Skip to content

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.

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 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.

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:

  1. ark_job_capabilities() returns the configured, scope-filtered targets and each target’s original input schema.
  2. ark_job_submit({"tool_name": name, "arguments": original_arguments}) durably enqueues the same registered task-enabled tool and returns a server-generated Ark job_id.
  3. ark_job_get({"job_id": id}) returns working or a terminal snapshot. On completion, result preserves the original MCP tool result.
  4. 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.

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).


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.

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

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
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.

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)
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

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

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
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.

{"kind": "video"}

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.

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" — —

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
// 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", ... } }
]
}
}

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.

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.

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
// 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.


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.

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.

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.

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)

Two steps, regular Seedance 2.5 only; Flash rejects both Draft fields:

  1. Preview. Call with draft: true. resolution must be omitted (becomes 480p) or 480p. Works with variations to compare several previews.
  2. Final. Once a Draft has succeeded, call again with draft_task_id set to its task_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, and omni_reference_task_type, so prompt, images, videos, audios, duration, ratio, generate_audio, omni_reference_task_type, and draft must be omitted (they are rejected even when they match).
    • model may be omitted (the Draft’s model is used); a different model is rejected.
    • resolution must be omitted or the model’s Draft final resolution (1080p for 2.5), which is the default. 4K applies to ordinary generation, not Draft promotion.
    • return_last_frame, watermark, execution_expires_after, priority, safety_identifier, and output_format may be set again.
    • Requires variations=1 and no variation_prompts.
  • Variations: variations 2-5 creates that many provider tasks in parallel. Partial failures are reported per entry in tasks (with error) rather than failing the call.
  • Dry run: dry_run: true runs all validation and returns preview instead of submitting. Through ark_job_submit, a dry run finishes on the first ark_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.

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

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

Extends MediaSource; also accepts a bare URL string, "asset://<asset_id>", or {"url": "..."}.

Field Type Description
role "reference_audio" Always reference_audio

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

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.

// 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.


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.

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
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.

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).

// 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
}

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_type is optional.
  • kind="base64": raw Base64 (no data: prefix), at most 10 MB decoded. mime_type is required and must be one of audio/wav (also audio/x-wav, audio/wave), audio/mpeg (audio/mp3), audio/flac (audio/x-flac), audio/aac (audio/x-aac), or audio/mp4 (m4a). The provider rejects Base64 Ogg/Opus and raw PCM, so upload those via media_upload and pass the URL instead.

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.

// 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
}
}
}
}

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
Field Type Description
result TranscriptionResult Full transcript: text, utterances, duration_ms
log_id string | null Provider-side log ID
// Input
{
"audio": { "audio_url": "https://example.com/meeting.wav", "audio_format": "wav" },
"options": { "language": "en-US", "enable_punc": true, "enable_itn": true }
}

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.

  1. Run a create tool through ark_job_submit and read each provider task_id from the background result.
  2. Call gen_task_get in the foreground with every task ID you are waiting on (persist_output=false, the default).
  3. While all_terminal is false, wait recommended_poll_after_ms (5000 ms while any task is active) and poll again. queued or running is not a failure; never resubmit the create tool to retry polling, because that creates a second billed task.
  4. Once all_terminal is true, call gen_task_get again through ark_job_submit with persist_output=true (optionally output_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

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.

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
Status Meaning
queued Waiting to start
running Generating
succeeded Completed, outputs available
failed Failed, check error
expired Expired before completion
cancelled Was cancelled
// 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 }

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

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
  • Follow next_cursor until it is null. A page may hold fewer than page_size tasks while next_cursor is 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, and page_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.
// 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
}

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
Status Cancel Delete
queued Yes No
running No No
succeeded No Yes
failed No Yes
expired No Yes
cancelled No No
Field Type Description
task_id string Task ID
mode "cancel" | "delete" Operation performed
previous_status string Status before operation
message string Result message

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

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.

{
"video_url": "https://media.example.com/source.mp4",
"tool_version": "fast",
"resolution": "1080p",
"bitrate_level": "medium",
"fps": null,
"persist": true
}

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

Returns VodTranscodeVideoOutput with provider byteplus-vod-mediakit, status="accepted", task/request IDs, operation="transcode", and a server-side heuristic recommended_poll_after_ms.

{
"video_url": "https://media.example.com/portrait.mp4",
"container_format": "MP4",
"video": {
"scale_type": 2,
"scale_width": 720,
"scale_height": 720,
"scale_mode": 2
}
}

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.

// 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
}

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.


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.


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

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.

Status Meaning
processing Queued or running; poll again
succeeded At least one entry in outputs
failed error populated; outputs empty
// 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.


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"
}
}

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.


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
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
// Input
{ "artifact_id": "71e9c2a8-..." }
// Output
{
"artifact_id": "71e9c2a8-...",
"media_type": "video",
"mime_type": "video/mp4",
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"bytes": 1748096,
"data": "AAAAIGZ0cBAAA..."
}

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).

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
// 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
}

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
Field Type Description
artifact ArtifactRef The new durable artifact

A failure is a tool error naming the persistence code and whether it is retryable.


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.

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
// 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
}

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
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
// 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
}

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.

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

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
Field Type Description
group AssetGroup The group
created boolean True when this call created it; false when it already existed

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
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.


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).

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

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
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.


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.

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

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
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

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
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

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.

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

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.

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.

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.

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"}}

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.