API Keys Guide
For the separate key members use to connect to a hosted MCP server, see shared MCP key generation. That key is not a BytePlus provider key. The credentials below stay on the server and must not be distributed to shared-server members.
For administrator-managed BytePlus deployments, follow Secret Manager setup and provider-key updates. That workflow pins one complete four-provider bundle, requires an approved sync to update the VM, and preserves the separate shared MCP connection key. It does not manage IAM or object-storage credentials.
This server calls several BytePlus services. Each uses a distinct credential and auth scheme — they are not interchangeable. You only need the keys for the products you want to use; absent credentials simply skip registering that tool set.
| Service | Env var | Auth header | Tools it enables |
|---|---|---|---|
| ModelArk | BYTEPLUS_MODELARK_API_KEY |
Authorization: Bearer <key> |
Seedream, Seedance, image/video/audio understanding, and gated 3D tools |
| Seed Speech | BYTEPLUS_SEED_SPEECH_API_KEY |
X-Api-Key: <key> |
Seed Audio (speech generation), Speech-to-Text (ASR) |
| VOD AI MediaKit | BYTEPLUS_VOD_MEDIAKIT_API_KEY |
Authorization: Bearer <key> |
Enhancement, transcode, subtitle burn-in/removal, audio separation, and poll tools |
| Vision AI (OmniHuman) | BYTEPLUS_CV_API_KEY |
Authorization: Bearer <key> |
omnihuman_* tools (also needs BYTEPLUS_OMNIHUMAN_ENABLED=true) |
| ModelArk OpenAPI | BYTEPLUS_MODELARK_ACCESS_KEY + BYTEPLUS_MODELARK_SECRET_KEY (+ session token for STS) |
AK/SK V4 signing | Asset tools, cached pricing, and opt-in ark_moderation_get; account-wide administration is local-only |
| TOS | TOS_ACCESS_KEY + TOS_SECRET_KEY + TOS_BUCKET |
AK/SK signing | media_upload, media_presign |
| S3 | S3_ACCESS_KEY + S3_SECRET_KEY + S3_BUCKET |
AK/SK signing | media_upload, media_presign |
With guided setup, your agent prepares a private blank credential file and opens it for you. Enter keys there, not in chat or MCP client JSON. You do not need to copy the full example configuration or configure services you do not use. If using a shared server, its operator manages provider keys; your client uses the operator’s connection credentials.
All keys below are startup configuration, never tool arguments. The examples are field-name references for that private file, not shell commands. Preserve existing files and keep credentials outside repositories and shared folders. See manual credential setup only when preparing the file yourself.
ModelArk
Section titled “ModelArk”ModelArk provides Seedream, Seedance, multimodal understanding and the gated 3D tools. The key is sent as a Bearer token.
Env vars:
| Variable | Default | Purpose |
|---|---|---|
BYTEPLUS_MODELARK_API_KEY |
empty | ModelArk API key |
BYTEPLUS_MODELARK_BASE_URL |
https://ark.ap-southeast.bytepluses.com/api/v3 |
Region-scoped data-plane host |
How to get the key:
- Sign in to the BytePlus console at https://console.byteplus.com.
- Open ModelArk (Ark) and navigate to API Key management.
- Create a new API key. Copy it immediately — it is shown once.
- (Optional) Create an inference endpoint for the Seedream or Seedance
model you want to use, then set its ID as
SEEDREAM_DEFAULT_MODELorSEEDANCE_DEFAULT_MODEL. The built-in defaults already have known families; a custom endpoint ID must be bound viaSEEDREAM_MODEL_BINDINGS/SEEDANCE_MODEL_BINDINGS.
BYTEPLUS_MODELARK_API_KEY=your-modelark-key-hereThe base URL is region-scoped. If your account is in a different region, update
BYTEPLUS_MODELARK_BASE_URL to match.
ModelArk OpenAPI (assets and moderation)
Section titled “ModelArk OpenAPI (assets and moderation)”Signed OpenAPI calls use BytePlus IAM AK/SK, not the ModelArk Bearer key.
Configure BYTEPLUS_MODELARK_ACCESS_KEY and BYTEPLUS_MODELARK_SECRET_KEY
together; temporary credentials also need BYTEPLUS_MODELARK_SESSION_TOKEN.
See asset configuration for the
OpenAPI host and signing region.
Moderation additionally needs BYTEPLUS_MODELARK_MODERATION_ENABLED=true
(default off), Advanced Creation Rights, whitelist activation and IAM
GetModerationResult. It is account-wide, foreground-only trusted stdio or
local-mode loopback access; moderation:read is never granted to shared HTTP.
AK/SK also configure asset tools and cached pricing. For a moderation-only IAM
policy, disable pricing refresh with BYTEPLUS_MODELARK_PRICING_REFRESH_SECONDS=0
and do not grant unrelated permissions. Discovery verifies configuration only;
live lookup success is unverified. See moderation.md.
Seed Speech
Section titled “Seed Speech”Seed Speech is the service for Seed Audio (full-scene audio generation /
TTS) and speech-to-text (ASR). A single Seed Speech API key covers
both capabilities — the provider distinguishes them by the
X-Api-Resource-Id header, not by the key. It is a separate key from
ModelArk and uses a different auth header (X-Api-Key, not Bearer).
Env vars:
| Variable | Default | Purpose |
|---|---|---|
BYTEPLUS_SEED_SPEECH_API_KEY |
empty | Seed Speech API key (Seed Audio + ASR) |
BYTEPLUS_SEED_AUDIO_BASE_URL |
https://voice.ap-southeast-1.bytepluses.com |
Seed Speech host |
SEED_SPEECH_ASR_BASE_URL |
https://voice.ap-southeast-1.bytepluses.com |
Seed Speech ASR host |
SEED_SPEECH_ASR_POLL_INTERVAL_SECONDS |
3.0 |
Seconds between ASR query polls |
SEED_SPEECH_ASR_POLL_MAX_SECONDS |
600.0 |
Maximum total seconds to wait for ASR result |
How to get the key:
- Sign in to https://console.byteplus.com.
- Open BytePlus Voice (or Seed Speech / Speech Studio).
- Navigate to API key or application management and create a key.
- Copy the key. It is distinct from your ModelArk key.
The key must belong to an application with access to the capability you use:
TTS for Seed Audio, and the ASR resource for speech_to_text. If a
capability is not enabled on the application, provider calls for it are
rejected with an auth/resource error even though the key itself is valid.
BYTEPLUS_SEED_SPEECH_API_KEY=your-seed-speech-key-hereSeed Speech ASR (Speech-to-Text)
Section titled “Seed Speech ASR (Speech-to-Text)”Speech-to-text (ASR) reuses BYTEPLUS_SEED_SPEECH_API_KEY — the same key
that powers Seed Audio. When the key is set, the speech_to_text tool is
registered automatically; it submits audio via HTTP, polls until
transcription is complete, and returns the full TranscriptionResult through
a required background job, submitted through the ordinary ark_job_* tools or
native MCP task augmentation on a task-capable client.
The ASR-specific settings below only control the host and polling behavior, not the credential.
Env vars:
| Variable | Default | Purpose |
|---|---|---|
SEED_SPEECH_ASR_BASE_URL |
https://voice.ap-southeast-1.bytepluses.com |
Seed Speech ASR HTTP host |
SEED_SPEECH_ASR_POLL_INTERVAL_SECONDS |
3.0 |
Seconds between ASR query polls |
SEED_SPEECH_ASR_POLL_MAX_SECONDS |
600.0 |
Maximum total seconds to wait for ASR result |
BytePlus VOD (AI MediaKit)
Section titled “BytePlus VOD (AI MediaKit)”BytePlus VOD AI MediaKit is a single Bearer-authenticated convenience surface
that powers video enhancement, video transcoding, subtitle burn-in/removal, and
voice + background audio separation. All six vod_* tools share the same API key.
Env vars:
| Variable | Default | Purpose |
|---|---|---|
BYTEPLUS_VOD_MEDIAKIT_API_KEY |
empty | VOD AI MediaKit Bearer key |
BYTEPLUS_VOD_MEDIAKIT_BASE_URL |
https://mediakit.ap-southeast-1.bytepluses.com/api/v1 |
MediaKit base URL |
How to get the key:
- Sign in to https://console.byteplus.com and enable BytePlus VOD.
- Open the AI MediaKit console and navigate to API key management.
- Create an API key and copy it immediately — it is shown once.
BYTEPLUS_VOD_MEDIAKIT_API_KEY=your-mediakit-key-hereThe key is sent as Authorization: Bearer <key> against
https://mediakit.ap-southeast-1.bytepluses.com/api/v1. It is startup
configuration only and is never logged, returned, or accepted as a tool
argument.
BytePlus Vision AI (OmniHuman)
Section titled “BytePlus Vision AI (OmniHuman)”Env vars:
| Variable | Default | Purpose |
|---|---|---|
BYTEPLUS_CV_API_KEY |
empty | Vision AI Bearer key |
BYTEPLUS_OMNIHUMAN_ENABLED |
false |
Registers the omnihuman_* tools |
BYTEPLUS_CV_BASE_URL |
https://openapi.cv.bytepluses.com |
Vision AI base URL |
Create the key under Access Key Management in the BytePlus console and make
sure the account has OmniHuman 2.0 enabled. The same service also accepts
AK/SK-signed requests on cv.byteplusapi.com; this server uses the API-key
path only.
Object storage (TOS or S3)
Section titled “Object storage (TOS or S3)”Object storage is optional but enables several workflows: the media_upload and
media_presign tools and Seedance video references
(URL-only). It uses Access Key / Secret Key (AK/SK) signing, not a bearer
token. Select the backend with OBJECT_STORAGE_BACKEND (tos default, or
s3).
TOS backend
Section titled “TOS backend”Env vars:
| Variable | Default | Purpose |
|---|---|---|
TOS_ACCESS_KEY |
empty | Access Key (AK) |
TOS_SECRET_KEY |
empty | Secret Key (SK) |
TOS_SECURITY_TOKEN |
empty | Optional temporary token (STS only) |
TOS_BUCKET |
empty | Target bucket name |
TOS_REGION |
ap-southeast-1 |
Bucket region |
TOS_ENDPOINT |
tos-ap-southeast-1.bytepluses.com |
TOS API endpoint |
TOS_PRESIGN_TTL_SECONDS |
1800 |
Presigned URL validity in seconds (60–604800) |
TOS_ACCESS_KEY and TOS_SECRET_KEY must both be set or both be
empty. All three of AK, SK, and bucket must be set to register the
media_upload and media_presign tools.
How to get the keys:
- Sign in to https://console.byteplus.com.
- Open TOS (Object Storage).
- Create a bucket (keep it private) in your target region. Note the
bucket name and region — set them as
TOS_BUCKETandTOS_REGION. - For the access keys: open IAM (Identity and Access Management) and create an access key pair (AK + SK) for a user or service account that has read/write permission on that bucket. Copy both immediately — the SK is shown once.
TOS_ACCESS_KEY=your-access-keyTOS_SECRET_KEY=your-secret-keyTOS_BUCKET=your-private-bucketTOS_REGION=ap-southeast-1TOS_ENDPOINT=tos-ap-southeast-1.bytepluses.comSecurity notes:
- Keep the bucket private. The server never makes objects public; it
generates short-lived presigned GET URLs (default 30 minutes, configurable via
TOS_PRESIGN_TTL_SECONDS) for individual objects. - Uploaded objects are not auto-deleted by this server. Configure a TOS
bucket lifecycle rule to expire objects under the upload prefixes
(
stt-input/,references/) to control storage cost over time. - For temporary credentials (STS), also set
TOS_SECURITY_TOKEN.
S3 backend
Section titled “S3 backend”| Variable | Default | Purpose |
|---|---|---|
S3_ACCESS_KEY |
empty | S3 access key ID |
S3_SECRET_KEY |
empty | S3 secret access key |
S3_BUCKET |
empty | Target bucket name |
S3_REGION |
us-east-1 |
AWS region |
S3_ENDPOINT |
empty | Custom endpoint for S3-compatible storage |
S3_PRESIGN_TTL_SECONDS |
1800 |
Presigned URL validity in seconds (60–604800) |
OBJECT_STORAGE_BACKEND |
tos |
Select active backend: tos or s3 |
S3_ACCESS_KEY and S3_SECRET_KEY must both be set or both be
empty. All three of AK, SK, and bucket must be set to register the
media_upload and media_presign tools with the S3
backend.
When S3_ENDPOINT is set, path-style addressing is used automatically for
S3-compatible storage (MinIO, R2, TOS-via-boto3).
Verifying your setup
Section titled “Verifying your setup”After saving the private file, reconnect Ark through your client’s MCP settings, taking care to finish active jobs first. The client starts the server automatically. Use the discovery-only connection check; do not start development mode just to test keys.
The seed-health://status MCP resource reports ModelArk configured,
Seed Audio configured, STT configured, TOS configured, S3 configured,
and Object storage backend values per
provider. The separate /health HTTP route is a liveness probe that returns
only {"status": "healthy"}. A disabled service may have a missing key or
feature flag. Ask your setup agent to check names and the configured
ARK_MCP_ENV_FILE path without reading or printing key values.
If a tool is missing entirely, its provider credentials were absent at startup. Tools are registered conditionally based on which keys are present. Discovery confirms configuration, not provider-key validity or account access.
Quick reference
Section titled “Quick reference”# ModelArk — image + videoBYTEPLUS_MODELARK_API_KEY=BYTEPLUS_MODELARK_BASE_URL=https://ark.ap-southeast.bytepluses.com/api/v3
# Seed Speech — Seed Audio (TTS) + ASR (STT), one keyBYTEPLUS_SEED_SPEECH_API_KEY=BYTEPLUS_SEED_AUDIO_BASE_URL=https://voice.ap-southeast-1.bytepluses.com
# Seed Speech ASR — host + polling only (reuses the key above)SEED_SPEECH_ASR_BASE_URL=https://voice.ap-southeast-1.bytepluses.comSEED_SPEECH_ASR_POLL_INTERVAL_SECONDS=3.0SEED_SPEECH_ASR_POLL_MAX_SECONDS=600.0
# BytePlus VOD — AI MediaKit (Bearer)BYTEPLUS_VOD_MEDIAKIT_API_KEY=BYTEPLUS_VOD_MEDIAKIT_BASE_URL=https://mediakit.ap-southeast-1.bytepluses.com/api/v1
# Object storage — TOS (optional, default backend)TOS_ACCESS_KEY=TOS_SECRET_KEY=TOS_BUCKET=TOS_REGION=ap-southeast-1TOS_ENDPOINT=tos-ap-southeast-1.bytepluses.comTOS_PRESIGN_TTL_SECONDS=1800
# Object storage — S3 (optional alternative backend)S3_ACCESS_KEY=S3_SECRET_KEY=S3_BUCKET=S3_REGION=us-east-1S3_ENDPOINT=S3_PRESIGN_TTL_SECONDS=1800OBJECT_STORAGE_BACKEND=tosConsole: https://console.byteplus.com Docs: https://docs.byteplus.com