Configuration
Configuration is loaded from environment variables or .env by Pydantic
Settings. Copy .env.example to .env. Empty values are ignored.
.env is resolved relative to the server’s working directory. Most MCP
clients set that correctly from their server configuration, so this is rarely
the problem. When a client cannot, it finds no .env, and the server starts
with no provider credentials and registers only the always-on job and artifact
tools — set ARK_MCP_ENV_FILE to an absolute path for that case, or launch the
server with its working directory at the repository root (for example
uv --directory /path/to/ark-mcp run python -m ark_mcp). The server logs a
no_provider_credentials_configured warning at startup when it happens; if a
client is missing tools and that warning is absent, look at
troubleshooting instead.
| Variable | Default | Purpose |
|---|---|---|
ARK_MCP_ENV_FILE |
.env |
Absolute path to the env file, for clients that cannot control the working directory |
Providers and models
Section titled “Providers and models”| Variable | Default | Purpose |
|---|---|---|
BYTEPLUS_MODELARK_API_KEY |
empty | Enables Seedream, Seedance, and Seed 2.1 understanding; sent as Bearer auth |
BYTEPLUS_SEED_SPEECH_API_KEY |
empty | Enables Seed Audio and speech-to-text; sent as X-Api-Key |
BYTEPLUS_VOD_MEDIAKIT_API_KEY |
empty | Enables MediaKit enhancement, transcode, subtitle burn-in/removal, audio-separation, and poll tools; sent as Bearer auth |
BYTEPLUS_CV_API_KEY |
empty | BytePlus Vision AI Bearer key for OmniHuman; tools also need BYTEPLUS_OMNIHUMAN_ENABLED=true |
BYTEPLUS_MODELARK_BASE_URL |
AP Southeast ModelArk URL | HTTPS data-plane base URL |
BYTEPLUS_SEED_AUDIO_BASE_URL |
AP Southeast Seed Speech URL | HTTPS service base URL |
BYTEPLUS_VOD_MEDIAKIT_BASE_URL |
https://mediakit.ap-southeast-1.bytepluses.com/api/v1 |
HTTPS VOD AI MediaKit convenience-endpoint base URL |
SEEDREAM_DEFAULT_MODEL |
dola-seedream-5-5-261028 |
Default image model/endpoint ID (Seedream 5.5; account authorization required) |
SEEDREAM_PROMPT_OPTIMIZATION_MODE |
standard |
Mode 5.0 Pro sends when a caller omits prompt_optimization: standard (prompt-following quality) or fast (lower latency). Both are provider-accepted; an explicit per-call value wins |
SEEDANCE_DEFAULT_MODEL |
dreamina-seedance-2-5-260628 |
Default video model/endpoint ID used by seedance_create_task when model is omitted (Seedance 2.5; was 2.0 before the tool consolidation, see the upgrade note) |
SEED_UNDERSTANDING_DEFAULT_MODEL |
dola-seed-2-1-turbo-260628 |
Default understanding model/endpoint ID. Set to dola-seed-evolving to use the latest Pro-tier model (auto-resolves to family pro, no SEED_UNDERSTANDING_MODEL_FAMILY needed) |
SEEDREAM_MODEL_FAMILY |
empty | Family for a custom default: seedream_5_5, pro, lite, or 4x |
SEEDANCE_MODEL_FAMILY |
empty | Family for a custom default: standard, fast, mini, seedance_2_5 (through 4K), or seedance_2_5_flash (480p/720p, no Draft) |
SEED_UNDERSTANDING_MODEL_FAMILY |
empty | Family for a custom default: pro or turbo |
SEEDREAM_MODEL_BINDINGS |
empty | JSON list of {model_id, family} bindings |
SEEDANCE_MODEL_BINDINGS |
empty | JSON list of {model_id, family} bindings |
SEED_UNDERSTANDING_MODEL_BINDINGS |
empty | JSON list of {model_id, family} bindings |
SEED_AUDIO_UNDERSTANDING_MODEL |
seed-2-0-lite-260428 |
Model/endpoint ID used by seed_audio_understand. Any ModelArk model that accepts Chat Completions input_audio parts with deep thinking works; change it when a newer audio-capable model ships |
BYTEPLUS_MODELARK_3D_ENABLED |
false |
Feature flag for 3D generation (Hyper3D + Hitem3d); reuses the ModelArk key, disabled by default |
HYPER3D_DEFAULT_MODEL |
hyper3d-gen2 |
Default Hyper3D model/endpoint ID |
HITEM3D_DEFAULT_MODEL |
hitem3d-2-0 |
Default Hitem3d model/endpoint ID |
SEED3D_MODEL_BINDINGS |
empty | JSON list of {model_id, family} bindings (hyper3d or hitem3d) |
BYTEPLUS_OMNIHUMAN_ENABLED |
false |
Feature flag for OmniHuman 2.0 (omnihuman_* tools); requires BYTEPLUS_CV_API_KEY |
BYTEPLUS_CV_BASE_URL |
https://openapi.cv.bytepluses.com |
HTTPS Vision AI base URL |
BYTEPLUS_OMNIHUMAN_REQ_KEY |
realman_avatar_picture_omni20_cv |
Service identifier sent as req_key; change only if BytePlus issues a new one |
The recognized built-in IDs have known families. A custom ID must be bound explicitly; the server does not infer capabilities from substrings in an ID. For example:
SEEDREAM_DEFAULT_MODEL=my-image-endpointSEEDREAM_MODEL_BINDINGS=[{"model_id":"my-image-endpoint","family":"pro"}]Seedream default model upgrade note
Section titled “Seedream default model upgrade note”The default is now Seedream 5.5 (dola-seedream-5-5-261028).
This changes only deployments that omit SEEDREAM_DEFAULT_MODEL; existing
explicit defaults stay unchanged. Discovery reflects configured models, not
provider authorization. Accounts without 5.5 access should retain 5.0 Pro:
SEEDREAM_DEFAULT_MODEL=dola-seedream-5-0-pro-260628Both built-in IDs resolve without a family setting. For a custom 5.5 endpoint,
set SEEDREAM_MODEL_FAMILY=seedream_5_5. If SEEDREAM_MODEL_BINDINGS contains
only older models and no explicit default, startup fails until the default is
set to a bound ID or a 5.5 binding is added. To offer both:
SEEDREAM_DEFAULT_MODEL=dola-seedream-5-5-261028SEEDREAM_MODEL_BINDINGS=[{"model_id":"dola-seedream-5-5-261028","family":"seedream_5_5"},{"model_id":"dola-seedream-5-0-pro-260628","family":"pro"}]5.5 uses PNG output when omitted and accepts transparent text-to-image.
SEEDREAM_PROMPT_OPTIMIZATION_MODE remains specific to 5.0 Pro; explicit
prompt_optimization="standard" is accepted on 5.5, while fast is rejected
even when the Pro-only operator setting is fast. Omitted 5.5 optimization
uses the provider’s standard default. Background defaults to auto on 5.5.
See image model limits.
Read seed-health://status to confirm the effective Seedream default model and
binding family. The resource also reports whether background-job local exports
have an absolute OUTPUT_ROOTS entry (comma-separated paths). It never reveals
root paths or credentials. These are configuration diagnostics only: they do not
probe provider authorization, check filesystem readiness, or replace the
request’s destination preflight. Client MCP roots are unavailable inside jobs.
Seedream dry-run preview.price_source distinguishes a cached account image
rate (catalog) from the built-in fallback (builtin); neither is actual billing.
Seedance default model upgrade note
Section titled “Seedance default model upgrade note”SEEDANCE_DEFAULT_MODEL now defaults to Seedance 2.5
(dreamina-seedance-2-5-260628) instead of 2.0. Every Seedance model is
called through the single seedance_create_task tool, and the default model
must be one of the bound IDs.
| Your configuration | Result after upgrading |
|---|---|
No SEEDANCE_MODEL_BINDINGS, no SEEDANCE_DEFAULT_MODEL |
Regular Seedance 2.5 and Flash are bound automatically; regular 2.5 is the default |
SEEDANCE_DEFAULT_MODEL set explicitly, bindings empty |
The selected model remains the default; Flash is also bound unless it is the selected default |
SEEDANCE_MODEL_BINDINGS lists only a Seedance 2.0 model and SEEDANCE_DEFAULT_MODEL is unset |
Startup fails with Seedance default model 'dreamina-seedance-2-5-260628' is missing from its bindings. Set the default model env var to one of the bound IDs: [...] |
Fix for the failing case: set SEEDANCE_DEFAULT_MODEL to the bound 2.0 ID
to keep 2.0 as the default, or add a 2.5 binding to use the new default:
# Keep Seedance 2.0 as the defaultSEEDANCE_DEFAULT_MODEL=dreamina-seedance-2-0-260128SEEDANCE_MODEL_BINDINGS=[{"model_id":"dreamina-seedance-2-0-260128","family":"standard"}]
# Or bind both and default to 2.5SEEDANCE_MODEL_BINDINGS=[{"model_id":"dreamina-seedance-2-0-260128","family":"standard"},{"model_id":"dreamina-seedance-2-5-260628","family":"seedance_2_5"}]Callers then choose a model per request with model, taking an exact ID from
ark_list_models(kind='video').
Seedance 2.5 4K
Section titled “Seedance 2.5 4K”All resolutions use dreamina-seedance-2-5-260628 and family seedance_2_5.
Select resolution="4k" on seedance_create_task; no extra feature flag,
model binding, or tool is needed.
The separate Premium model, family, service entry, and configuration settings
have been removed without a compatibility layer. Remove
BYTEPLUS_MODELARK_SEEDANCE_2_5_PREMIUM_ENABLED and SEEDANCE_2_5_PREMIUM_MODEL
from configuration and replace any seedance_2_5_premium binding with the
current 2.5 model and family. There is no automatic alias or rerouting of old
model IDs.
Draft previews remain 480p and Draft-to-final rendering remains 1080p; 4K currently applies to ordinary generation, not Draft promotion. Static video cost previews do not account for resolution or duration.
Seedance 2.5 Flash
Section titled “Seedance 2.5 Flash”Flash uses dreamina-seedance-2-5-flash-261115, family seedance_2_5_flash,
through the same seedance_create_task tool, ModelArk key, host, and task
lifecycle. It supports 480p/720p, 4-30 seconds, 10 image / 5 video / 5 audio
references, audio-only input, reference/edit/extend task types, and MP4/MOV.
It does not support 1080p, 4K, draft, or draft_task_id.
With empty bindings, Flash is added alongside the selected default. Regular
2.5 remains the default for omitted model. A non-empty
SEEDANCE_MODEL_BINDINGS remains authoritative; add Flash explicitly there:
SEEDANCE_MODEL_BINDINGS=[{"model_id":"dreamina-seedance-2-5-260628","family":"seedance_2_5"},{"model_id":"dreamina-seedance-2-5-flash-261115","family":"seedance_2_5_flash"}]To use a custom Flash endpoint, bind its ID to seedance_2_5_flash. Listing
the model does not prove provider activation or account entitlement. No new
feature flag is required. Flash cost previews currently reuse the static
2.5 per-task fallback, not its token-based provider price.
Credentials are startup-only. If a provider key is absent, its tools are not
registered. Specifically, vod_enhance_video is registered independently
when BYTEPLUS_VOD_MEDIAKIT_API_KEY is non-empty; it does not require the
ModelArk key. Provider base URLs must use HTTPS, include a hostname, and must
not contain embedded credentials.
Transport and authentication
Section titled “Transport and authentication”| Variable | Default | Purpose |
|---|---|---|
MCP_TRANSPORT |
stdio |
stdio or Streamable http |
MCP_HOST |
127.0.0.1 |
HTTP bind address |
MCP_PORT |
3000 |
HTTP listen port |
MCP_ALLOWED_HOSTS |
loopback hosts | Comma-separated accepted Host headers |
MCP_ALLOWED_ORIGINS |
empty | Comma-separated accepted browser Origins |
MCP_HTTP_MAX_BODY_BYTES |
314572800 (300 MiB) |
Maximum HTTP request body; sized to inline the largest supported Base64 media upload (200 MiB video inflates ~4/3x). A smaller value logs a warning at startup (large inlined uploads will 413). |
READINESS_CHECK_PROVIDERS |
false |
When true, /ready also checks provider connectivity |
READINESS_PROVIDER_TIMEOUT_SECONDS |
2.0 |
Per-provider timeout for readiness checks |
RATE_LIMIT_RPM |
0 |
Max HTTP requests per minute per client IP; 0 disables |
RATE_LIMIT_BURST |
0 |
Token bucket burst size; 0 defaults to RATE_LIMIT_RPM |
RATE_LIMIT_TRUST_PROXY_HEADERS |
false |
Trust the first X-Forwarded-For entry for rate-limit keys; enable only behind a trusted proxy |
MCP_AUTH_MODE |
local |
local or api_key; Docker, Compose and Terraform default to api_key |
MCP_API_KEY_SHA256 |
empty | Required for api_key: lowercase SHA-256 hex digest of the shared MCP key, never the raw key |
FASTMCP_TRANSPORT, FASTMCP_HOST, and FASTMCP_PORT are accepted as
aliases for the corresponding MCP_* transport settings.
local auth is accepted only for stdio or loopback HTTP. Binding HTTP to a
non-loopback address fails closed unless api_key mode and a valid digest
are configured. API key mode assigns one shared-team tenant/principal
with ordinary tool permissions, a shared budget and shared data access, excluding
account-wide admin scopes. See shared-key setup and rotation.
The internal tenant claim key is fixed to tenant_id, not an operator setting.
FastMCP enforces the fixed ordinary scope allowlist:
seed:audio:generateseedream:generateseedance:creategen:read,gen:delete(gen_task_*tools for Seedance and 3D tasks)seed:asr:transcribeunderstanding:readhyper3d:create,hitem3d:createomnihuman:create,omnihuman:read,omnihuman:cancelvod:enhancevod:transcodevod:subtitle:addvod:subtitle:removevod:readvod:extractmedia:uploadmedia:presignartifacts:read
Breaking change: jwt mode is rejected. Retired MCP_JWT_*,
MCP_TENANT_CLAIM and MCP_PUBLIC_BASE_URL settings are not used.
There is no automatic ownership transfer. Preserve SQLite, Redis, artifacts
and the snapshot encryption key; follow
the migration procedure.
Seed Speech ASR (STT)
Section titled “Seed Speech ASR (STT)”The speech_to_text tool is registered when BYTEPLUS_SEED_SPEECH_API_KEY is
set — the same key that enables Seed Audio (TTS). It submits audio via HTTP,
polls until transcription is complete, and returns the complete
TranscriptionResult through a required background job, submitted through the
ordinary ark_job_* tools or native MCP task augmentation on a task-capable
client. Audio input accepts
URL, Base64, or a local file path (stdio only).
| Variable | Default | Purpose |
|---|---|---|
BYTEPLUS_SEED_SPEECH_API_KEY |
empty | Enables Seed Audio + speech-to-text; sent as X-Api-Key header |
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 |
Fixed team scope for speech-to-text:
seed:asr:transcribe
VOD AI MediaKit
Section titled “VOD AI MediaKit”vod_enhance_video is registered when BYTEPLUS_VOD_MEDIAKIT_API_KEY is
set. The tool supports the fast, standard, and professional enhancement
tiers with target resolutions from 240p to 8K (4K for fast) and defaults to
professional/4k/high/24 fps. It serializes the project label upstream as
case-sensitive Project for standard/professional. Submission returns an asynchronous
task ID and operation="enhance" for vod_get_task, the single MediaKit
poller, which returns and best-effort persists completed outputs. The submit POST is not retried automatically.
Convenience-endpoint pricing is not yet confirmed, so the tool does not emit a
cost estimate.
vod_transcode_video and vod_get_task are also registered when
BYTEPLUS_VOD_MEDIAKIT_API_KEY is set. vod_transcode_video submits an async
transcoding task (codec, container format, scaling, bitrate, frame rate, HDR);
vod_get_task with operation="transcode" polls it and best-effort persists
the completed output.
The transcode request/status contract is verified from the official AI MediaKit
API reference; the output URL hostname (*.byteplusvod.com) is confirmed and
trusted for durable persistence. queue_id/Project request params remain
unverified and are not exposed.
vod_add_subtitles and vod_remove_subtitles (polled with vod_get_task,
operation="add_subtitles" or "remove_subtitles") use the same API key.
Addition accepts a public HTTPS SRT, VTT, or ASS file or inline timed cues and
burns them into the output video. Removal defaults to dialogue-subtitle mode;
the broader text mode may also erase titles, labels, or watermarks. Both
submit asynchronously, use client_token to reconcile ambiguous submissions,
and preserve the provider URL when optional durable persistence is skipped or
fails. The optional project and removal model_version fields are legacy
convenience-endpoint extensions and are omitted unless explicitly supplied.
VOD AI MediaKit audio separation
Section titled “VOD AI MediaKit audio separation”vod_separate_audio and vod_get_task are registered when
BYTEPLUS_VOD_MEDIAKIT_API_KEY is set, sharing the same Bearer-authenticated
convenience surface as enhancement and transcoding.
vod_separate_audio submits a POST /api/v1/tools/separate-voice task from a
public HTTPS audio_url or video_url (exactly one) plus an optional scene
(Audio default, Music, Drama, Narrate) and output_format (aac
default, mp3, wav, m4a, flac). vod_get_task with
operation="separate_audio" polls GET /api/v1/tasks/{task_id} and returns
each separated track (voice, background, music, sfx) as an output with
its expiring source_url (valid 24 hours) plus a durable artifact reference
when best-effort persistence succeeds. An output_path directory receives
every track.
Private asset library (AK/SK)
Section titled “Private asset library (AK/SK)”The ark_asset_* tools are registered only when both
BYTEPLUS_MODELARK_ACCESS_KEY and BYTEPLUS_MODELARK_SECRET_KEY are set; they
do not need BYTEPLUS_MODELARK_API_KEY. Seedance asset:// references need
only the API key. See assets.md.
| Variable | Default | Description |
|---|---|---|
BYTEPLUS_MODELARK_ACCESS_KEY |
empty | BytePlus IAM access key (AKLT… long-term or AKTP… STS) for signed ModelArk OpenAPI calls |
BYTEPLUS_MODELARK_SECRET_KEY |
empty | Matching secret key; must be set together with the access key |
BYTEPLUS_MODELARK_SESSION_TOKEN |
empty | STS session token, required for AKTP… keys (sent as signed X-Security-Token) |
BYTEPLUS_MODELARK_PRICING_REFRESH_SECONDS |
86400 |
Background account-price refresh interval when AK/SK exists; 0 disables. Values below 60 seconds are clamped to 60; snapshots expire after twice the effective interval |
BYTEPLUS_MODELARK_OPENAPI_BASE_URL |
https://ark.ap-southeast-1.byteplusapi.com |
ModelArk OpenAPI host (HTTPS) |
BYTEPLUS_MODELARK_REGION |
ap-southeast-1 |
Signing region |
BYTEPLUS_MODELARK_PROJECT_NAME |
default |
Default project for groups and assets; must match the inference endpoint’s project |
BYTEPLUS_MODELARK_ASSETS_ALLOW_DELETE |
false |
Registers the irreversible ark_asset_delete tool (assets and groups) |
BYTEPLUS_MODELARK_ASSET_CREATE_QPM |
3 |
Client-side CreateAsset pacing; set to your tier (3 Entry, 120 Advanced, 300 Premium) |
BYTEPLUS_MODELARK_ASSET_VERIFY_CALLBACK_URL |
empty | Default HTTPS redirect for real-person verification |
BYTEPLUS_MODELARK_ASSET_REFERENCE_MODE |
off |
Seedream / Seed Audio asset:// handling: off rejects, resolve swaps in the temporary asset URL (experimental; needs AK/SK) |
SEEDANCE_ASSET_PREFLIGHT |
true |
With AK/SK, check asset:// references with GetAsset before a billed Seedance submit |
Account-wide asset scopes (assets:read, assets:write, assets:verify,
assets:delete) are excluded from shared-key HTTP. Use trusted local stdio
for asset administration; configuring AK/SK does not grant remote access.
Moderation lookup (AK/SK, opt-in)
Section titled “Moderation lookup (AK/SK, opt-in)”| Variable | Default | Description |
|---|---|---|
BYTEPLUS_MODELARK_MODERATION_ENABLED |
false |
Registers foreground-only ark_moderation_get when complete ModelArk AK/SK is configured |
Reuses the OpenAPI host, signing region and AK/SK above; temporary credentials
also need BYTEPLUS_MODELARK_SESSION_TOKEN. A ModelArk Bearer key is not required.
The account needs Advanced Creation Rights, whitelist activation and IAM
GetModerationResult. Discovery’s moderation service and health’s
Moderation lookup configured report configuration only, not entitlement.
This is account-wide trusted stdio/local-mode loopback access, not tenant-scoped
access. moderation:read is not granted to shared-key HTTP, even with the flag
enabled. AK/SK also register asset tools and enable the pricing refresher;
for isolated lookup set BYTEPLUS_MODELARK_PRICING_REFRESH_SECONDS=0, without
broadening a moderation-only IAM policy. The fixed ten-lookups-per-rolling-minute
guard is independent of HTTP rate limits; live success remains unverified.
See moderation.md for eligibility, validation and quota bounds.
Object storage (TOS or S3, optional)
Section titled “Object storage (TOS or S3, optional)”The media_upload and media_presign tools are registered when the selected
object-storage backend is configured. media_upload uploads 1-50 files to a
private bucket and returns a presigned HTTPS GET URL per file;
media_presign generates fresh presigned URLs for 1-100 existing objects
without re-uploading.
Use OBJECT_STORAGE_BACKEND to select tos (default) or s3.
| Variable | Default | Purpose |
|---|---|---|
MEDIA_UPLOAD_BATCH_MAX_BYTES |
524288000 (500 MiB) |
Maximum total decoded bytes in one media_upload call (all items); checked before any upload starts, and an oversized call fails as a whole |
TOS backend
Section titled “TOS backend”| Variable | Default | Purpose |
|---|---|---|
TOS_ACCESS_KEY |
empty | TOS access key (AK) |
TOS_SECRET_KEY |
empty | TOS secret key (SK) |
TOS_SECURITY_TOKEN |
empty | Optional temporary security token |
TOS_BUCKET |
empty | Target bucket name |
TOS_REGION |
ap-southeast-1 |
TOS region |
TOS_ENDPOINT |
tos-ap-southeast-1.bytepluses.com |
TOS API endpoint |
TOS_PRESIGN_TTL_SECONDS |
1800 |
Presigned URL validity in seconds (60–604800) |
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 (MinIO, R2) |
S3_PRESIGN_TTL_SECONDS |
1800 |
Presigned URL validity in seconds (60–604800) |
OBJECT_STORAGE_BACKEND |
tos |
Select active backend: tos or s3 |
AK and SK must both be set or both be empty. The bucket must remain private;
presigned URLs grant temporary read access to individual objects. When
S3_ENDPOINT is set, path-style addressing is used automatically for
S3-compatible storage.
Persistence and runtime policy
Section titled “Persistence and runtime policy”| Variable | Default | Purpose |
|---|---|---|
ARTIFACT_BACKEND |
filesystem |
filesystem (local disk) or object_storage (TOS/S3) |
STATE_BACKEND |
sqlite |
Task ownership/budget/cache backend; only sqlite (single instance) is implemented |
ARTIFACT_DIR |
~/.ark-mcp/artifacts |
Media, metadata, ownership, and budget state |
ARTIFACT_TTL_SECONDS |
604800 |
Artifact retention, in seconds |
ARTIFACT_SWEEP_INTERVAL_SECONDS |
3600 |
Interval between background artifact/state expiry sweeps |
STATE_PRUNE_MAX_AGE_DAYS |
30 |
Max age for ownership/budget/cache rows before pruning; at least 14 for authenticated HTTP with regular Seedance 2.5 enabled |
MCP_INLINE_MEDIA_MAX_BYTES |
8388608 |
Maximum inline MCP media size |
ARTIFACT_DOWNLOAD_TIMEOUT_SECONDS |
120 |
Timeout for each attempt to download provider output into artifact storage (filesystem and object-storage backends) |
ARTIFACT_DOWNLOAD_MAX_ATTEMPTS |
3 |
Attempts (1-10) for a retryable output download (timeouts, network errors, 408/429/5xx), with 1s, 2s, 4s, … backoff. Expired, untrusted, or oversized sources are never retried |
ARTIFACT_INLINE_FALLBACK_MAX_BYTES |
8388608 (8 MiB) |
When inline Base64 output (Seed Audio, Seedream b64_json) cannot be stored, return it inline in ArtifactRef.fallback_data up to this decoded size; 0 disables |
PROVIDER_MAX_CONCURRENCY |
5 |
Process-wide slots per provider |
PRINCIPAL_MAX_CONCURRENCY |
3 |
Shared slots across the whole team on authenticated HTTP; skipped in local mode |
DAILY_BUDGET_USD |
0 |
Per-principal UTC daily estimate limit, team-wide on shared-key HTTP; zero records only |
PERSISTENCE_CACHE_MAX_SIZE |
10000 |
Max cached provider task IDs in artifact-resolution cache |
PERSISTENCE_CACHE_TTL_SECONDS |
86400 |
TTL for cached task-to-artifact mappings (seconds) |
Authenticated HTTP servers with ModelArk credentials and any regular
seedance_2_5 binding (including custom or non-default models) require
STATE_PRUNE_MAX_AGE_DAYS >= 14 to retain Draft ownership throughout the
promotion window. Shorter values fail at startup; increase existing overrides
or keep the 30-day default. Flash-only, legacy-only, local, and disabled
ModelArk configurations retain the one-day minimum. Increasing retention does
not recover already-pruned ownership rows; missing ownership remains denied.
A billed output is never dropped because storage failed; see Artifacts.
The filesystem backend enforces principal and tenant ownership. It is suitable for one process. Multiple replicas require shared artifact, task-ownership, budget, cache, and limiter implementations before horizontal scaling is safe.
Local output paths
Section titled “Local output paths”| Variable | Default | Purpose |
|---|---|---|
OUTPUT_ROOTS |
empty | Comma-separated absolute directories where stdio tools may write files (output_path, output_dir, save_to, destination_path) |
The client’s MCP roots (roots/list) take precedence when the client provides
them; OUTPUT_ROOTS is the fallback. With neither, local path writing is
disabled and those fields are rejected. Background jobs
(ark_job_submit) run in a worker with no MCP session and therefore no MCP
roots, so local writes from a job always use OUTPUT_ROOTS; set it whenever
jobs should write files. Path writing is stdio-only. See
Security.
Timeouts and logging
Section titled “Timeouts and logging”| Variable | Default | Purpose |
|---|---|---|
BYTEPLUS_CONNECT_TIMEOUT_MS |
10000 |
Provider connection timeout |
BYTEPLUS_REQUEST_TIMEOUT_MS |
600000 |
Full provider request timeout |
SEED_UNDERSTANDING_TIMEOUT_MS |
unset (uses BYTEPLUS_REQUEST_TIMEOUT_MS) |
Request timeout for seed_understand and seed_audio_understand chat completions. Deep thinking is always on, so long analyses may need more than the general request timeout |
FASTMCP_DOCKET_URL |
memory:// |
FastMCP background-task backend used by generation, transcription, upload, provider submission, understanding, and optional media-persistence calls; Redis can retain task state across restarts of the same single-replica deployment; it does not make SQLite state horizontally scalable |
FASTMCP_TASKS_ENCRYPTION_KEY |
unset | Required for API-key-authenticated Redis task backends; use at least 32 random characters and keep the same key across restarts |
FASTMCP_DOCKET_CONCURRENCY |
10 |
Maximum active background tasks per worker; provider/principal limits still apply |
ARK_LOG_LEVEL |
INFO |
DEBUG, INFO, WARNING, or ERROR |
Logs are structured JSON on stderr. Provider credentials and sensitive media fields are redacted. The default in-memory task backend is process-local; a server restart discards active and retained task state.
Background task ownership and recovery
Section titled “Background task ownership and recovery”Keep the runtime database with the queue. MCP task ownership is persisted in
runtime.sqlite3 using the fixed tenant_id claim key and principal. Every
tasks/get, tasks/update, and tasks/cancel request checks that owner.
Missing identity or ownership fails closed in api_key mode. All shared-key
members use the same shared-team owner, including after key rotation.
One shared server process gives all of its clients one queue: in local auth
mode every loopback client is the same local/local principal, so a job
submitted by one client is visible to the others. This remains single-instance
state; see transports.md.
Before a required-task handler starts, it atomically records an execution claim in the same database. If that MCP task is delivered again, the handler returns an error without repeating provider work. This favors avoiding duplicate charges over automatic recovery: after an interrupted submission, reconcile its provider outcome before creating a new operation. Optional output-retrieval tasks can be retried because they do not submit paid generation work.
The default in-memory queue still loses task results at process exit. With Redis,
retain the runtime database, backend, and encryption key together, and run only
one application replica. Snapshot encryption protects caller credentials and
HTTP headers stored by FastMCP; Redis must also restrict access to task arguments
and results, which may contain media URLs and prompts. rediss:// protects the
connection and does not replace snapshot encryption. A wrong or missing key
cannot decrypt existing encrypted snapshots. See deployment.md.