gen_task_get
Check status and outputs of ModelArk generation tasks (Seedance video, 3D).
Pass every task ID in one call. queued or running is not a failure: poll again after recommended_poll_after_ms, never resubmit the create tool (that bills a second task). Provider output URLs expire in about 24 hours; once all_terminal is true, call again through ark_job_submit with persist_output=true to keep durable artifacts. IDs the caller does not own are listed in errors.
| Requirement | Value |
|---|---|
| Registration | Requires BYTEPLUS_MODELARK_API_KEY. |
| Execution | Foreground or background |
| Required permission | gen:read |
This site lists the full configured capability surface, not the tools enabled on your particular server. Use model discovery and job discovery to check your connection. Credentials are server configuration, never tool arguments.
Ask your connected AI client to use gen_task_get for the operation you want.
The client constructs the arguments and handles tool calls. Review its proposed
operation before approving anything billable. For a non-billable introduction,
start with discovery without generation.
Use a direct foreground call for lightweight operations. Submit through ark_job_submit when output persistence or a large download may take time. The full arguments still include the input wrapper.
Exact MCP call (for developers)
The following is an MCP tool-call envelope, not a shell command. Example media URLs and identifiers must be replaced with your own accessible resources. Seedream and Seedance examples are non-billable dry runs; other provider operations may incur charges.
{ "name": "gen_task_get", "arguments": { "input": { "task_ids": [ "cgt-example-replace-me" ], "persist_output": false } }}An Ark job ID is not a provider task ID. Video and 3D tasks use gen_task_get, VOD tasks use vod_get_task, and avatars use omnihuman_get_task. Save accepted provider task IDs and resume polling instead of submitting a second generation.
Inputs
Section titled “Inputs”The MCP arguments object wraps these fields as {"input": {...}}.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
output_dir |
string or null | No | Optional local directory for succeeded tasks’ outputs, written as <artifact_id>. |
overwrite |
boolean | No | Replace an existing file at output_path/output_dir when its content differs (identical content is always accepted).; Default: false |
persist_output |
boolean | No | Copy each succeeded task’s outputs into durable artifact storage, once per task. Requires background execution (ark_job_submit or native task augmentation); leave false for a foreground status poll.; Default: false |
task_ids |
array of string | Yes | 1-50 ModelArk generation task IDs returned by seedance_create_task, hyper3d_create_task, or hitem3d_create_task (not ark_job IDs). Duplicates are ignored.; minItems: 1; maxItems: 50 |
Outputs
Section titled “Outputs”| Field | Type | Required | Description and constraints |
|---|---|---|---|
active_tasks |
integer | Yes | Number of found tasks still queued or running. |
all_terminal |
boolean | Yes | True when every found task has finished, so polling can stop. |
errors |
array of GenTaskLookupError | No | Task IDs that could not be checked (NOT_OWNED, NOT_FOUND, or a provider code). |
recommended_poll_after_ms |
integer or null | No | Suggested delay in milliseconds before the next poll; null when all_terminal.; Default: null |
tasks |
array of GenTask | Yes | One entry per found task, in request order. |
Nested Types
Section titled “Nested Types”Field types named above refer to these shared definitions. Optional/null fields, enum choices and bounds are retained in the complete schemas below. Schema validation is followed by runtime capability and security checks.
GenTaskGetInput
| Field | Type | Required | Description and constraints |
|---|---|---|---|
output_dir |
string or null | No | Optional local directory for succeeded tasks’ outputs, written as <artifact_id>. |
overwrite |
boolean | No | Replace an existing file at output_path/output_dir when its content differs (identical content is always accepted).; Default: false |
persist_output |
boolean | No | Copy each succeeded task’s outputs into durable artifact storage, once per task. Requires background execution (ark_job_submit or native task augmentation); leave false for a foreground status poll.; Default: false |
task_ids |
array of string | Yes | 1-50 ModelArk generation task IDs returned by seedance_create_task, hyper3d_create_task, or hitem3d_create_task (not ark_job IDs). Duplicates are ignored.; minItems: 1; maxItems: 50 |
Complete JSON Schemas
Section titled “Complete JSON Schemas”Input schema, including the MCP wrapper
{ "$defs": { "GenTaskGetInput": { "description": "Input model for ``gen_task_get``.", "properties": { "output_dir": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Optional local directory for succeeded tasks' outputs, written as <artifact_id>.<ext>. stdio only; absolute path inside an allowed output root (client MCP roots or OUTPUT_ROOTS). The durable artifact is always kept; the copy is reported in ArtifactRef.local_path." }, "overwrite": { "default": false, "description": "Replace an existing file at output_path/output_dir when its content differs (identical content is always accepted).", "type": "boolean" }, "persist_output": { "default": false, "description": "Copy each succeeded task's outputs into durable artifact storage, once per task. Requires background execution (ark_job_submit or native task augmentation); leave false for a foreground status poll.", "type": "boolean" }, "task_ids": { "description": "1-50 ModelArk generation task IDs returned by seedance_create_task, hyper3d_create_task, or hitem3d_create_task (not ark_job IDs). Duplicates are ignored.", "items": { "type": "string" }, "maxItems": 50, "minItems": 1, "type": "array" } }, "required": [ "task_ids" ], "type": "object" } }, "additionalProperties": false, "properties": { "input": { "$ref": "#/$defs/GenTaskGetInput" } }, "required": [ "input" ], "type": "object"}Output schema, including nested definitions
{ "$defs": { "ArtifactPersistenceIssue": { "description": "Safe explanation for a provider output that could not be persisted.", "properties": { "artifact_limit_bytes": { "description": "Maximum durable artifact size in bytes.", "title": "Artifact Limit Bytes", "type": "integer" }, "code": { "description": "Failure category.", "enum": [ "untrusted_output_host", "output_too_large", "invalid_output_mime", "source_expired", "download_failed", "storage_failed" ], "title": "Code", "type": "string" }, "message": { "description": "Safe failure message (no credentials or URLs).", "title": "Message", "type": "string" }, "retryable": { "description": "Whether retrying persistence later may succeed.", "title": "Retryable", "type": "boolean" }, "source_url_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of the unpersisted provider URL (the artifact uri).", "title": "Source Url Expires At" } }, "required": [ "code", "message", "retryable", "artifact_limit_bytes" ], "title": "ArtifactPersistenceIssue", "type": "object" }, "ArtifactRef": { "description": "Stable reference to a persisted media artifact.", "properties": { "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Size in bytes.", "title": "Bytes" }, "created_at": { "description": "ISO-8601 timestamp of artifact creation.", "title": "Created At", "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of the stored artifact.", "title": "Expires At" }, "export_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Why the requested local copy was not written (the artifact is unaffected).", "title": "Export Error" }, "fallback_data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Base64 output bytes, only with id 'inline-fallback'.", "title": "Fallback Data" }, "id": { "description": "Unique artifact identifier.", "title": "Id", "type": "string" }, "local_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Absolute path of the local copy written for output_path/output_dir.", "title": "Local Path" }, "media_type": { "$ref": "#/$defs/MediaType", "description": "image, audio, video or three_d." }, "mime_type": { "description": "MIME type, e.g. image/png.", "title": "Mime Type", "type": "string" }, "persistence_error": { "anyOf": [ { "$ref": "#/$defs/ArtifactPersistenceIssue" }, { "type": "null" } ], "default": null, "description": "Set when the output was billed but not stored. id is then 'provider-url' (uri is the temporary provider URL; re-persist it with seed_media_persist_url before source_expires_at) or 'inline-fallback' (bytes in fallback_data)." }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "SHA-256 hex digest.", "title": "Sha256" }, "source_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of the provider URL.", "title": "Source Expires At" }, "uri": { "description": "MCP resource URI (seed-media://artifacts/{id}).", "title": "Uri", "type": "string" } }, "required": [ "id", "uri", "media_type", "mime_type", "created_at" ], "title": "ArtifactRef", "type": "object" }, "GenTask": { "description": "Status and outputs of one ModelArk generation task.", "properties": { "created_at": { "description": "ISO-8601 task creation time.", "title": "Created At", "type": "string" }, "draft": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "True for a Seedance Draft task (480p preview). Once it succeeds, pass task_id as draft_task_id to the Seedance create tool within 14 days of created_at (7 if created before 2026-10-28 10:00 UTC+8).", "title": "Draft" }, "error": { "anyOf": [ { "$ref": "#/$defs/TaskError" }, { "type": "null" } ], "default": null, "description": "Provider failure details when failed." }, "family": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Registry family of the model; null when the model is not configured on this server.", "title": "Family" }, "kind": { "description": "Output kind from the registry binding for model: video, 3d, or unknown.", "enum": [ "video", "3d", "unknown" ], "title": "Kind", "type": "string" }, "model": { "description": "Model ID that ran the task.", "title": "Model", "type": "string" }, "outputs": { "description": "Finished outputs: video and last_frame for video tasks, model_file for 3D tasks. Empty until the task succeeds.", "items": { "$ref": "#/$defs/TaskOutputFile" }, "title": "Outputs", "type": "array" }, "queue": { "anyOf": [ { "$ref": "#/$defs/SeedanceQueueInfo" }, { "type": "null" } ], "default": null, "description": "Server-derived queue timing for a queued or running video task. ModelArk publishes no queue position or ETA. Null once finished and for 3D tasks." }, "settings": { "anyOf": [ { "$ref": "#/$defs/SeedanceTaskSettings" }, { "type": "null" } ], "default": null, "description": "Video generation settings echoed by the provider; null for 3D tasks." }, "status": { "$ref": "#/$defs/GenTaskStatus", "description": "Task status: queued, running, succeeded, failed, cancelled, or expired." }, "task_id": { "description": "Provider task ID.", "title": "Task Id", "type": "string" }, "updated_at": { "description": "ISO-8601 time of the last status change.", "title": "Updated At", "type": "string" }, "usage": { "anyOf": [ { "$ref": "#/$defs/TaskUsage" }, { "type": "null" } ], "default": null, "description": "Token usage reported by the provider." } }, "required": [ "task_id", "model", "kind", "status", "created_at", "updated_at", "outputs" ], "title": "GenTask", "type": "object" }, "GenTaskLookupError": { "description": "A task ID that could not be checked.", "properties": { "code": { "description": "NOT_OWNED (not created by this caller), NOT_FOUND, or a provider error code.", "title": "Code", "type": "string" }, "message": { "description": "Human-readable reason.", "title": "Message", "type": "string" }, "task_id": { "description": "The task ID that could not be checked.", "title": "Task Id", "type": "string" } }, "required": [ "task_id", "code", "message" ], "title": "GenTaskLookupError", "type": "object" }, "GenTaskStatus": { "description": "Lifecycle state of a ModelArk generation task (Seedance, Hyper3D, Hitem3d).", "enum": [ "queued", "running", "cancelled", "succeeded", "failed", "expired", "unknown" ], "title": "GenTaskStatus", "type": "string" }, "MediaType": { "description": "Logical generated-media categories.", "enum": [ "image", "audio", "video", "three_d" ], "title": "MediaType", "type": "string" }, "SeedanceQueueInfo": { "description": "Server-derived queue timing for a Seedance task.\n\nModelArk publishes no queue position or ETA. These values are computed by\nthis server from the task's timestamps and expiry setting; they are\nestimates, not a provider SLA.", "properties": { "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 time after which the provider fails a task that has not finished: created_at + execution_expires_after. None for finished tasks.", "title": "Expires At" }, "expires_at_estimated": { "default": false, "description": "True when the provider did not report execution_expires_after and the documented default (48 hours) was assumed.", "title": "Expires At Estimated", "type": "boolean" }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Human-readable queue summary for reporting to the user.", "title": "Hint" }, "queued_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Seconds spent queued: now minus created_at while queued, or updated_at minus created_at once running (approximate). None for finished tasks.", "title": "Queued Seconds" }, "running_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Seconds since the last status update while running (approximate).", "title": "Running Seconds" }, "service_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Service tier ('default' or 'flex'). Flex tasks usually queue longer.", "title": "Service Tier" } }, "title": "SeedanceQueueInfo", "type": "object" }, "SeedanceTaskSettings": { "additionalProperties": true, "description": "Known Seedance settings, preserving provider extensions.", "properties": { "duration": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "null" } ], "default": null, "description": "Video duration in seconds, or 'auto'.", "title": "Duration" }, "generate_audio": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether an audio track was generated.", "title": "Generate Audio" }, "omni_reference_task_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider task type hint echoed by Seedance 2.5: auto, reference, edit, or extend.", "title": "Omni Reference Task Type" }, "priority": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Task priority (0-9).", "title": "Priority" }, "ratio": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Output aspect ratio (e.g. 16:9).", "title": "Ratio" }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Output video resolution.", "title": "Resolution" }, "return_last_frame": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "description": "Whether the last frame was returned as a separate image.", "title": "Return Last Frame" }, "service_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Service tier used (default or flex).", "title": "Service Tier" } }, "title": "SeedanceTaskSettings", "type": "object" }, "TaskError": { "description": "Safe provider failure detail for an asynchronous task.", "properties": { "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Provider failure code, when returned.", "title": "Code" }, "message": { "default": "", "description": "Failure explanation without credentials or signed URLs.", "title": "Message", "type": "string" } }, "title": "TaskError", "type": "object" }, "TaskOutputFile": { "description": "One output file of a finished task (ModelArk generation or VOD MediaKit).", "properties": { "artifact": { "anyOf": [ { "$ref": "#/$defs/ArtifactRef" }, { "type": "null" } ], "default": null, "description": "Durable artifact when persisted." }, "persistence": { "description": "Persistence outcome, independent of task success.", "enum": [ "not_requested", "persisted", "failed" ], "title": "Persistence", "type": "string" }, "persistence_issue": { "anyOf": [ { "$ref": "#/$defs/ArtifactPersistenceIssue" }, { "type": "null" } ], "default": null, "description": "Safe explanation when persistence failed." }, "role": { "description": "Output kind: video, last_frame (Seedance), model_file (3D), or voice, background, music, sfx (VOD audio separation).", "enum": [ "video", "last_frame", "model_file", "voice", "background", "music", "sfx" ], "title": "Role", "type": "string" }, "source_expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 expiry of source_url.", "title": "Source Expires At" }, "source_url": { "anyOf": [ { "format": "uri", "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Expiring provider URL (kept when persistence is skipped or fails).", "title": "Source Url" } }, "required": [ "role", "persistence" ], "title": "TaskOutputFile", "type": "object" }, "TaskUsage": { "description": "Token usage reported for a finished ModelArk generation task.", "properties": { "completion_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Completion tokens consumed, when reported.", "title": "Completion Tokens" }, "prompt_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Prompt tokens consumed, when reported.", "title": "Prompt Tokens" }, "total_tokens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Total tokens consumed, when reported.", "title": "Total Tokens" } }, "title": "TaskUsage", "type": "object" } }, "description": "Output model for ``gen_task_get``.", "properties": { "active_tasks": { "description": "Number of found tasks still queued or running.", "title": "Active Tasks", "type": "integer" }, "all_terminal": { "description": "True when every found task has finished, so polling can stop.", "title": "All Terminal", "type": "boolean" }, "errors": { "description": "Task IDs that could not be checked (NOT_OWNED, NOT_FOUND, or a provider code).", "items": { "$ref": "#/$defs/GenTaskLookupError" }, "title": "Errors", "type": "array" }, "recommended_poll_after_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Suggested delay in milliseconds before the next poll; null when all_terminal.", "title": "Recommended Poll After Ms" }, "tasks": { "description": "One entry per found task, in request order.", "items": { "$ref": "#/$defs/GenTask" }, "title": "Tasks", "type": "array" } }, "required": [ "tasks", "all_terminal", "active_tasks" ], "title": "GenTaskGetOutput", "type": "object"}Troubleshooting
Section titled “Troubleshooting”- Missing tool: check provider credentials and feature flags, then restart the connection.
- Invalid arguments: keep the correct wrapper and follow current model limits from discovery. A valid schema alone does not prove the chosen model supports the combination.
- A job completes with an error: inspect the original tool result, not only the outer job status. Never automatically resubmit potentially billable work.
- Local output writes from jobs require server-configured
OUTPUT_ROOTS; HTTP cannot write to a client’s local disk.
See configuration, background execution, and artifact delivery.