API Reference
Complete schemas, inputs, outputs, and examples for the conditional MCP tool surface.
Hosted HTTP requires the shared MCP key on every tool call, including
discovery. Its fixed ordinary scopes apply to all members as tenant/principal
shared-team; ownership, budgets and permitted cancellations are team-wide.
Account-wide asset and moderation administration is not available over
shared-key HTTP, even if provider credentials register those tools. Use trusted
local stdio for administration. Provider credentials listed below remain
server-side and are separate from the MCP key.
Tool Inventory
Section titled “Tool Inventory”The catalog contains 39 tools; configuration gates and caller permissions determine the visible inventory.
| # | Tool | Product | Type | Auth |
|---|---|---|---|---|
| 1 | ark_list_models |
Discovery | Read-only | No extra tool scope |
| 2 | seed_audio_generate |
Seed Audio | Required background task | Seed Speech |
| 3 | seedream_generate_image |
Seedream | Required background task | ModelArk |
| 4 | seedance_create_task |
Seedance (every configured model; 2.5 supports 4K) | Required background submission | ModelArk |
| 5 | hyper3d_create_task |
Hyper3D (optional) | Required background submission | ModelArk |
| 6 | hitem3d_create_task |
Hitem3d (optional) | Required background submission | ModelArk |
| 7 | seed_understand |
Seed 2.1 (optional) | Required background task | ModelArk |
| 8 | seed_audio_understand |
Seed audio understanding (optional) | Required background task | ModelArk |
| 9 | speech_to_text |
Seed Speech ASR (optional) | Required background task | Seed Speech |
| 10 | gen_task_get |
ModelArk generation tasks | Optional background retrieval | ModelArk |
| 11 | gen_task_list |
ModelArk generation tasks | Read-only | ModelArk |
| 12 | gen_task_cancel_or_delete |
ModelArk generation tasks | Destructive | ModelArk |
| 13 | vod_enhance_video |
VOD AI MediaKit (optional) | Required background submission | MediaKit Bearer |
| 14 | vod_transcode_video |
VOD AI MediaKit (optional) | Required background submission | MediaKit Bearer |
| 15 | vod_separate_audio |
VOD AI MediaKit (optional) | Required background submission | MediaKit Bearer |
| 16 | vod_add_subtitles |
VOD AI MediaKit (optional) | Required background submission | MediaKit Bearer |
| 17 | vod_remove_subtitles |
VOD AI MediaKit (optional) | Required background submission | MediaKit Bearer |
| 18 | vod_get_task |
VOD AI MediaKit (optional) | Optional background retrieval | MediaKit Bearer |
| 19 | omnihuman_create_task |
OmniHuman 2.0 (flag-gated) | Required background submission | Vision AI Bearer |
| 20 | omnihuman_get_task |
OmniHuman 2.0 (flag-gated) | Optional background retrieval | Vision AI Bearer |
| 21 | omnihuman_cancel_task |
OmniHuman 2.0 (flag-gated) | Destructive | Vision AI Bearer |
| 22 | seed_media_get_artifact |
Artifacts | Read-only | Local / shared key |
| 23 | seed_media_export_artifact |
Artifacts | Locate (read-only) or copy (stdio only) | Local stdio |
| 24 | seed_media_persist_url |
Artifacts | Optional background task | Local / shared key |
| 25 | media_upload |
Object storage (optional) | Required background task (1-50 files) | TOS / S3 |
| 26 | media_presign |
Object storage (optional) | Read-only (1-100 keys) | TOS / S3 |
| 27 | ark_asset_group_ensure |
Asset library (optional) | Write | BytePlus AK/SK |
| 28 | ark_asset_group_list |
Asset library (optional) | Read-only | BytePlus AK/SK |
| 29 | ark_asset_create |
Asset library (optional) | Optional background task | BytePlus AK/SK |
| 30 | ark_asset_list |
Asset library (optional) | Read-only | BytePlus AK/SK |
| 31 | ark_asset_update |
Asset library (optional) | Write | BytePlus AK/SK |
| 32 | ark_asset_verification_start |
Asset library (optional) | Write | BytePlus AK/SK |
| 33 | ark_asset_verification_result |
Asset library (optional) | Optional background retrieval | BytePlus AK/SK |
| 34 | ark_asset_delete |
Asset library (optional) | Destructive (opt-in) | BytePlus AK/SK |
| 35 | ark_job_capabilities |
Background jobs | Read-only ordinary tool | Local / shared key |
| 36 | ark_job_submit |
Background jobs | Default background submission path | Dynamic target scope |
| 37 | ark_job_get |
Background jobs | Read-only ordinary tool | Owner only |
| 38 | ark_job_cancel |
Background jobs | Destructive ordinary tool | Owner only |
| 39 | ark_moderation_get |
Moderation (opt-in) | Foreground-only read | Flag + BytePlus AK/SK; trusted local only |
Tools removed or merged in 0.2 are listed in the migration guide.
seedream_generate_image is the only Seedream tool: registered whenever
BYTEPLUS_MODELARK_API_KEY is set, it requires seedream:generate in api_key mode.
seed_audio_generate covers single and parallel audio and requires
seed:audio:generate.
seedance_create_task serves every configured
Seedance model (pick one from ark_list_models(kind='video')), is registered
whenever BYTEPLUS_MODELARK_API_KEY is set, and requires seedance:create in
api_key mode. Seedance 2.5 supports 4K through resolution="4k" on the same model;
no additional tool, model, or feature flag is needed.
The three gen_task_* tools poll, list, and cancel or delete every ModelArk
generation task (Seedance, Hyper3D, and Hitem3d). They are registered whenever
ModelArk is configured, independent of BYTEPLUS_MODELARK_3D_ENABLED, and
require gen:read (gen_task_get, gen_task_list) or gen:delete
(gen_task_cancel_or_delete) in api_key mode. vod_get_task polls every VOD AI
MediaKit task, is registered when BYTEPLUS_VOD_MEDIAKIT_API_KEY is set, and
requires vod:read. media_upload takes a list of files (media:upload)
and media_presign takes a list of keys (media:presign); both are
registered when object storage is configured. The eight ark_asset_* tools
are registered only when BYTEPLUS_MODELARK_ACCESS_KEY and
BYTEPLUS_MODELARK_SECRET_KEY are set (see Asset Library).
ark_moderation_get also needs BYTEPLUS_MODELARK_MODERATION_ENABLED=true;
its account-wide moderation:read label is not a shared HTTP permission.
See security.md for the full scope list.
Tool Annotations
Section titled “Tool Annotations”| Tool | readOnly | destructive | idempotent | openWorld |
|---|---|---|---|---|
ark_list_models |
true | false | true | false |
seed_audio_generate |
false | false | false | true |
seedream_generate_image |
false | false | false | true |
seedance_create_task |
false | false | false | true |
gen_task_get |
false | false | true | false |
gen_task_list |
true | false | true | false |
gen_task_cancel_or_delete |
false | true | false | true |
media_upload |
false | false | false | true |
media_presign |
true | false | true | false |
seed_understand |
false | false | false | true |
seed_audio_understand |
false | false | false | true |
seed_media_get_artifact |
true | false | true | false |
seed_media_export_artifact |
false | false | true | false |
speech_to_text |
true | false | true | false |
vod_enhance_video |
false | false | false | true |
vod_transcode_video |
false | false | false | true |
vod_separate_audio |
false | false | false | true |
vod_add_subtitles |
false | false | false | true |
vod_remove_subtitles |
false | false | false | true |
vod_get_task |
false | false | true | false |
hyper3d_create_task |
false | false | false | true |
hitem3d_create_task |
false | false | false | true |
omnihuman_create_task |
false | false | false | true |
omnihuman_get_task |
false | false | true | true |
omnihuman_cancel_task |
false | true | false | true |
ark_job_capabilities |
true | false | true | false |
ark_job_submit |
false | false | false | true |
ark_job_get |
true | false | true | false |
ark_job_cancel |
false | true | false | true |
seed_media_persist_url |
false | false | false | true |
ark_asset_group_ensure |
false | false | true | true |
ark_asset_group_list |
true | false | true | true |
ark_asset_create |
false | false | false | true |
ark_asset_list |
true | false | true | true |
ark_asset_update |
false | false | true | true |
ark_asset_verification_start |
false | false | false | true |
ark_asset_verification_result |
true | false | true | true |
ark_asset_delete |
false | true | true | true |
ark_moderation_get |
true | false | true | true |
seed_understand and seed_audio_understand are not read-only because save_to
writes local files, and the task pollers (gen_task_get and vod_get_task) are
not read-only because output_dir/output_path write local files.
Background Execution
Section titled “Background Execution”Generation tools (seed_audio_generate, seedream_generate_image, including
their variations and dry runs), speech_to_text, media_upload,
seed_understand, seed_audio_understand, and all Seedance, Seed 3D, and
MediaKit provider-submission tools declare execution.taskSupport="required". By default, discover them
with ark_job_capabilities, submit them through ark_job_submit, and poll
ark_job_get at the advertised two-second interval until terminal. A
task-capable client may instead invoke them with MCP task metadata and read the
result from the tasks/get response. Foreground direct calls to those target
tools fail before the provider is contacted.
In this reference, background result means the original tool result under
terminal ark_job_get.result, or the terminal tasks/get response on the
native path.
The task pollers gen_task_get (Seedance and Seed 3D) and vod_get_task
(MediaKit), and seed_media_persist_url, declare
execution.taskSupport="optional" because a processing-status check is short,
but a successful response with persist_output=true may download a large
artifact. Use foreground execution with persistence disabled for quick polling,
then background execution to retrieve and persist completed output. Both
pollers default to persist_output=false, so a plain foreground call is a
status poll; pass persist_output=true only through ark_job_submit (or
native task augmentation). ark_asset_create and
ark_asset_verification_result also declare execution.taskSupport="optional"
because wait_until_active and wait_seconds can poll for minutes. List,
presign, artifact-read, the other asset tools, and cancel/delete tools remain
foreground operations.
ark_moderation_get is foreground-only, excluded from both ark_job_submit
and native task augmentation; it never persists lookup results.
The ordinary background-job tools, usable on any MCP client:
ark_job_capabilities()returns the configured, scope-filtered targets and each target’s original input schema.ark_job_submit({"tool_name": name, "arguments": original_arguments})durably enqueues the same registered task-enabled tool and returns a server-generated Arkjob_id.ark_job_get({"job_id": id})returnsworkingor a terminal snapshot. On completion,resultpreserves the original MCP tool result.ark_job_cancel({"job_id": id})cooperatively cancels the local job.
The ordinary path uses the same worker, target schema validation, target-scope check, tenant/principal ownership, replay claim, budget, concurrency, metrics, and provider adapter as native task augmentation. Ark job IDs and provider task IDs are separate identifiers.
Local Output Paths
Section titled “Local Output Paths”On stdio transport, these fields write output straight to a local file:
output_path on seedream_generate_image, seed_audio_generate, and
vod_get_task; output_dir on gen_task_get; save_to on seed_understand
and seed_audio_understand; and destination_path on
seed_media_export_artifact. Each comes with an overwrite boolean (default
false).
| Rule | Behavior |
|---|---|
| Transport | stdio only; rejected on HTTP |
| Path form | Absolute. output_path names a file, or a directory when it ends with / (files named <artifact_id>.<ext>) |
| Allowed roots | Client MCP roots (roots/list) first, otherwise OUTPUT_ROOTS; with neither, path writing is disabled. Inside ark_job_submit there are no MCP roots, so OUTPUT_ROOTS is required |
| Timing | Validated before any provider call |
| Preconditions | persist=true (generation tools) or persist_output=true (task pollers); a directory is required for seedream_generate_image with variations > 1 or max_images > 1, seed_audio_generate with variations > 1, and vod_get_task with operation="separate_audio" |
| Existing files | Replaced only with overwrite=true; identical content is success |
| Failure | A failed local write never fails the call; see ArtifactRef.local_path / export_error |
gen_task_get writes every persisted output of each succeeded task (video,
last frame, or 3D model file) into output_dir as <artifact_id>.<ext>.
vod_get_task with separate_audio writes every separated track into the
output_path directory.
seedream_generate_image and seed_audio_generate with variations > 1 write
every succeeded variation into the output_path directory (see
summary.variations[].artifact.local_path).
Shared Types
Section titled “Shared Types”MediaSource
Section titled “MediaSource”A media reference by URL or Base64.
| Field | Type | Required | Description |
|---|---|---|---|
kind |
"url" | "base64" |
Yes | Source type |
url |
string | If kind=url | HTTPS URL |
data |
string | If kind=base64 | Base64-encoded data |
mime_type |
string | No | MIME type |
Seedance image/audio inputs and the Seedream / Seed Audio images /
image_reference inputs (ReferenceImageInput) also accept
url: "asset://<asset_id>" for private asset library assets. Seedance passes
it through natively; Seedream and Seed Audio require
BYTEPLUS_MODELARK_ASSET_REFERENCE_MODE=resolve. See assets.md.
AudioReference
Section titled “AudioReference”An audio reference for voice cloning.
| Field | Type | Required | Description |
|---|---|---|---|
kind |
"speaker" | "url" | "base64" |
Yes | Reference mode |
speaker_id |
string | If kind=speaker | Preset speaker ID |
url |
string | If kind=url | Reference audio URL, or asset://<asset_id> (resolve mode only) |
data |
string | If kind=base64 | Base64 audio data (WAV preflight-checked against 30s limit) |
mime_type |
string | No | MIME type |
ArtifactRef
Section titled “ArtifactRef”A durable reference to persisted media.
| Field | Type | Description |
|---|---|---|
id |
string | Unique artifact ID, or provider-url / inline-fallback when the output could not be stored |
uri |
string | seed-media://artifacts/{id}, or the temporary provider URL when id="provider-url" |
media_type |
"image" | "audio" | "video" | "three_d" |
Logical type |
mime_type |
string | e.g. image/png, audio/wav, video/mp4 |
bytes |
integer | Size in bytes |
sha256 |
string | SHA-256 hex digest |
created_at |
string | ISO-8601 timestamp |
expires_at |
string | Local artifact expiry |
source_expires_at |
string | Provider URL expiry (2h audio, 24h image/video/3D) |
persistence_error |
ArtifactPersistenceIssue | null | Set when the output was generated (and billed) but could not be stored durably |
fallback_data |
string | null | Base64 output bytes, only for id="inline-fallback" (up to ARTIFACT_INLINE_FALLBACK_MAX_BYTES) |
local_path |
string | null | Absolute local path written for output_path/output_dir |
export_error |
string | null | Why the requested local copy was not written; the durable artifact is unaffected |
ArtifactPersistenceIssue
Section titled “ArtifactPersistenceIssue”| Field | Type | Description |
|---|---|---|
code |
string | untrusted_output_host, output_too_large, invalid_output_mime, source_expired, download_failed, or storage_failed |
message |
string | Credential- and URL-safe failure message |
retryable |
boolean | Whether persistence may succeed if attempted again |
artifact_limit_bytes |
integer | Maximum size accepted by the durable artifact policy |
source_url_expires_at |
string | null | When the unpersisted provider URL (the artifact’s uri) expires |
Recover a provider-url artifact with seed_media_persist_url before
source_url_expires_at.
VariationResult
Section titled “VariationResult”Result of a single variation within a parallel generation.
| Field | Type | Description |
|---|---|---|
index |
integer | 0-based variation index |
seed |
integer | null | Seed used (image only) |
artifact |
ArtifactRef | null | Generated artifact (null if failed) |
task_id |
string | null | Provider task ID for Seedance polling, obtained from the enclosing background result |
error |
VariationError | null | Error details if failed |
request_id |
string | null | Provider request ID |
provider_log_id |
string | null | Provider log ID (Seed Audio) |
VariationError
Section titled “VariationError”| Field | Type | Description |
|---|---|---|
code |
string | Error code, e.g. QUEUE_TIMEOUT, TIMEOUT, GATHER_ERROR, a provider code, or an upper-cased persistence code |
message |
string | Human-readable message |
request_id |
string | null | Provider request ID, if available |
retryable |
boolean | Whether the variation may succeed if retried |
ambiguous_completion |
boolean | Whether the provider may have completed despite the error |
phase |
"queued" | "generating" | "persisting" | null |
Stage at failure: queued never started (safe to retry), generating provider call in flight, persisting output generated but not stored |
VariationSummary
Section titled “VariationSummary”Aggregate result of a parallel generation.
| Field | Type | Description |
|---|---|---|
total |
integer | Total variations requested |
succeeded |
integer | Variations that produced output |
failed |
integer | Variations that failed |
variations |
list[VariationResult] | Per-variation results |
1. ark_list_models
Section titled “1. ark_list_models”List the models this server is configured to call, with per-model limits,
and report which optional services are enabled. Call it before any generation
or understanding tool: their model argument accepts only the exact
model_id values listed here. Always registered, needs no scope, and makes
no provider calls.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
kind |
string | No | — | Filter to one model kind: video, image, 3d, or understanding. Omit to list every configured kind |
Output
Section titled “Output”| Field | Type | Description |
|---|---|---|
models |
list[ModelInfo] | Configured models matching the filter |
pricing_status |
"live" | "unavailable" |
Whether a fresh account catalog snapshot is cached |
pricing_note |
string | null | Safe explanation when prices are unavailable |
services |
list[ServiceStatus] | Enablement of each optional service |
ModelInfo: model_id (exact ID to pass as model), family, kind,
is_default (used when model is omitted), tool (the tool that accepts the
model), and one limits object matching the kind: video (resolutions,
duration_seconds range, ratios, reference counts, Draft support, task types,
output formats), image (reference count, output formats, batch support,
sizes, transparent background), seed3d (text-to-3D support, reference count,
file formats, seed support), or understanding (modalities, media-part limit,
thinking support, reasoning efforts, response formats).
Each ModelInfo also has nullable pricing with catalog_name, display_name,
available, and charge_items (charge_type, price, list_price, unit).
Prices are account-specific catalog rates populated by the background refresher
when AK/SK is configured. Discovery makes no network calls; stale or unmatched
prices are null. See Runtime.
Understanding modalities and media limits describe the named tool, not
every possible use of the underlying model. The seed_audio_understand
entry advertises only audio (up to eight clips); it has no model argument.
Even when audio and visual defaults share an ID, use seed_understand for
images/videos. Neither route supports mixed audio/visual requests.
ServiceStatus: service, enabled, and reason (the env var or flag that
enables a disabled service; never a secret value). Services: modelark,
seed3d, seed_audio, speech_to_text,
vod_mediakit, omnihuman, object_storage, asset_library, asset_delete,
moderation. The last reports flag + AK/SK configuration, not whitelist
activation, IAM permission, model coverage or shared-key access.
Example
Section titled “Example”{"kind": "video"}2. seed_audio_generate
Section titled “2. seed_audio_generate”Generate full-scene audio through Seed Speech: one clip, or up to five
independent variations in parallel. Requires seed:audio:generate in api_key
mode. Required background task: run it through ark_job_submit (or native
task augmentation).
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
text_prompt |
string | No* | — | 1-3000 chars |
variations |
integer | No | 1 |
1-5 parallel generations |
variation_prompts |
list[string] | No | — | Exactly variations entries (each 1-3000 chars); overrides text_prompt |
audio_references |
list[AudioReference] | No | [] |
Max 3 |
image_reference |
ReferenceImageInput | No | — | Mutually exclusive with audio |
output |
AudioOutputOptions | No | — | Format, rate, pitch |
watermark |
AudioWatermarkOptions | No | — | AIGC watermark |
persist |
boolean | No | true |
Persist to artifact store |
output_path |
string | No | — | Local file or directory (ending /); must be a directory when variations > 1; stdio only, requires persist=true |
overwrite |
boolean | No | false |
Replace existing files at output_path |
* Provide text_prompt or variation_prompts.
Variations: Seed Audio has no seed, so variations differ only by the
model’s sampling. Partial failures are reported per variation in summary
rather than failing the call.
AudioOutputOptions
Section titled “AudioOutputOptions”| Field | Type | Default | Constraints |
|---|---|---|---|
format |
"wav" | "mp3" | "pcm" | "ogg" |
— | — |
sample_rate |
integer | — | 8000-48000 |
speech_rate |
integer | — | -50 to 100 |
loudness_rate |
integer | — | -50 to 100 |
pitch_rate |
integer | — | -12 to 12 |
subtitle |
boolean | — | — |
subtitle_type |
"utterance" | "word" |
— | — |
Output
Section titled “Output”Returns SeedAudioGenerateOutput for both single calls and variations.
| Field | Type | Description |
|---|---|---|
provider |
"byteplus-seed-speech" |
Fixed |
model |
"seed-audio-1.0" |
Fixed |
duration_seconds |
float | null | Output duration; null when variations > 1 |
billing_duration_seconds |
float | null | Billed duration; null when variations > 1 |
artifact |
ArtifactRef | null | Persisted audio; null when variations > 1 |
subtitle |
Subtitle | null | Optional subtitles |
request_id |
string | null | Request ID |
provider_log_id |
string | null | X-Tt-Logid |
source_url |
string | null | Provider URL (2-hour expiry) |
summary |
VariationSummary | null | Per-variation artifacts and errors when variations > 1; null otherwise |
Examples
Section titled “Examples”// Single clip (arguments.input){ "text_prompt": "Welcome to BytePlus.", "output": { "format": "wav", "sample_rate": 44100 }}
// Background result{ "provider": "byteplus-seed-speech", "model": "seed-audio-1.0", "duration_seconds": 2.5, "billing_duration_seconds": 2.5, "artifact": { "id": "5828e515-...", "uri": "seed-media://artifacts/5828e515-...", "media_type": "audio", "mime_type": "audio/wav", "bytes": 2656078 }, "request_id": "", "provider_log_id": "20260721...", "summary": null}// Three variations (arguments.input){ "text_prompt": "Hello world", "variations": 3 }
// Background result{ "provider": "byteplus-seed-speech", "model": "seed-audio-1.0", "duration_seconds": null, "billing_duration_seconds": null, "artifact": null, "summary": { "total": 3, "succeeded": 3, "failed": 0, "variations": [ { "index": 0, "artifact": { "id": "...", "media_type": "audio", ... } }, { "index": 1, "artifact": { "id": "...", "media_type": "audio", ... } }, { "index": 2, "artifact": { "id": "...", "media_type": "audio", ... } } ] }}3. seedream_generate_image
Section titled “3. seedream_generate_image”The only Seedream tool: text-to-image, image-to-image and reference
editing, point/bbox edits, provider batches (max_images), parallel variations,
and dry runs. Registered whenever BYTEPLUS_MODELARK_API_KEY is set; requires
seedream:generate in api_key mode. Required background task: run it through
ark_job_submit (or native task augmentation).
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
prompt |
string | No* | — | 1-4000 chars, including any point/bbox markup. With images, it is the edit instruction |
images |
list[ReferenceImageInput] | No | — | Reference or source images (URL, Base64, or asset://); per-model maximum checked at runtime |
point |
EditCoordinate | No | — | x, y in 0-999 (normalized) on the first image; requires images |
bbox |
EditBbox | No | — | x1, y1, x2, y2 in 0-999 on the first image, x1 <= x2, y1 <= y2; requires images |
model |
string | No | SEEDREAM_DEFAULT_MODEL |
Exact configured ID from ark_list_models(kind='image') |
size |
string | No | 2K on 5.5 |
5.5: 1K, 1.5K, 2K, or positive WIDTHxHEIGHT with 921600-4624220 pixels and ratio 1/16-16, inclusive. No generation auto; older families remain provider-validated |
seed |
integer | No | — | -1 to 2147483647; undocumented compatibility field on 5.5, omit unless verified; the base seed when variations > 1 (see below) |
max_images |
integer | No | — | 1-15 images from one provider call; batch-capable models only. Cannot be combined with variations > 1 |
output_format |
"png" | "jpeg" |
No | png on 5.5 and transparent output; provider default otherwise |
Model-dependent |
response_format |
"url" | "b64_json" |
No | — | Base64 requires persist=true; the unusable combination is rejected even for dry runs, before submission |
watermark |
boolean | No | — | AIGC watermark |
prompt_optimization |
"standard" | "fast" |
No | standard on 5.5; operator setting on Pro |
5.5 rejects fast; Pro accepts both. Omitted 5.5 mode uses the provider default |
background |
"auto" | "opaque" | "transparent" |
No | auto on 5.5; opaque otherwise |
auto is 5.5-only; JPEG always opaque in auto mode. Transparent output requires PNG. 5.5 accepts text or references without alpha; Pro needs exactly one already-transparent PNG |
safety_identifier |
string | No | — | 5.5/Pro: 1-64 non-space printable ASCII characters; use a stable hashed user ID, not personal data. Redacted in previews and logs |
variations |
integer | No | 1 |
1-10 independent parallel generations |
variation_prompts |
list[string] | No | — | Exactly variations entries (each 1-4000 chars); overrides prompt |
persist |
boolean | No | true |
Persist as durable MCP resources |
dry_run |
boolean | No | false |
Validate and return preview; no provider call, nothing billed |
output_path |
string | No | — | Local file, or directory ending /; must be a directory when variations > 1 or max_images > 1; stdio only, requires persist=true |
overwrite |
boolean | No | false |
Replace existing files at output_path |
* Provide prompt or variation_prompts.
Unknown input fields are rejected, including layer-decomposition/OCR controls; only generation and editing are supported.
Point and bbox edits. The tool prepends coordinate markup to every prompt
(including each variation prompt): Image 1<bbox>x1 y1 x2 y2</bbox> and/or
Image 1<point>x y</point>, bbox first when both are set. The 4000-character
limit applies to the final prompt.
Seed behavior. Seedream 5.5 does not document this compatibility field;
omit it unless provider acceptance is verified. A single call (variations=1)
sends an explicitly supplied seed as-is. With
variations > 1, seed is the base seed:
seed |
Per-variation seeds |
|---|---|
| omitted | Provider randomizes each (not recorded) |
-1 |
Client picks a random seed per variation (recorded in summary) |
N |
N, N+1, N+2, ... (modulo 2147483648) |
Variations. Each variation is its own provider call; partial failures are
reported per variation in summary rather than failing the call.
Runtime Validation
Section titled “Runtime Validation”Model limits are checked before any provider call against the resolved
model’s capabilities. All violations are returned in one error that ends
with Call ark_list_models(kind='image') for per-model limits. Checks:
reference image count, output_format, size, max_images > 1 without batch
support, prompt_optimization support, and the background="transparent"
rules.
Built-in family limits (ark_list_models(kind='image') is authoritative):
| Family | Max references | max_images batch |
output_format |
prompt_optimization |
Transparent background |
|---|---|---|---|---|---|
5.5 (default dola-seedream-5-5-261028) |
10 | No (use variations) |
png (default), jpeg | standard only (provider default) |
Text-only and reference-based |
Pro (Seedream 5.0 Pro, dola-seedream-5-0-pro-260628) |
10 | No (use variations) |
png, jpeg | Yes (default SEEDREAM_PROMPT_OPTIMIZATION_MODE) |
Existing transparent PNG only |
| Lite | 14 | Yes | png, jpeg | Yes | No |
| 4.x | 14 | Yes | jpeg | Yes | No |
Discovery’s image limits include supports_transparent_generation and
supports_prompt_optimization, named size tiers, custom pixel/ratio bounds,
background_modes, prompt_optimization_modes, and supports_safety_identifier.
5.5 requires account authorization; see the
default upgrade note.
Examples below that return a 5.0 Pro model ID assume Pro is configured explicitly.
Output
Section titled “Output”Returns SeedreamGenerateOutput, the same shape for single calls,
variations, and dry runs:
| Field | Type | Description |
|---|---|---|
provider |
"byteplus-modelark" |
Fixed |
model |
string | Resolved model ID |
created_at |
string | ISO-8601 |
dry_run |
boolean | true when nothing was generated; see preview |
artifacts |
list[ArtifactRef] | Images from a single call (variations=1); an image that could not be stored is returned as a provider-url or inline-fallback reference with persistence_error. Empty for variations and dry runs |
item_errors |
list[SeedreamItemError] | Single-call errors (index, code, message): NO_OUTPUT for empty/missing output, NO_DELIVERABLE_OUTPUT for unexpected Base64-only output with persist=false |
usage |
SeedreamUsage | null | Single-call usage: legacy token fields plus input_images, generated_images, output_tokens; null for variations and dry runs |
summary |
VariationSummary | null | Per-variation index, seed, artifact or error, and request_id when variations > 1 |
generations |
list[SeedreamGenerationMetadata] | Completed provider calls ordered by variation_index (0 for single calls); provenance, provider reports and advisory image inspections, described below. Empty on dry runs |
preview |
SeedreamGeneratePreview | null | Set only for a dry run |
Per-call provenance and image metadata:
| Field | Description |
|---|---|
request_id |
Provider request ID, or null when absent; available for single calls and variations |
seed |
Submitted seed. Single-call -1/null means provider randomness, not a recovered actual seed |
prompt_sha256 |
SHA-256 of the exact UTF-8 submitted prompt, including server-added point/bbox markup |
request_options |
Submitted size, formats, watermark, background, optimization and batch maximum when present, plus reference count. Excludes prompt, media and safety identifier; omitted options are not inferred |
usage, safety_identifier |
Provider usage and identifier echo; absent values remain null |
images[] |
Provider-data index, matching artifact_id, provider-reported size, output_format, background and independent inspection |
images[].inspection |
null for URL-only delivery; otherwise status, decoded width/height, byte-detected output_format, actual has_transparency and safe issues |
Inspection states are verified, mismatch, invalid, or unavailable.
verified means byte checks passed, not visual approval. Mismatches and
inspection failures retain billed artifacts and do not overwrite provider reports
or trigger another generation. See image inspection.
Variations report missing/undeliverable outputs as explicit errors in summary.
SeedreamGeneratePreview:
| Field | Type | Description |
|---|---|---|
requests |
list[object] | Provider request bodies, one per variation. Reference URLs are reduced to scheme and host, Base64 to its size, and safety_identifier redacted |
estimated_cost_usd |
number | Cached account rate or built-in fallback estimate; not actual billing or a provider quote |
price_source |
"catalog" | "builtin" |
catalog: fresh cached account image rate; builtin: missing, stale or unsupported rate fallback. Dry runs never fetch pricing |
Examples
Section titled “Examples”// Text-to-image, via ark_job_submit{ "tool_name": "seedream_generate_image", "arguments": { "input": { "prompt": "A serene mountain landscape at sunset", "size": "2048x2048", "seed": 42, "output_format": "jpeg" } }}
// Background result{ "provider": "byteplus-modelark", "model": "dola-seedream-5-0-pro-260628", "created_at": "2026-07-21T05:36:04+00:00", "dry_run": false, "artifacts": [ { "id": "83ef8c61-...", "uri": "seed-media://artifacts/83ef8c61-...", "media_type": "image", "mime_type": "image/jpeg", "bytes": 428968 } ], "item_errors": [], "usage": { "total_tokens": 4096 }, "summary": null, "preview": null}// Edit a region of the first image (arguments.input){ "prompt": "Replace the object with a crown", "images": [{ "kind": "url", "url": "https://example.com/frame.png", "mime_type": "image/png" }], "bbox": { "x1": 100, "y1": 100, "x2": 400, "y2": 400 }}// Prompt sent: "Image 1<bbox>100 100 400 400</bbox> Replace the object with a crown"// Edit an image with transparency on Seedream 5.0 Pro (arguments.input){ "model": "dola-seedream-5-0-pro-260628", "prompt": "Turn the circle into a glossy ceramic button, keep the background transparent", "images": [{ "kind": "url", "url": "https://example.com/circle-transparent.png", "mime_type": "image/png" }], "background": "transparent", "output_format": "png"}// Three variations with a base seed (arguments.input){ "model": "dola-seedream-5-0-pro-260628", "prompt": "A futuristic city skyline, cyberpunk", "variations": 3, "seed": 42, "output_path": "/Users/me/out/"}
// Background result{ "provider": "byteplus-modelark", "model": "dola-seedream-5-0-pro-260628", "created_at": "2026-07-21T...", "dry_run": false, "artifacts": [], "item_errors": [], "usage": null, "summary": { "total": 3, "succeeded": 3, "failed": 0, "variations": [ { "index": 0, "seed": 42, "artifact": { "id": "16cfa323-...", ... } }, { "index": 1, "seed": 43, "artifact": { "id": "86f189f2-...", ... } }, { "index": 2, "seed": 44, "artifact": { "id": "6f5978c9-...", ... } } ] }, "preview": null}// Dry run (arguments.input){ "prompt": "A lighthouse at dusk", "variations": 2, "seed": 7, "dry_run": true }
// Background result{ "provider": "byteplus-modelark", "model": "dola-seedream-5-0-pro-260628", "created_at": "2026-07-21T...", "dry_run": true, "artifacts": [], "item_errors": [], "usage": null, "summary": null, "preview": { "requests": [ { "model": "dola-seedream-5-0-pro-260628", "prompt": "A lighthouse at dusk", "seed": 7, "stream": false, "optimize_prompt_options": { "mode": "standard" } }, { "model": "dola-seedream-5-0-pro-260628", "prompt": "A lighthouse at dusk", "seed": 8, "stream": false, "optimize_prompt_options": { "mode": "standard" } } ], "estimated_cost_usd": 0.06, "price_source": "builtin" }}The estimated_cost_usd value above is illustrative only.
4. seedance_create_task
Section titled “4. seedance_create_task”One create tool for every configured Seedance model (2.0, 2.0 Fast, 2.0
Mini, 2.5, and 2.5 Flash): single tasks, up to five parallel variations,
Draft mode, and dry runs. Registered whenever BYTEPLUS_MODELARK_API_KEY is
set; requires seedance:create in api_key mode. Required background
submission: run it through ark_job_submit (or native task augmentation).
Poll the returned task IDs with gen_task_get.
Model Selection
Section titled “Model Selection”Set model to an exact configured ID from ark_list_models(kind='video');
every video model listed there names seedance_create_task as its tool. Omit
model to use SEEDANCE_DEFAULT_MODEL, which defaults to
dreamina-seedance-2-5-260628 (Seedance 2.5). Select resolution="4k" on
this same model or a configured 2.5 endpoint for retained server 4K acceptance.
Current model-specific provider docs list regular 2.5 only through 1080p;
see the contract caveat.
Flash uses dreamina-seedance-2-5-flash-261115 with seedance_2_5_flash
through this same tool. It is included when bindings are empty; explicit
binding lists must add it themselves. Regular 2.5 remains the default.
Discovery reports configured support, not account activation.
Family limits as shipped (ark_list_models(kind='video') is authoritative
for the models configured on a given server):
| Family | Resolutions | Duration (s) | Max images / videos / audios | Draft (final resolution) | Audio-only input | omni_reference_task_type |
output_format |
|---|---|---|---|---|---|---|---|
seedance_2 |
480p, 720p, 1080p, 4k | 4-15 | 9 / 3 / 3 | No | No | — | — |
seedance_2_fast |
480p, 720p | 4-15 | 9 / 3 / 3 | No | No | — | — |
seedance_2_mini |
480p, 720p | 4-15 | 9 / 3 / 3 | No | No | — | — |
seedance_2_5 |
480p, 720p, 1080p, 4k | 4-30 | 30 / 10 / 10 | Yes (1080p) | Yes | auto, reference, edit, extend |
mp4, mov |
seedance_2_5_flash |
480p, 720p | 4-30 | 10 / 5 / 5 | No | Yes | auto, reference, edit, extend |
mp4, mov |
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
prompt |
string | No* | — | 1-32,000 chars. Optional when media or variation_prompts are given |
images |
list[SeedanceImageInput] | No | — | Schema max 30; per-model max checked at runtime. Roles first_frame, last_frame, reference_image |
videos |
list[SeedanceVideoInput] | No | — | Schema max 10; per-model max checked at runtime |
audios |
list[SeedanceAudioInput] | No | — | Schema max 10; per-model max checked at runtime. 2.5 models accept audio-only input; 2.0 models need an image or video too |
model |
string | No | SEEDANCE_DEFAULT_MODEL |
Exact configured ID from ark_list_models(kind='video'). With draft_task_id, omit to reuse the Draft task’s model |
resolution |
"480p" | "720p" | "1080p" | "4k" |
No | — | Per-model set checked at runtime. draft=true allows only 480p (the default); draft_task_id allows only the model’s Draft final resolution (the default) |
ratio |
string | No | — | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, or adaptive (provider default). Edit, extend, first-frame, and first/last-frame requests on 2.5 require it omitted or adaptive |
duration |
integer | No | — | -1 (auto) or 4 up to the model max (15 for 2.0, 30 for 2.5). edit requires -1 or omitted |
omni_reference_task_type |
"auto" | "reference" | "edit" | "extend" |
No | — | 2.5 models only. edit/extend need at least one reference video |
output_format |
"mp4" | "mov" |
No | — | 2.5 models only. mov is H.264, YUV 4:4:4, PCM audio for post-production; some players cannot play it |
generate_audio |
boolean | No | — | Generate an audio track |
watermark |
boolean | No | false |
AIGC watermark |
return_last_frame |
boolean | No | — | Return the last frame as a separate image output |
execution_expires_after |
integer | No | — | 3600-259200 seconds |
priority |
integer | No | — | 0-9; model range checked at runtime |
safety_identifier |
string | No | — | Max 64 chars |
draft |
boolean | No | — | Draft step 1 (regular 2.5 only, not Flash): 480p preview billed as a normal 480p video. Mutually exclusive with draft_task_id |
draft_task_id |
string | No | — | Draft step 2: render a succeeded Draft task as the final video. See Draft Mode |
variations |
integer | No | 1 |
1-5. Each variation is a separate billed task |
variation_prompts |
list[string] | No | — | Exactly variations entries, each 1-32,000 chars; overrides prompt |
dry_run |
boolean | No | false |
Validate and return provider request bodies plus a cost estimate; nothing is submitted or billed |
* At least one of prompt, images, videos, or audios is required
(unless draft_task_id is set). variations > 1 needs prompt or
variation_prompts.
Runtime Validation
Section titled “Runtime Validation”The schema stays permissive; each request is checked against the resolved
model’s limits from the capability registry (resolution, ratio, duration
range, priority and expiry ranges, reference counts, Draft support,
audio-only input, task types, output_format). Every violation is returned
in one error before anything is submitted:
Request is not valid for model '<id>' (<family>):- <violation>- <violation>Call ark_list_models(kind='video') for per-model limits.asset:// references are preflighted against the private asset library
before submission, including on dry runs.
Auto-locked parameters by task type
Section titled “Auto-locked parameters by task type”When the provider detects (or is hinted via omni_reference_task_type)
that the task is video editing, extension, or first/last-frame generation,
certain parameters are auto-derived from the input media and cannot be
overridden:
| Task type | Aspect ratio | Duration |
|---|---|---|
| Video editing | Locked to input video’s ratio | Locked to input video’s duration (±0.3s) |
| Video extension | Locked to input video’s ratio | Set freely |
| First/last-frame generation | Locked to first image’s ratio | Set freely |
| Text-to-video / standard reference | Set freely | Set freely (or -1 for auto) |
Draft Mode
Section titled “Draft Mode”Two steps, regular Seedance 2.5 only; Flash rejects both Draft fields:
- Preview. Call with
draft: true.resolutionmust be omitted (becomes480p) or480p. Works withvariationsto compare several previews. - Final. Once a Draft has succeeded, call again with
draft_task_idset to itstask_id. The tool checks that the caller owns the task, that it succeeded, that it was created in Draft mode, and that it is within 14 days of creation (7 days if created before 2026-10-28 10:00 UTC+8).- The provider reuses the Draft’s model, prompt, media, duration, ratio,
seed,
generate_audio, andomni_reference_task_type, soprompt,images,videos,audios,duration,ratio,generate_audio,omni_reference_task_type, anddraftmust be omitted (they are rejected even when they match). modelmay be omitted (the Draft’s model is used); a different model is rejected.resolutionmust be omitted or the model’s Draft final resolution (1080pfor 2.5), which is the default. 4K applies to ordinary generation, not Draft promotion.return_last_frame,watermark,execution_expires_after,priority,safety_identifier, andoutput_formatmay be set again.- Requires
variations=1and novariation_prompts.
- The provider reuses the Draft’s model, prompt, media, duration, ratio,
seed,
Variations and Dry Run
Section titled “Variations and Dry Run”- Variations:
variations2-5 creates that many provider tasks in parallel. Partial failures are reported per entry intasks(witherror) rather than failing the call. - Dry run:
dry_run: trueruns all validation and returnspreviewinstead of submitting. Throughark_job_submit, a dry run finishes on the firstark_job_get. - Cost preview: static video estimates do not account for resolution or duration, including 4K; they are not provider quotes. Flash currently reuses the static 2.5 per-task fallback, not its token-based provider price.
SeedanceImageInput
Section titled “SeedanceImageInput”Extends MediaSource with a role field. A bare URL string,
"asset://<asset_id>", or {"url": "..."} is accepted and defaults to
role: "reference_image".
| Field | Type | Description |
|---|---|---|
role |
"first_frame" | "last_frame" | "reference_image" |
Image purpose |
SeedanceVideoInput
Section titled “SeedanceVideoInput”Video references are URL-only. Unlike image and audio references, there is no
Base64 path — videos must be uploaded to a publicly reachable HTTPS endpoint
before the tool is called, or referenced as asset://<asset_id> for an Active
private Video asset. Use the media_upload tool to upload Base64 or a local
file (stdio only) to object storage (TOS or S3) and receive a presigned HTTPS
GET URL. Alternatively, host the video on your own HTTPS endpoint. The URL
must resolve to a public IP (loopback, private, and link-local addresses are
rejected by the SSRF policy). A bare URL string or {"url": "..."} is
accepted.
| Field | Type | Description |
|---|---|---|
kind |
"url" |
Always url (hard-coded) |
url |
string | Public HTTPS URL of the reference video, or asset://<asset_id> |
role |
"reference_video" |
Always reference_video |
SeedanceAudioInput
Section titled “SeedanceAudioInput”Extends MediaSource; also accepts a bare URL string, "asset://<asset_id>",
or {"url": "..."}.
| Field | Type | Description |
|---|---|---|
role |
"reference_audio" |
Always reference_audio |
Output
Section titled “Output”Returns SeedanceCreateTaskOutput, the same shape for single requests,
variations, and dry runs:
| Field | Type | Description |
|---|---|---|
model |
string | Resolved model ID |
family |
string | Resolved model family (e.g. seedance_2_5) |
dry_run |
boolean | true when nothing was submitted; see preview |
tasks |
list[SeedanceTaskRef] | One entry per requested variation, in order; empty for a dry run |
submitted |
integer | Tasks the provider accepted |
failed |
integer | Submissions that failed |
recommended_poll_after_ms |
integer | null | Suggested delay before the first gen_task_get poll; null for a dry run |
preview |
SeedanceCreatePreview | null | Set only for a dry run |
SeedanceTaskRef:
| Field | Type | Description |
|---|---|---|
index |
integer | 0-based variation index (0 for a single request) |
task_id |
string | null | Provider task ID; poll with gen_task_get. For draft=true, pass it as draft_task_id once succeeded. null when submission failed |
request_id |
string | null | Provider request ID, when returned |
error |
VariationError | null | Why this submission failed; null when accepted |
SeedanceCreatePreview:
| Field | Type | Description |
|---|---|---|
requests |
list[object] | Provider request bodies, one per variation. HTTPS media URLs are reduced to scheme and host, inline Base64 to its size; asset:// references are kept |
estimated_cost_usd |
number | Static estimate from the server’s price table for all requests; not a provider quote |
Polling
Section titled “Polling”Read each tasks[].task_id from the background result and pass all of them
in one call to gen_task_get. queued or running is
not a failure: poll with gen_task_get; never resubmit seedance_create_task
to poll, because every submission is a new billed task.
Examples
Section titled “Examples”// Single task (default model), via ark_job_submit{ "tool_name": "seedance_create_task", "arguments": { "input": { "prompt": "A cat walking through a garden", "images": ["https://example.com/cat.png"], "resolution": "1080p", "duration": 10 } }}
// Background result{ "model": "dreamina-seedance-2-5-260628", "family": "seedance_2_5", "dry_run": false, "tasks": [ { "index": 0, "task_id": "cgt-20260721134956-h5cz9", "request_id": "021...", "error": null } ], "submitted": 1, "failed": 0, "recommended_poll_after_ms": 5000, "preview": null}// Variations on a Seedance 2.0 model (arguments.input){ "model": "dreamina-seedance-2-0-260128", "variations": 2, "variation_prompts": [ "The cat walks forward slowly", "The cat jumps playfully" ], "images": [ { "kind": "base64", "data": "...", "mime_type": "image/png", "role": "reference_image" } ], "resolution": "480p", "duration": 5}
// Background result (one variation failed){ "model": "dreamina-seedance-2-0-260128", "family": "seedance_2", "dry_run": false, "tasks": [ { "index": 0, "task_id": "cgt-...-rq5gm", "request_id": "021...", "error": null }, { "index": 1, "task_id": null, "request_id": null, "error": { "code": "TIMEOUT", "message": "...", "retryable": true, "ambiguous_completion": true, "phase": "generating" } } ], "submitted": 1, "failed": 1, "recommended_poll_after_ms": 5000, "preview": null}// Draft step 1: 480p preview (arguments.input){ "prompt": "A paper boat drifting down a rainy street", "draft": true }
// Draft step 2: final render from the succeeded Draft (arguments.input){ "draft_task_id": "cgt-20260721134956-h5cz9" }// Dry run (arguments.input){ "prompt": "A lighthouse at dusk", "variations": 2, "dry_run": true }
// Background result (available on the first ark_job_get){ "model": "dreamina-seedance-2-5-260628", "family": "seedance_2_5", "dry_run": true, "tasks": [], "submitted": 0, "failed": 0, "recommended_poll_after_ms": null, "preview": { "requests": [ { "model": "dreamina-seedance-2-5-260628", "content": [{ "type": "text", "text": "A lighthouse at dusk" }], "watermark": false }, { "model": "dreamina-seedance-2-5-260628", "content": [{ "type": "text", "text": "A lighthouse at dusk" }], "watermark": false } ], "estimated_cost_usd": 1.2 }}The estimated_cost_usd value above is illustrative only.
7. seed_understand
Section titled “7. seed_understand”Understand images and videos, or reason about a task, through the Seed 2.1
multimodal model. Deep thinking is always on (depth set by reasoning_effort),
and only the final answer is returned: the reasoning trace is discarded and
never returned, logged, or saved. The default model
is dola-seed-2-1-turbo-260628 (Seed 2.1 Turbo); dola-seed-evolving (the
latest Seed-series Pro-tier model) is also supported as a recognized built-in
ID — set SEED_UNDERSTANDING_DEFAULT_MODEL=dola-seed-evolving to opt in; its
family auto-resolves to pro so no explicit SEED_UNDERSTANDING_MODEL_FAMILY
is required. Other custom model IDs can be registered via
SEED_UNDERSTANDING_MODEL_BINDINGS. Video
Base64 is not supported by the chat endpoint — upload local videos via
media_upload first to obtain an HTTPS URL.
Execution
Section titled “Execution”seed_understand declares execution.taskSupport="required". A compatible
MCP client invokes it as a task, receives the server-generated task ID without
waiting for the ModelArk response, and polls for the final tool result. The
server recommends a two-second polling interval. Foreground invocation is
rejected immediately instead of waiting until the client timeout expires.
Clients must request a task TTL long enough for the expected analysis duration.
The chat request timeout is SEED_UNDERSTANDING_TIMEOUT_MS (default:
BYTEPLUS_REQUEST_TIMEOUT_MS). A timeout returns TIMEOUT with
retryable=true and ambiguous_completion=false, but is not retried
automatically; 429 and 5xx responses are retried.
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
prompt |
string | Yes | — | 1-32,000 chars |
images |
list[UnderstandingImageInput] | No | — | Max 32; URL or Base64 |
videos |
list[UnderstandingVideoInput] | No | — | Max 32; URL only |
system |
string | No | — | Max 32,000 chars |
model |
string | No | Configured Seed 2.1 model | Must be in capability registry |
reasoning_effort |
"low" | "medium" | "high" |
No | "medium" |
Depth of deep thinking; always sent |
response_format |
UnderstandingResponseFormat | No | — | JSON / JSON Schema, enforced provider-side |
json_retry |
integer | No | 0 |
0-2 extra billed attempts on a JSON parse/validation failure; skipped when finish_reason="length" |
save_to |
string | No | — | Absolute file path; stdio only, inside an output root; validated before billing |
overwrite |
boolean | No | false |
Replace an existing save_to file with different content |
return_content |
"full" | "summary" | "none" |
No | "full" |
summary inlines the first 2,000 characters; none inlines nothing |
temperature |
float | No | — | 0.0-2.0 |
max_tokens |
integer | No | — | 1-32,768, including deep-thinking tokens |
top_p |
float | No | — | 0.0-1.0 |
repetition_penalty |
float | No | — | 0.0-2.0; Ark-only |
thinking |
boolean | No | — | Deprecated and ignored; false only logs a warning |
UnderstandingResponseFormat
Section titled “UnderstandingResponseFormat”| Field | Type | Required | Constraints |
|---|---|---|---|
type |
"text" | "json_object" | "json_schema" |
Yes | — |
json_schema |
object | When type="json_schema" |
Must be omitted otherwise |
json_schema.name |
string | Yes | ^[A-Za-z0-9_-]{1,64}$ |
json_schema.schema |
object | Yes | Valid JSON Schema draft 2020-12, at most 64 KB serialized |
json_schema.description |
string | No | Max 2,000 chars |
json_schema.strict |
boolean | No | Default true |
save_to writes the parsed JSON pretty-printed when the answer parsed as JSON,
otherwise the UTF-8 text. Reasoning is never written. If the write fails after
billing, the call still succeeds without saved_path and returns the full
answer inline.
Output
Section titled “Output”| Field | Type | Description |
|---|---|---|
provider |
"byteplus-modelark" |
Fixed |
model |
string | Model used |
completion_id |
string | null | Provider completion ID |
choices |
list[UnderstandingChoice] | Final answers; see below |
usage |
UnderstandingUsage | Token usage summed over all attempts |
attempts |
integer | 1 plus any json_retry attempts used |
saved_path |
string | null | Absolute path written for save_to |
saved_bytes |
integer | null | Size of the written file |
request_id |
string | null | Provider request ID |
UnderstandingChoice:
| Field | Type | Description |
|---|---|---|
role |
"assistant" |
Fixed |
content |
string | Final answer; truncated for summary, empty for none |
content_chars |
integer | Full answer length before truncation |
content_truncated |
boolean | true when content is shorter than the full answer |
parsed |
object | array | null | Parsed JSON when a JSON response_format parsed (and, for json_schema, validated); returned even with summary/none |
schema_violation |
SchemaViolation | null | path (JSON Pointer, "" when not JSON), message, finish_reason |
finish_reason |
string | Provider finish reason; length means cut off by max_tokens |
UnderstandingUsage: prompt_tokens, completion_tokens (including
reasoning), total_tokens, and reasoning_tokens (thinking token cost when
the provider reports it).
Example
Section titled “Example”// Input{ "prompt": "Describe what happens in this video and identify the objects in this image.", "videos": [{ "kind": "url", "url": "https://.../sample.mp4", "mime_type": "video/mp4" }], "images": [{ "kind": "url", "url": "https://.../frame.png", "mime_type": "image/png" }], "reasoning_effort": "medium", "max_tokens": 4096}8. seed_audio_understand
Section titled “8. seed_audio_understand”Understand, transcribe, translate, or reason about audio clips (speech, music,
or sound) through a ModelArk chat model with audio input. The model is set by
SEED_AUDIO_UNDERSTANDING_MODEL (default seed-2-0-lite-260428) and is not a
per-call argument. Deep thinking is always on (depth set by reasoning_effort),
and only the final answer is returned. For long-form transcription with
word-level timings, use speech_to_text instead.
The tool shares seed_understand’s answer-shaping fields and output shape:
system, reasoning_effort, response_format, json_retry, save_to,
overwrite, return_content, temperature, max_tokens, top_p, and
repetition_penalty behave exactly as documented in
section 7. It requires background execution and uses the
understanding:read scope and SEED_UNDERSTANDING_TIMEOUT_MS.
json_schema is enforced by the provider for seed-2-0-lite-260428;
json_object is not enforced by that model, so prefer json_schema (or set
json_retry) when you need JSON.
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
prompt |
string | Yes | — | 1-32,000 chars |
audios |
list[UnderstandingAudioInput] | Yes | — | 1-8 clips, sent in order |
delivery |
"auto" | "direct" | "files_api" |
No | "auto" |
Automatic Files API fallback, direct only, or upload URLs first; Base64 stays inline |
| (shared fields) | — | No | — | As seed_understand, without images, videos, model, or thinking |
UnderstandingAudioInput: kind ("url" or "base64"), url, data,
mime_type.
kind="url": an HTTPS URL that passes the SSRF policy. The provider fetches and decodes it;mime_typeis optional.kind="base64": raw Base64 (nodata:prefix), at most 10 MB decoded.mime_typeis required and must be one ofaudio/wav(alsoaudio/x-wav,audio/wave),audio/mpeg(audio/mp3),audio/flac(audio/x-flac),audio/aac(audio/x-aac), oraudio/mp4(m4a). The provider rejects Base64 Ogg/Opus and raw PCM, so upload those viamedia_uploadand pass the URL instead.
Output
Section titled “Output”Same fields as seed_understand (provider, model,
completion_id, choices, usage, attempts, saved_path, saved_bytes,
request_id). model is the configured SEED_AUDIO_UNDERSTANDING_MODEL.
Also returns audio_delivery (per-input url, base64, files_api_audio,
or files_api_video) and nullable delivery_fallback_reason.
Direct URL audio is limited to 25 MiB by the default model. Files API accepts up to 512 MB, including video soundtracks with sampled frames at 0.2 fps (frames consume input tokens). Automatic fallback only retries a 400 rejection mentioning audio, once. Uploaded files are deleted best-effort after the call; unremoved files expire after roughly one day. See tool details.
Example
Section titled “Example”// Input{ "prompt": "Transcribe the speech and identify each speaker's emotion.", "audios": [{ "kind": "url", "url": "https://.../meeting.mp3" }], "reasoning_effort": "low", "response_format": { "type": "json_schema", "json_schema": { "name": "speech_analysis", "schema": { "type": "object", "properties": { "transcript": { "type": "string" }, "emotion": { "type": "string" } }, "required": ["transcript", "emotion"], "additionalProperties": false } } }}9. speech_to_text
Section titled “9. speech_to_text”Transcribe audio to text via Seed Speech ASR as a required background job. The
tool submits audio over HTTP and polls internally until complete; retrieve the
full TranscriptionResult from the background result. There is no separate
provider task tool or object-storage upload requirement.
| Field | Type | Required | Description |
|---|---|---|---|
audio |
AsrAudioInput | Yes | Audio source (see below) |
options |
AsrRequestOptions | No | Transcription feature toggles |
AsrAudioInput — provide exactly one source:
| Field | Type | Required | Description |
|---|---|---|---|
audio_url |
string | No* | HTTPS URL of the audio file (SSRF-safe, trusted hosts only) |
audio_data |
string | No* | Base64-encoded audio bytes |
audio_file_path |
string | No* | Absolute local file path (stdio transport only) |
audio_format |
wav | mp3 | ogg | raw | flac |
Yes | Audio format |
AsrRequestOptions:
| Field | Type | Default | Description |
|---|---|---|---|
language |
string | "en-US" |
BCP-47 language code |
enable_punc |
boolean | null |
Enable punctuation |
enable_itn |
boolean | null |
Enable ITN |
Output
Section titled “Output”| Field | Type | Description |
|---|---|---|
result |
TranscriptionResult | Full transcript: text, utterances, duration_ms |
log_id |
string | null | Provider-side log ID |
Example
Section titled “Example”// Input{ "audio": { "audio_url": "https://example.com/meeting.wav", "audio_format": "wav" }, "options": { "language": "en-US", "enable_punc": true, "enable_itn": true }}10. gen_task_get
Section titled “10. gen_task_get”One poller for every ModelArk generation task: Seedance video tasks
(seedance_create_task, every Seedance model) and Seed 3D tasks
(hyper3d_create_task, hitem3d_create_task). Registered whenever ModelArk is
configured; requires gen:read in api_key mode. Optional background task (required
when persist_output=true).
Fetches tasks with one provider list call per page of 20 task IDs (at most
three pages), filtered by task ID, and re-fetches individually only tasks
missing from the list or succeeded without an output URL. Task IDs the caller
did not create are reported in errors instead of failing the call.
Polling Workflow
Section titled “Polling Workflow”- Run a create tool through
ark_job_submitand read each providertask_idfrom the background result. - Call
gen_task_getin the foreground with every task ID you are waiting on (persist_output=false, the default). - While
all_terminalisfalse, waitrecommended_poll_after_ms(5000 ms while any task is active) and poll again.queuedorrunningis not a failure; never resubmit the create tool to retry polling, because that creates a second billed task. - Once
all_terminalistrue, callgen_task_getagain throughark_job_submitwithpersist_output=true(optionallyoutput_dir) to keep the outputs as durable artifacts before the provider URLs expire (about 24 hours).
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
task_ids |
list[string] | Yes | — | 1-50 ModelArk task IDs (not ark_job IDs); duplicates ignored |
persist_output |
boolean | No | false |
Persist each succeeded task’s outputs once per task; true requires background execution (ark_job_submit or native task augmentation) |
output_dir |
string | No | — | Local directory; stdio only, requires persist_output=true; see Local Output Paths |
overwrite |
boolean | No | false |
Replace existing files in output_dir |
Output
Section titled “Output”Returns GenTaskGetOutput:
| Field | Type | Description |
|---|---|---|
tasks |
list[GenTask] | One entry per found task, in request order |
errors |
list[GenTaskLookupError] | task_id, code (NOT_OWNED, NOT_FOUND, or a provider code), message |
all_terminal |
boolean | true when every found task has finished, so polling can stop |
active_tasks |
integer | Found tasks still queued or running |
recommended_poll_after_ms |
integer | null | 5000 while any task is active; null when all_terminal |
GenTask:
| Field | Type | Description |
|---|---|---|
task_id |
string | Provider task ID |
model |
string | Model ID that ran the task |
family |
string | null | Registry family of the model; null when the model is not configured on this server |
kind |
"video" | "3d" | "unknown" |
Output kind from the registry binding for model |
status |
GenTaskStatus | queued, running, succeeded, failed, cancelled, or expired |
created_at / updated_at |
string | ISO-8601 |
outputs |
list[TaskOutputFile] | video and last_frame for video tasks, model_file for 3D tasks; empty until succeeded. Same shape as in vod_get_task |
error |
TaskError | null | Provider code and message when failed |
usage |
TaskUsage | null | prompt_tokens, completion_tokens, total_tokens when reported |
draft |
boolean | null | true for a Seedance Draft task (480p preview); once it has succeeded, pass its task_id as draft_task_id within 14 days of created_at (7 if created before 2026-10-28 10:00 UTC+8) |
settings |
SeedanceTaskSettings | null | Video generation settings echoed by the provider; null for 3D tasks |
queue |
SeedanceQueueInfo | null | Server-derived queue timing for a queued or running video task; null once finished and for 3D tasks |
Without persistence, each output carries its expiring source_url and
persistence="not_requested". With persist_output=true, outputs are copied
once per task under a single-flight lock, so overlapping polls never
download the same file twice; a storage failure returns the provider URL with
persistence="failed" and a later poll retries.
SeedanceQueueInfo
Section titled “SeedanceQueueInfo”ModelArk publishes no queue position or ETA. These values are derived by the server from the task’s timestamps and expiry setting; they are estimates, not a provider SLA.
| Field | Type | Description |
|---|---|---|
queued_seconds |
integer | null | Now minus created_at while queued; updated_at minus created_at once running (approximate) |
running_seconds |
integer | null | Seconds since the last status update while running (approximate) |
service_tier |
string | null | default or flex |
expires_at |
string | null | created_at + execution_expires_after: the provider fails the task if unfinished by then |
expires_at_estimated |
boolean | true when execution_expires_after was not reported and the 48-hour default was assumed |
hint |
string | null | Human-readable summary |
Task Statuses
Section titled “Task Statuses”| Status | Meaning |
|---|---|
queued |
Waiting to start |
running |
Generating |
succeeded |
Completed, outputs available |
failed |
Failed, check error |
expired |
Expired before completion |
cancelled |
Was cancelled |
Example
Section titled “Example”// Input (foreground poll){ "task_ids": ["cgt-20260721134956-h5cz9", "cgt-20260721135012-k2m8p"] }
// Output (one still running){ "tasks": [ { "task_id": "cgt-20260721134956-h5cz9", "model": "dreamina-seedance-2-0-260128", "family": "seedance_2", "kind": "video", "status": "succeeded", "created_at": "2026-07-21T06:02:19+00:00", "updated_at": "2026-07-21T06:06:13+00:00", "outputs": [ { "role": "video", "source_url": "https://ark-content-generation.example.com/video.mp4?sign=...", "source_expires_at": "2026-07-22T06:06:20+00:00", "persistence": "not_requested" } ], "usage": { "completion_tokens": 48400, "total_tokens": 48400 } }, { "task_id": "cgt-20260721135012-k2m8p", "model": "dreamina-seedance-2-0-260128", "family": "seedance_2", "kind": "video", "status": "running", "created_at": "2026-07-21T06:02:35+00:00", "updated_at": "2026-07-21T06:03:10+00:00", "outputs": [] } ], "errors": [], "all_terminal": false, "active_tasks": 1, "recommended_poll_after_ms": 5000}
// Input (background persistence, via ark_job_submit){ "task_ids": ["cgt-20260721134956-h5cz9"], "persist_output": true }11. gen_task_list
Section titled “11. gen_task_list”List the caller’s ModelArk generation tasks (Seedance video and 3D), newest
first, covering tasks created in the last 7 days (the provider’s list
window). Registered whenever ModelArk is configured; requires gen:read in api_key
mode. Use gen_task_get for outputs.
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
page_size |
integer | No | 20 |
1-100 |
cursor |
string | No | — | Opaque next_cursor from a previous call made with the same filters |
status |
GenTaskStatus | No | — | queued, running, succeeded, failed, cancelled, or expired |
model |
string | No | — | Exact model ID |
task_ids |
list[string] | No | — | Up to 100; IDs the caller does not own are skipped |
Output
Section titled “Output”Returns GenTaskPage:
| Field | Type | Description |
|---|---|---|
tasks |
list[GenTaskSummary] | Matching tasks, newest first: task_id, model, kind, status, created_at, and error when failed |
next_cursor |
string | null | Pass back as cursor to continue; null when there are no more tasks |
Paging Rules
Section titled “Paging Rules”- Follow
next_cursoruntil it isnull. A page may hold fewer thanpage_sizetasks whilenext_cursoris non-null, so a short page does not mean the list is finished. - Keep the same filters while paging. A cursor is bound to
status,model,task_ids, andpage_size; changing any of them rejects the cursor. Repeat the original filters or start again without a cursor. - Non-local principals page through their owned task IDs from the ownership store in slices of 100, so the provider request URL never overflows however many tasks the caller owns.
Example
Section titled “Example”// Input{ "status": "succeeded", "page_size": 10 }
// Output{ "tasks": [ { "task_id": "cgt-20260721134956-h5cz9", "model": "dreamina-seedance-2-0-260128", "kind": "video", "status": "succeeded", "created_at": "2026-07-21T06:02:19+00:00" } ], "next_cursor": null}12. gen_task_cancel_or_delete
Section titled “12. gen_task_cancel_or_delete”Cancel (queued) or delete (terminal) any ModelArk generation task: Seedance,
Hyper3D, or Hitem3d. Registered whenever ModelArk is configured; requires
gen:delete in api_key mode. Destructive. The tool first fetches the task and
refuses to act when its actual status differs from expected_status. A deleted
task’s outputs are no longer retrievable through gen_task_get.
| Field | Type | Required | Description |
|---|---|---|---|
task_id |
string | Yes | ModelArk generation task ID |
mode |
"cancel" | "delete" |
Yes | Operation |
expected_status |
"queued" | "succeeded" | "failed" | "expired" |
Yes | Expected current status |
confirm |
true |
Yes | Explicit confirmation |
DELETE Semantics
Section titled “DELETE Semantics”| Status | Cancel | Delete |
|---|---|---|
queued |
Yes | No |
running |
No | No |
succeeded |
No | Yes |
failed |
No | Yes |
expired |
No | Yes |
cancelled |
No | No |
Output
Section titled “Output”| Field | Type | Description |
|---|---|---|
task_id |
string | Task ID |
mode |
"cancel" | "delete" |
Operation performed |
previous_status |
string | Status before operation |
message |
string | Result message |
13. vod_enhance_video
Section titled “13. vod_enhance_video”Enhance a public HTTPS video through the Bearer-authenticated BytePlus VOD AI
MediaKit convenience endpoint. The tool is registered only when
BYTEPLUS_VOD_MEDIAKIT_API_KEY is configured and requires the vod:enhance
scope in api_key mode.
The tool selects an enhancement tier (fast, standard, or professional) and a
target resolution from 240p up to 8K (fast tops out at 4K) or a short-side pixel
limit. standard and professional submit to /tools/enhance-video; fast submits
to /tools/enhance-video-fast. Defaults preserve the previous profile:
professional / 4k / high / 24 fps. Retrieve
the provider task ID and operation ("enhance") from the background result,
then poll them with vod_get_task. The POST is non-idempotent
and is never retried automatically because a timeout may occur after the provider
began processing.
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
video_url |
URL | Yes | — | Public HTTPS source; private, loopback, and link-local targets rejected |
tool_version |
"fast" | "standard" | "professional" |
No | "professional" |
Enhancement tier; fast uses its own endpoint |
resolution |
"240p" … "4k", "6k", "8k" |
No | "4k" when resolution_limit is unset |
fast accepts up to "4k"; mutually exclusive with resolution_limit |
resolution_limit |
integer | No | — | 128–4320 (128–2160 for fast); short-side pixels, aspect ratio preserved |
bitrate_level |
"low" | "medium" | "high" |
No | "high" |
Ignored when bitrate is set |
bitrate |
integer | No | — | kbps, 10–150000 |
fps |
number | null | No | 24 |
15–120; null keeps the source frame rate |
scene |
"common" | "ugc" | "short_series" | "aigc" | "old_film" |
No | "common" |
Effective for standard only; not sent for fast |
enhance_style |
"hd" | "natural" |
No | — | standard/professional only; rejected for fast |
project |
string | No | "default" |
1–128 characters; serialized upstream as Project |
input_duration_seconds |
number | null | No | null |
Positive; reserved for future pricing support |
persist |
boolean | No | true |
Best-effort durable artifact copy |
Output
Section titled “Output”Returns VodEnhanceVideoOutput with provider byteplus-vod-mediakit,
status="accepted", task/request IDs, and operation="enhance". If the provider directly returns a
completed result, status is succeeded and source_url is preserved whether
persistence succeeds, is skipped, or fails.
When persist=true, the server attempts an SSRF-safe copy into the artifact
store. Video persistence is capped at 200 MiB. persistence is one of
not_applicable, persisted, failed, or not_requested; persistence_issue safely explains
a failure without exposing the URL or credential. video contains the durable
ArtifactRef only when persistence succeeds. estimated_cost_usd is always
null until the convenience endpoint’s pricing and billing-unit mapping are
confirmed.
The asynchronous acceptance and completed task shapes are verified by sanitized live probes. Unknown shapes fail closed.
Example
Section titled “Example”{ "video_url": "https://media.example.com/source.mp4", "tool_version": "fast", "resolution": "1080p", "bitrate_level": "medium", "fps": null, "persist": true}14. vod_transcode_video
Section titled “14. vod_transcode_video”Submit an asynchronous BytePlus VOD AI MediaKit video transcoding task through
the Bearer-authenticated convenience endpoint. Registered only when
BYTEPLUS_VOD_MEDIAKIT_API_KEY is configured; requires the vod:transcode
scope in api_key mode.
The request body and video object field names and enums are verified from the
official AI MediaKit API reference. The default options reproduce the verified
portrait-to-720x720 letterbox profile. Submission returns status="accepted"
with a task_id and operation="transcode" for polling via
vod_get_task. The non-idempotent
POST is never retried automatically because a timeout may occur after the
provider began processing.
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
video_url |
URL | Yes | — | Public HTTPS source; private, loopback, and link-local targets rejected |
container_format |
"MP4" | "FLV" | "MPEGTS" |
No | "MP4" |
Output container format |
video |
VodTranscodeVideoOptions | No | default profile | See below |
VodTranscodeVideoOptions:
| Field | Type | Default | Constraints |
|---|---|---|---|
codec |
"h264" | "h265" |
"h264" |
Output video codec |
scale_type |
0 | 1 | 2 |
2 |
0 follow source, 1 long/short-side limit, 2 width/height limit |
scale_mode |
0 | 1 | 2 |
2 |
0 no upsampling, 1 stretch, 2 letterbox with black bars |
scale_width |
integer | null | null |
px [0,4320]; only when scale_type=2; defaults to 720 |
scale_height |
integer | null | null |
px [0,4320]; only when scale_type=2; defaults to 720 |
scale_short |
integer | null | null |
px [0,4320]; only when scale_type=1 |
scale_long |
integer | null | null |
px [0,4320]; only when scale_type=1 |
bitrate_mode |
"crf" | "abr" | "cbr" |
"crf" |
Bitrate control mode |
bitrate_crf |
integer | 25 |
[0,51]; only used when bitrate_mode=crf |
bitrate_kbps |
integer | 2000 |
kbps [10,50000] |
fps_mode |
"vfr" | "cfr" |
"vfr" |
Only takes effect after fps is set |
fps |
integer | null | null |
[1,240]; unset keeps source rate |
is_hdr_to_sdr |
boolean | true |
Convert HDR to SDR; false keeps HDR |
Output
Section titled “Output”Returns VodTranscodeVideoOutput with provider byteplus-vod-mediakit,
status="accepted", task/request IDs, operation="transcode", and a
server-side heuristic recommended_poll_after_ms.
Example
Section titled “Example”{ "video_url": "https://media.example.com/portrait.mp4", "container_format": "MP4", "video": { "scale_type": 2, "scale_width": 720, "scale_height": 720, "scale_mode": 2 }}15. vod_separate_audio
Section titled “15. vod_separate_audio”Submit an asynchronous BytePlus VOD AI MediaKit voice and background audio
separation task via POST /api/v1/tools/separate-voice. The tool is registered
when BYTEPLUS_VOD_MEDIAKIT_API_KEY is configured and requires the
vod:extract scope in api_key mode.
Input takes a public HTTPS source URL and separation options:
| Field | Type | Required | Description |
|---|---|---|---|
audio_url |
string | No | Public HTTPS audio URL (mp3, m4a, wav). Exactly one of audio_url/video_url |
video_url |
string | No | Public HTTPS video URL (mp4, flv, ts, avi, mov, wmv, mkv). Exactly one of audio_url/video_url |
scene |
string | No | Audio (default), Music, Drama, Narrate |
output_format |
string | No | aac (default), mp3, wav, m4a, flac |
Returns VodSeparateAudioOutput with provider byteplus-vod-mediakit,
status accepted, operation="separate_audio", the provider request_id and
provider_log_id. Run it in the background, then pass the provider task ID and
operation from its result to vod_get_task. The mutation is never retried
automatically because completion is ambiguous after a timeout.
Example
Section titled “Example”// Input{ "video_url": "https://example.com/clip.mp4", "scene": "Drama" }
// Output{ "provider": "byteplus-vod-mediakit", "status": "accepted", "request_id": "20260820...", "provider_log_id": "20260820...", "task_id": "amk-tool-separate-voice-...", "operation": "separate_audio", "recommended_poll_after_ms": 3000}16. vod_add_subtitles
Section titled “16. vod_add_subtitles”Submit POST /tools/add-subtitle-to-video using the configured MediaKit Bearer
key and the vod:subtitle:add scope in api_key mode. video_url is required and must be a
public HTTPS URL. Provide at least one of subtitle_url (SRT, VTT, or ASS) or
subtitles, where every inline cue has nonblank subtitle_text and an
end_time greater than its nonnegative start_time. A subtitle file takes
priority when both forms are present.
Optional style fields control the position preset, positive pixel font size,
RGBA color, and MediaKit font. client_token is at most 64 printable ASCII
characters; callback payloads are capped at 512 UTF-8 bytes. callback_url
must be public HTTPS. project is a legacy case-sensitive Project extension
and is omitted by default. The accepted output includes task_id,
operation="add_subtitles", request IDs, and a 5-second initial polling
heuristic. Poll with vod_get_task.
17. vod_remove_subtitles
Section titled “17. vod_remove_subtitles”Submit POST /tools/erase-video-subtitle-pro using vod:subtitle:remove.
mode="subtitle" removes recognized dialogue subtitles; the broader
mode="text" may also remove titles, labels, or watermarks. Encoding mode is
quality or size. Optional precision controls include one-to-twenty
normalized erasure rectangles, selected/skipped time segments, and subtitle
OCR size/centering thresholds. Callback, queue, and client_token fields match
subtitle addition. The legacy model_version (v4/v5) and project fields
are omitted unless explicitly supplied. The output includes the task ID,
operation="remove_subtitles", and a 15-second initial polling heuristic. Poll
with vod_get_task.
18. vod_get_task
Section titled “18. vod_get_task”One poller for every VOD AI MediaKit task. Pass the task_id and
operation that any vod_* create tool returned (vod_enhance_video,
vod_transcode_video, vod_separate_audio, vod_add_subtitles, or
vod_remove_subtitles). Registered only when BYTEPLUS_VOD_MEDIAKIT_API_KEY
is configured; requires the vod:read scope in api_key mode. Only the principal
that created the task can poll it.
processing is not a failure: poll again later and never resubmit the create
tool, because each submission starts a new billed task.
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
task_id |
string | Yes | — | MediaKit task ID from a vod_* create tool; 1-256 chars of A-Z a-z 0-9 . _ : - |
operation |
"enhance" | "transcode" | "separate_audio" | "add_subtitles" | "remove_subtitles" |
Yes | — | Echoed as operation by the create tool |
persist_output |
boolean | No | false |
Copy finished outputs into durable artifacts once per task. true requires background execution (ark_job_submit or native task augmentation); leave false for a foreground status poll |
output_path |
string | No | — | Local file, or directory ending /; a directory is required for separate_audio, which writes every track. Stdio only, requires persist_output=true; see Local Output Paths |
overwrite |
boolean | No | false |
Replace existing files at output_path |
Output
Section titled “Output”Returns VodTaskOutput:
| Field | Type | Description |
|---|---|---|
provider |
"byteplus-vod-mediakit" |
Provider surface |
task_id |
string | MediaKit task ID |
operation |
string | Operation that created the task |
status |
"processing" | "succeeded" | "failed" |
Normalized status |
provider_status |
string | null | Raw provider status label |
request_id |
string | null | Provider diagnostic request ID |
created_at / finished_at |
string | null | ISO-8601 timestamps |
duration_seconds |
number | null | Output duration (input duration for separate_audio) |
resolution |
string | null | Output resolution (enhance, transcode, subtitles) |
fps |
number | null | Output frame rate (enhance) |
video_codec |
string | null | Output video codec (transcode) |
tool_version |
string | null | Enhancement tier (enhance) |
outputs |
list[TaskOutputFile] | Finished outputs; empty unless succeeded |
error |
TaskError | null | code and safe message; set only when failed |
TaskOutputFile (shared with gen_task_get):
| Field | Type | Description |
|---|---|---|
role |
string | video (enhance, transcode, subtitles) or voice / background / music / sfx (separate_audio) |
artifact |
ArtifactRef | null | Durable artifact when persisted; local_path set when also exported |
source_url |
string | null | Expiring provider URL (about 24 hours), kept even when persistence is skipped or fails |
source_expires_at |
string | null | ISO-8601 expected expiry of source_url |
persistence |
"not_requested" | "persisted" | "failed" |
Persistence outcome, independent of task success |
persistence_issue |
ArtifactPersistenceIssue | null | Safe explanation when persistence failed |
With persist_output=true, the first successful poll copies each output into
the artifact store once per task: concurrent polls share one copy and the
artifacts are cached by task ID for later polls. A persistence failure never
changes provider success.
Task Statuses
Section titled “Task Statuses”| Status | Meaning |
|---|---|
processing |
Queued or running; poll again |
succeeded |
At least one entry in outputs |
failed |
error populated; outputs empty |
Example
Section titled “Example”// Foreground status poll (persist_output defaults to false){ "task_id": "amk-tool-transcode-video-112738623234", "operation": "transcode" }
// Once succeeded: run once through ark_job_submit to keep every separated track{ "task_id": "amk-tool-separate-voice-...", "operation": "separate_audio", "persist_output": true, "output_path": "/Users/me/out/stems/"}
// Output (succeeded, separate_audio){ "provider": "byteplus-vod-mediakit", "task_id": "amk-tool-separate-voice-...", "operation": "separate_audio", "status": "succeeded", "provider_status": "completed", "duration_seconds": 120.5, "outputs": [ { "role": "voice", "artifact": { "id": "...", "uri": "seed-media://artifacts/...", "media_type": "audio", "mime_type": "audio/aac", "bytes": 1787924 }, "source_url": "https://vod.ap-southeast-1.byteplusvod.com/voice.aac?sign=...", "persistence": "persisted" }, { "role": "background", "artifact": { "id": "...", "uri": "seed-media://artifacts/...", "media_type": "audio", "mime_type": "audio/aac", "bytes": 1787924 }, "source_url": "https://vod.ap-southeast-1.byteplusvod.com/background.aac?sign=...", "persistence": "persisted" } ]}19–21. omnihuman_create_task / omnihuman_get_task / omnihuman_cancel_task
Section titled “19–21. omnihuman_create_task / omnihuman_get_task / omnihuman_cancel_task”Registered when BYTEPLUS_OMNIHUMAN_ENABLED=true and BYTEPLUS_CV_API_KEY is
set. Scopes: omnihuman:create, omnihuman:read, omnihuman:cancel.
omnihuman_create_task input: image and audio (HTTPS URL or
seed-media://artifacts/<id>), optional prompt (max 2000 characters), and
watermark (default true). Output: provider, status="accepted",
task_id, request_id, recommended_poll_after_ms.
omnihuman_get_task input: task_id, persist_output (default true, needs
task-augmented execution), output_path, overwrite. Output: status
(queued, running, succeeded, failed, canceled, expired,
not_found), video (durable ArtifactRef), source_url and
source_expires_at (one-hour provider URL), persistence,
persistence_issue, error (code, message, failed tasks only).
omnihuman_cancel_task input: task_id. Output: canceled, message
(explains why a started task cannot be canceled), request_id. See
tools.md
for limits and artifact-reference behavior.
Resources
Section titled “Resources”seed-media://artifacts/{artifact_id}
Section titled “seed-media://artifacts/{artifact_id}”Returns persisted media by artifact ID with the correct MIME type.
{ "contents": [ { "content": "<base64-encoded-bytes>", "mime_type": "image/png" } ], "meta": { "artifact_id": "83ef8c61-...", "media_type": "image" }}seed-health://status
Section titled “seed-health://status”Returns server health and configuration status as plain text, including the
build stamp, effective Seedream default model/family and background-job local
export configuration. It exposes neither credentials nor output-root paths.
Moderation lookup configured reports the flag + AK/SK gate only.
These diagnostics do not check provider authorization or filesystem readiness;
configured; needs request preflight is not proof a destination is writable.
22. seed_media_get_artifact
Section titled “22. seed_media_get_artifact”Retrieve persisted media by artifact ID. Returns the raw media bytes
(Base64-encoded) with MIME type, SHA-256 hash, and byte count. Use this to
fetch media after the provider URL has expired (2h audio, 24h image/video).
Always registered; requires artifacts:read in api_key mode.
| Field | Type | Required | Description |
|---|---|---|---|
artifact_id |
string | Yes | Artifact ID returned by a previous generation call |
Output
Section titled “Output”| Field | Type | Description |
|---|---|---|
artifact_id |
string | Artifact identifier |
media_type |
"image" | "audio" | "video" |
Logical media type |
mime_type |
string | MIME type of the stored content |
sha256 |
string | SHA-256 hex digest |
bytes |
integer | Size in bytes |
expires_at |
string | null | Local artifact expiry, if applicable |
data |
string | Base64-encoded media data |
Example
Section titled “Example”// Input{ "artifact_id": "71e9c2a8-..." }
// Output{ "artifact_id": "71e9c2a8-...", "media_type": "video", "mime_type": "video/mp4", "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "bytes": 1748096, "data": "AAAAIGZ0cBAAA..."}23. seed_media_export_artifact
Section titled “23. seed_media_export_artifact”Locate or copy a persisted media artifact on the local filesystem. Returns the
absolute on-disk path instead of streaming Base64 through the MCP context.
Stdio transport only — the client and server must share a filesystem. Always
registered, but HTTP calls are rejected even though the shared key has
artifacts:read.
| Field | Type | Required | Description |
|---|---|---|---|
artifact_id |
string | Yes | Artifact ID returned by a previous generation call |
destination_path |
string | No | Absolute file path inside an allowed output root where the server writes an atomic copy; omit to return the canonical store path |
overwrite |
boolean | No | Replace an existing destination file with different content (default false) |
destination_path follows the Local Output Paths policy.
It must be absolute and inside a client MCP root or OUTPUT_ROOTS; an existing
file is never silently overwritten (identical content is accepted).
Output
Section titled “Output”| Field | Type | Description |
|---|---|---|
artifact_id |
string | Artifact identifier |
path |
string | Absolute on-disk path of the exported media file |
media_type |
"image" | "audio" | "video" | "three_d" |
Logical media type |
mime_type |
string | MIME type of the stored content |
bytes |
integer | Size in bytes |
sha256 |
string | null | SHA-256 hex digest |
copied |
boolean | true when copied to destination_path (or an identical copy was already there); false when path is the canonical store location |
Example
Section titled “Example”// Input{ "artifact_id": "71e9c2a8-..." }
// Output{ "artifact_id": "71e9c2a8-...", "path": "/abs/.artifacts/71/71e9c2a8-....mp4", "media_type": "video", "mime_type": "video/mp4", "bytes": 1748096, "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "copied": false}24. seed_media_persist_url
Section titled “24. seed_media_persist_url”Persist a temporary provider output URL as a durable artifact. Use it to
recover an ArtifactRef with id="provider-url" and a persistence_error
before the provider URL expires. Always registered; requires media:upload in
api_key mode. Optional background task.
Only trusted BytePlus provider hosts are downloaded, through the same SSRF-resistant downloader, host allowlist, redirect re-validation, and size limits as generation-time persistence.
| Field | Type | Required | Constraints |
|---|---|---|---|
url |
string | Yes | HTTPS provider URL, 1-8192 chars |
media_type |
"image" | "audio" | "video" | "three_d" |
Yes | — |
mime_type |
string | Yes | Expected MIME type; a specific provider Content-Type takes precedence |
source_expires_at |
string | No | ISO-8601 URL expiry, copied from the original reference |
Output
Section titled “Output”| Field | Type | Description |
|---|---|---|
artifact |
ArtifactRef | The new durable artifact |
A failure is a tool error naming the persistence code and whether it is retryable.
25. media_upload
Section titled “25. media_upload”Upload 1-50 files to object storage (TOS or S3) in one call and return a
presigned HTTPS GET URL per file. Registered when the selected object-storage
backend credentials are set (TOS_* with default OBJECT_STORAGE_BACKEND=tos,
or S3_* with OBJECT_STORAGE_BACKEND=s3); requires media:upload in api_key
mode. Required background task: run it through ark_job_submit (or native
task augmentation).
Use it for media that cannot be inlined as Base64, most notably Seedance video references, which are URL-only.
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
items |
list[MediaUploadItem] | Yes | — | 1-50 files |
expires_in_seconds |
integer | No | configured presign TTL | 60–604800, applied to every item. Use a long value (e.g. 3600) for URLs destined for vod_* tools, which fetch asynchronously |
max_concurrent |
integer | No | 4 |
1-8 uploads at once |
MediaUploadItem:
| Field | Type | Required | Constraints |
|---|---|---|---|
media_type |
"image" | "audio" | "video" |
Yes | Selects the MIME allow-list and size limit |
mime_type |
string | For data items |
Must be in the allowed list for media_type. For file_path items it is guessed from the extension when omitted; if it cannot be guessed, that item fails with Could not infer mime_type ... |
data |
string | one of | Base64 bytes; mutually exclusive with file_path |
file_path |
string | one of | Absolute local path (stdio only); mutually exclusive with data |
key_prefix |
string | No | Default "references"; alphanumeric, -, _, / |
Limits:
- Per item: the media-policy maximum for its
media_type(video up to 200 MiB). An oversized or invalid item fails on its own. - Whole call: the total decoded size is capped by
MEDIA_UPLOAD_BATCH_MAX_BYTES(default 500 MiB) and checked before any upload starts. Exceeding it fails the whole call (“Split it into smaller calls”); it is not a per-item error.
Each object is stored at <key_prefix>/<media_type>/<uuid>, and its owner is
recorded for media_presign ownership checks. All shared-key members use the
same owner and can presign team uploads.
Output
Section titled “Output”| Field | Type | Description |
|---|---|---|
items |
list[MediaUploadItemResult] | Per-item results in request order |
succeeded |
integer | Items uploaded |
failed |
integer | Items that failed; check it and items[].error when non-zero |
total_bytes |
integer | Bytes uploaded across successful items |
MediaUploadItemResult:
| Field | Type | Description |
|---|---|---|
index |
integer | 0-based position in the request |
file_path |
string | null | The item’s file_path as given, to match results to inputs |
url |
string | null | Presigned HTTPS GET URL (null if failed) |
object_key |
string | null | Object key, reusable with media_presign |
expires_at |
string | null | ISO-8601 expiry of url |
mime_type |
string | null | MIME type used for the upload |
bytes |
integer | null | Uploaded byte count |
error |
string | null | Why the item failed (validation, missing file, provider error); null on success |
retryable |
boolean | null | Whether the failed item may succeed if uploaded again; null on success |
Example
Section titled “Example”// ark_job_submit input{ "tool_name": "media_upload", "arguments": { "input": { "items": [ { "media_type": "video", "file_path": "/Users/me/clips/ref.mp4" }, { "media_type": "image", "mime_type": "image/png", "data": "iVBORw0KGgo..." } ], "expires_in_seconds": 3600 } }}
// Background result{ "items": [ { "index": 0, "file_path": "/Users/me/clips/ref.mp4", "url": "https://test-bucket.tos-ap-southeast-1.bytepluses.com/references/video/abc?X-Tos-Signature=...", "object_key": "references/video/abc", "expires_at": "2026-07-24T07:30:00+00:00", "mime_type": "video/mp4", "bytes": 1048576, "error": null, "retryable": null }, { "index": 1, "file_path": null, "url": "https://test-bucket.tos-ap-southeast-1.bytepluses.com/references/image/def?X-Tos-Signature=...", "object_key": "references/image/def", "expires_at": "2026-07-24T07:30:00+00:00", "mime_type": "image/png", "bytes": 20480, "error": null, "retryable": null } ], "succeeded": 2, "failed": 0, "total_bytes": 1069056}26. media_presign
Section titled “26. media_presign”Mint fresh presigned HTTPS GET URLs for 1-100 objects already in storage
(TOS or S3), without re-uploading. Use it when a reference URL from
media_upload has expired or is about to. No data is transferred.
Registered with object storage; requires media:presign in api_key mode.
Foreground (read-only).
A malformed, unowned, or provider-failing key is reported per key while the
other keys succeed, so check failed.
| Field | Type | Required | Constraints |
|---|---|---|---|
object_keys |
list[string] | Yes | 1-100 keys from prior media_upload calls (e.g. references/video/<uuid>). Alphanumeric, -, _, /; must not start with / or - or contain empty segments |
expires_in_seconds |
integer | No | 60–604800, applied to every key; defaults to the configured presign TTL. Use a long value (e.g. 3600) for vod_* inputs |
Output
Section titled “Output”| Field | Type | Description |
|---|---|---|
items |
list[MediaPresignItem] | Per-key results, in input order |
succeeded |
integer | Keys that produced a URL |
failed |
integer | Keys that failed; check items[].error when non-zero |
MediaPresignItem:
| Field | Type | Description |
|---|---|---|
object_key |
string | Key this entry corresponds to |
url |
string | null | Fresh presigned URL (null if failed) |
expires_at |
string | null | ISO-8601 expiry (null if failed) |
code |
string | null | Error code when failed (see below) |
error |
string | null | Human-readable error (null on success) |
request_id |
string | null | Provider request ID for this key’s presign call, when available |
code |
Meaning |
|---|---|
INVALID_KEY |
Malformed object key |
NOT_OWNED |
Key was not uploaded by the calling principal |
INTERNAL |
Unexpected server error |
| (provider code) | The storage provider rejected the presign |
Example
Section titled “Example”// Input{ "object_keys": ["references/video/abc-123-def", "references/image/def-456-ghi"]}
// Output{ "items": [ { "object_key": "references/video/abc-123-def", "url": "https://test-bucket.tos-ap-southeast-1.bytepluses.com/references/video/abc-123-def?X-Tos-Signature=...", "expires_at": "2026-07-24T07:30:00+00:00", "code": null, "error": null, "request_id": null }, { "object_key": "references/image/def-456-ghi", "url": null, "expires_at": null, "code": "NOT_OWNED", "error": "Object key is not owned by the current principal.", "request_id": null } ], "succeeded": 1, "failed": 1}Asset Library
Section titled “Asset Library”Eight ark_asset_* tools manage the Dreamina Seedance private asset
library (AIGC virtual portraits and verified real people) through the
AK/SK-signed ModelArk OpenAPI. They are registered only when
BYTEPLUS_MODELARK_ACCESS_KEY and BYTEPLUS_MODELARK_SECRET_KEY are set;
ark_asset_delete additionally needs BYTEPLUS_MODELARK_ASSETS_ALLOW_DELETE=true.
Pass the returned asset_uri (asset://<asset_id>) to Seedance. See
assets.md for the end-to-end workflow.
| # | Tool | Scope | Execution |
|---|---|---|---|
| 27 | ark_asset_group_ensure |
assets:write |
Foreground |
| 28 | ark_asset_group_list |
assets:read |
Foreground |
| 29 | ark_asset_create |
assets:write |
Optional background |
| 30 | ark_asset_list |
assets:read |
Foreground |
| 31 | ark_asset_update |
assets:write |
Foreground |
| 32 | ark_asset_verification_start |
assets:verify |
Foreground |
| 33 | ark_asset_verification_result |
assets:verify |
Optional background |
| 34 | ark_asset_delete |
assets:delete |
Foreground |
Replacements for the former single-purpose tools: group creation is now
ark_asset_group_ensure; reading groups or assets by ID is group_ids on
ark_asset_group_list and asset_ids on ark_asset_list; group rename and
description edits are ark_asset_update(group_id=...); group deletion is
ark_asset_delete(group_id=..., cascade=...).
Rate limiting: asset calls hold the modelark-openapi rate-limit slot only
around each provider request, so asset processing waits (wait_until_active
polls), CreateAsset spacing, and verification polling no longer block
Seedance asset:// preflight.
Every tool accepts an optional project_name (1-64 chars, default
BYTEPLUS_MODELARK_PROJECT_NAME, i.e. default). Assets only work with
inference endpoints in the same project, so keep one project throughout.
Provider failures are returned as tool errors.
Shared asset types
Section titled “Shared asset types”AssetGroup: group_id, name, description, group_type (AIGC or
LivenessFace), project_name, created_at, updated_at.
Asset: asset_id, asset_uri (asset://<asset_id>), name, group_id,
asset_type (Image, Video, Audio), status (Processing, Active,
Failed; only Active is usable), project_name, moderation_strategy
(Default or Skip), preview_url (temporary ~12 h viewing link; never pass
it to Seedance), created_at, updated_at, last_inference_time.
AssetLookupError (in errors[] of ID lookups):
| Field | Type | Description |
|---|---|---|
id |
string | Asset or group ID that could not be read |
code |
string | Provider error code (e.g. NotFound.Asset) |
message |
string | Human-readable reason |
27. ark_asset_group_ensure
Section titled “27. ark_asset_group_ensure”Return the single AIGC group named exactly subject, creating it if absent.
Keeps all assets of one subject (a fictional character, mascot, or product) in
one group. idempotentHint: true: repeating the call returns the same
group. Fails with ambiguous_asset_group (listing the IDs) when several AIGC
groups share the name. Creation is serialized within one server event loop;
separate servers should use a pre-created group ID. Real people use the
LivenessFace group from ark_asset_verification_result instead.
| Field | Type | Required | Constraints |
|---|---|---|---|
subject |
string | Yes | Exact group name, 1-64 chars |
description |
string | No | ≤300 chars; used only when a new group is created |
project_name |
string | No | See above |
Output (AssetGroupResult)
Section titled “Output (AssetGroupResult)”| Field | Type | Description |
|---|---|---|
group |
AssetGroup | The group |
created |
boolean | True when this call created it; false when it already existed |
28. ark_asset_group_list
Section titled “28. ark_asset_group_list”List groups by fuzzy name and type, or read up to 20 groups by ID.
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
group_ids |
list[string] | No | — | 1-20 IDs of any group type. Not combinable with name, next_token, or sort_order; group_type and max_results are ignored |
name |
string | No | — | Fuzzy name filter, ≤64 chars |
group_type |
"AIGC" | "LivenessFace" |
No | "AIGC" |
Virtual portraits or verified real people |
max_results |
integer | No | 20 |
1-100 |
next_token |
string | No | — | Token from the previous page |
sort_order |
"Asc" | "Desc" |
No | provider default | By creation time |
project_name |
string | No | — | See above |
Output (AssetGroupPage)
Section titled “Output (AssetGroupPage)”| Field | Type | Description |
|---|---|---|
groups |
list[AssetGroup] | Groups on this page, or the groups read by ID |
next_token |
string | null | Token for the next page; null when done |
errors |
list[AssetLookupError] | group_ids that could not be read; empty when listing |
With group_ids, duplicate IDs are de-duplicated, each group is read in order,
and an unreadable ID goes to errors[] instead of failing the call.
29. ark_asset_create
Section titled “29. ark_asset_create”Add files of one subject to one group and return asset:// references.
Each source is registered with CreateAsset (rate-limited by
BYTEPLUS_MODELARK_ASSET_CREATE_QPM); per-source failures are reported inline.
Real-person groups reject faces that do not match the verified person.
Optional background task.
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
sources |
list[AssetSource] | Yes | — | 1-20 files of one subject |
group_id |
string | one of | — | Target group (AIGC or LivenessFace); real people must use the ID from ark_asset_verification_result |
subject |
string | one of | — | AIGC subject name; reuses or creates that group like ark_asset_group_ensure |
skip_moderation |
boolean | No | false |
Moderation.Strategy=Skip; works only after content pre-filter is off in the console |
wait_until_active |
boolean | No | true |
Poll until each asset is Active or Failed |
wait_timeout_seconds |
integer | No | 120 |
5-900 |
project_name |
string | No | — | See above |
AssetSource: exactly one of url (public HTTPS URL) or object_key (from
media_upload; a presigned URL is minted automatically), plus optional
asset_type (Image, Video, Audio; inferred from the extension or key)
and name (≤64 chars, search only).
Output (AssetCreateOutput)
Section titled “Output (AssetCreateOutput)”| Field | Type | Description |
|---|---|---|
group_id |
string | Group the assets were added to |
group_created |
boolean | True when the subject’s group was created by this call |
group_created_empty |
boolean | True when this call created the group but every source failed, leaving it empty; delete it with ark_asset_delete(group_id=...) if not needed (registered only when BYTEPLUS_MODELARK_ASSETS_ALLOW_DELETE=true) |
items |
list[AssetCreateItem] | One result per source: index, asset_id, asset_uri, status, error |
all_active |
boolean | True when every source ended Active |
30. ark_asset_list
Section titled “30. ark_asset_list”List assets by group, type, status, or fuzzy name, or read up to 20 assets by ID.
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
asset_ids |
list[string] | No | — | 1-20 asset IDs or asset://<id> references. Not combinable with group_ids, statuses, name, next_token, or sort_order; group_type and max_results are ignored |
group_ids |
list[string] | No | — | Up to 100 group IDs |
group_type |
"AIGC" | "LivenessFace" |
No | "AIGC" |
Group type to list |
statuses |
list["Processing" | "Active" | "Failed"] |
No | — | Status filter |
name |
string | No | — | Fuzzy name filter, ≤64 chars |
max_results |
integer | No | 20 |
1-100 |
next_token |
string | No | — | Token from the previous page |
sort_order |
"Asc" | "Desc" |
No | provider default | By creation time |
project_name |
string | No | — | See above |
Output (AssetPage)
Section titled “Output (AssetPage)”| Field | Type | Description |
|---|---|---|
assets |
list[Asset] | Assets on this page, or the assets read by ID |
next_token |
string | null | Token for the next page; null when done |
errors |
list[AssetLookupError] | asset_ids that could not be read; empty when listing |
With asset_ids, duplicates are de-duplicated and unreadable IDs go to
errors[]. Assets authorized from another account are not listed but can
still be used by ID.
31. ark_asset_update
Section titled “31. ark_asset_update”Rename an asset, or rename and re-describe a group, in one tool.
| Field | Type | Required | Constraints |
|---|---|---|---|
asset_id |
string | one of | Asset ID or asset://<id> reference |
group_id |
string | one of | Group ID |
name |
string | at least one | New name, 1-64 chars |
description |
string | at least one | New description, ≤300 chars; group_id only |
project_name |
string | No | See above |
Pass exactly one of asset_id / group_id, and at least one of name /
description.
Output (AssetUpdateResult)
Section titled “Output (AssetUpdateResult)”| Field | Type | Description |
|---|---|---|
asset |
Asset | null | The updated asset, when asset_id was given |
group |
AssetGroup | null | The updated group, when group_id was given |
32. ark_asset_verification_start
Section titled “32. ark_asset_verification_start”Start real-person (liveness) verification so a consenting person’s face can be used in Seedance. Returns an H5 link for the person to open themselves.
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
callback_url |
string | No | BYTEPLUS_MODELARK_ASSET_VERIFY_CALLBACK_URL |
HTTPS page the person returns to; one of the two is required |
language |
"en" | "zh" | "zh-Hant" |
No | "en" |
Verification page language |
project_name |
string | No | — | See above |
Output (VerificationStartOutput)
Section titled “Output (VerificationStartOutput)”| Field | Type | Description |
|---|---|---|
h5_link |
string | Verification link with temporary credentials; share only with that person. Invalid after a failed attempt |
verification_token |
string | Token for ark_asset_verification_result, valid about 30 minutes |
expires_at |
string | Approximate token expiry (ISO-8601, UTC) |
next_step |
string | What to do next |
33. ark_asset_verification_result
Section titled “33. ark_asset_verification_result”Get the LivenessFace group created by a finished verification. Optional
background task (useful when wait_seconds is large).
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
verification_token |
string | Yes | — | From ark_asset_verification_start, 8-512 chars |
wait_seconds |
integer | No | 0 |
0-600; keep polling up to this long (0 = one check) |
project_name |
string | No | — | See above |
Output (VerificationResultOutput)
Section titled “Output (VerificationResultOutput)”| Field | Type | Description |
|---|---|---|
status |
"verified" | "pending" |
verified once a group exists |
group_id |
string | null | The person’s LivenessFace group; upload only their media with ark_asset_create(group_id=...) |
message |
string | Status detail |
34. ark_asset_delete
Section titled “34. ark_asset_delete”Permanently delete one asset or one group. Irreversible. Registered only
when BYTEPLUS_MODELARK_ASSETS_ALLOW_DELETE=true. Check last_inference_time
(ark_asset_list) and your own records first.
| Field | Type | Required | Default | Constraints |
|---|---|---|---|---|
asset_id |
string | one of | — | Asset ID or asset://<id> reference |
group_id |
string | one of | — | Group ID |
confirm |
true |
Yes | — | Must be true |
cascade |
boolean | No | false |
Group deletes only: also delete the group’s assets |
project_name |
string | No | — | See above |
Deleting a group deletes its assets, so a non-empty group is refused with
asset_group_not_empty unless cascade=true.
Output (AssetDeleteResult)
Section titled “Output (AssetDeleteResult)”| Field | Type | Description |
|---|---|---|
id |
string | ID of the deleted asset or group |
kind |
"asset" | "group" |
What was deleted |
deleted |
boolean | True when the provider accepted the delete |
39. ark_moderation_get
Section titled “39. ark_moderation_get”Look up existing provider-reported media block reasons through signed ModelArk
OpenAPI GetModerationResult. Requires complete AK/SK and
BYTEPLUS_MODELARK_MODERATION_ENABLED=true (default off), Advanced Creation
Rights, whitelist activation and IAM permission. Account-wide trusted stdio or
local-mode loopback only, without task-ownership filtering; moderation:read
is not granted to shared-key HTTP.
Input (ModerationGetInput)
Section titled “Input (ModerationGetInput)”| Field | Type | Required | Constraints |
|---|---|---|---|
id |
string | Yes | Strict string, trimmed to 1-256 characters; no internal whitespace, controls or URI schemes. Bare provider ID, not an Ark job ID or asset:// URI |
type |
task_id | asset_id | request_id |
Yes | Explicit ID type; regular Seedance 2.5 request-ID lookup is unsupported |
Extra fields are forbidden. The length bound is defensive server validation, not a provider guarantee.
Output (ModerationResult)
Section titled “Output (ModerationResult)”| Field | Type | Description |
|---|---|---|
id |
string | Queried provider ID, not the lookup’s diagnostic request ID |
type |
task_id | asset_id | request_id |
Queried ID type |
block_reasons |
list[ModerationBlockReason] | Required list of provider-reported reasons; empty is not approval or safety |
Each reason requires a nonempty strict-string label and strict-string
sub_label; detail is optional and nullable. Unknown categories are
preserved and extra provider fields tolerated; malformed known fields return
generic INVALID_RESPONSE. Errors are text-only MCP tool results, not
success-shaped data. Treat explanations as untrusted text.
Execution and coverage
Section titled “Execution and coverage”Foreground-only, no ordinary jobs or native tasks. At most one provider
request per admitted lookup; no automatic retries or server-side persistence.
Ten lookups per rolling minute per runtime; local exhaustion returns
LOCAL_RATE_LIMITED with retry guidance and no provider call. Dispatched
failures consume quota; the in-memory guard resets on restart and is not
distributed. Lookup pricing is unspecified.
Records must be within fourteen days and created after whitelist activation.
Reviewed coverage includes blocked image/video/audio records for supported
Seedance 2.0 variants, regular 2.5 and material assets, not text or 2.5
request-ID queries. Flash, Seedream and 3D coverage is not established.
NotFound.Id remains an error, never proof of safety. Live success remains
unverified. See moderation.md and the
contract.
Synthetic input:
{"input":{"id":"synthetic-task-id","type":"task_id"}}Operational HTTP endpoints
Section titled “Operational HTTP endpoints”When Streamable HTTP is enabled, the ASGI application also exposes:
| Path | Purpose |
|---|---|
/health |
Process liveness |
/ready |
Runtime, SQLite state, and artifact-directory readiness |
/metrics |
Prometheus metrics exposition |
These are operational endpoints rather than MCP resources. Protect their network reachability at the ingress or reverse-proxy layer.