gen_task_list
List your ModelArk generation tasks (Seedance video and 3D), newest first.
Covers tasks created in the last 7 days, the provider’s list window. Filter by status, model, or task_ids, and follow next_cursor until it is null; keep the same filters while paging. Use gen_task_get for outputs.
| Requirement | Value |
|---|---|
| Registration | Requires BYTEPLUS_MODELARK_API_KEY. |
| Execution | Foreground only |
| 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_list 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.
Call this tool directly. It is not a background-job target.
Match the input fields below and the full JSON Schema. See the worked examples for this capability and Background Execution for job/result handling.
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 |
|---|---|---|---|
cursor |
string or null | No | Opaque next_cursor from a previous call made with the same filters.; Default: null |
model |
string or null | No | Only return tasks run by this exact model ID.; Default: null |
page_size |
integer | No | Maximum number of tasks to return.; minimum: 1; maximum: 100; Default: 20 |
status |
GenTaskStatus or null | No | Only return tasks in this status: queued, running, succeeded, failed, cancelled, or expired.; Default: null |
task_ids |
array of string or null | No | Only return these task IDs (up to 100); IDs the caller does not own are skipped.; Default: null |
Outputs
Section titled “Outputs”| Field | Type | Required | Description and constraints |
|---|---|---|---|
next_cursor |
string or null | No | Pass back as cursor to continue; null when there are no more tasks. A page may hold fewer than page_size tasks while next_cursor is non-null.; Default: null |
tasks |
array of GenTaskSummary | Yes | Matching tasks, newest first. |
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.
GenTaskListInput
| Field | Type | Required | Description and constraints |
|---|---|---|---|
cursor |
string or null | No | Opaque next_cursor from a previous call made with the same filters.; Default: null |
model |
string or null | No | Only return tasks run by this exact model ID.; Default: null |
page_size |
integer | No | Maximum number of tasks to return.; minimum: 1; maximum: 100; Default: 20 |
status |
GenTaskStatus or null | No | Only return tasks in this status: queued, running, succeeded, failed, cancelled, or expired.; Default: null |
task_ids |
array of string or null | No | Only return these task IDs (up to 100); IDs the caller does not own are skipped.; Default: null |
GenTaskStatus
No fields. Pass {}.
Complete JSON Schemas
Section titled “Complete JSON Schemas”Input schema, including the MCP wrapper
{ "$defs": { "GenTaskListInput": { "description": "Input model for ``gen_task_list``.", "properties": { "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Opaque next_cursor from a previous call made with the same filters." }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Only return tasks run by this exact model ID." }, "page_size": { "default": 20, "description": "Maximum number of tasks to return.", "maximum": 100, "minimum": 1, "type": "integer" }, "status": { "anyOf": [ { "$ref": "#/$defs/GenTaskStatus" }, { "type": "null" } ], "default": null, "description": "Only return tasks in this status: queued, running, succeeded, failed, cancelled, or expired." }, "task_ids": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "default": null, "description": "Only return these task IDs (up to 100); IDs the caller does not own are skipped." } }, "type": "object" }, "GenTaskStatus": { "description": "Lifecycle state of a ModelArk generation task (Seedance, Hyper3D, Hitem3d).", "enum": [ "queued", "running", "cancelled", "succeeded", "failed", "expired", "unknown" ], "type": "string" } }, "additionalProperties": false, "properties": { "input": { "$ref": "#/$defs/GenTaskListInput" } }, "required": [ "input" ], "type": "object"}Output schema, including nested definitions
{ "$defs": { "GenTaskStatus": { "description": "Lifecycle state of a ModelArk generation task (Seedance, Hyper3D, Hitem3d).", "enum": [ "queued", "running", "cancelled", "succeeded", "failed", "expired", "unknown" ], "title": "GenTaskStatus", "type": "string" }, "GenTaskSummary": { "description": "Summary of one ModelArk generation task.", "properties": { "created_at": { "description": "ISO-8601 task creation time.", "title": "Created At", "type": "string" }, "error": { "anyOf": [ { "$ref": "#/$defs/TaskError" }, { "type": "null" } ], "default": null, "description": "Failure details when the task failed." }, "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" }, "status": { "$ref": "#/$defs/GenTaskStatus", "description": "Task status." }, "task_id": { "description": "Provider task ID; pass it to gen_task_get for outputs.", "title": "Task Id", "type": "string" } }, "required": [ "task_id", "model", "kind", "status", "created_at" ], "title": "GenTaskSummary", "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" } }, "description": "Output model for ``gen_task_list``.", "properties": { "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pass back as cursor to continue; null when there are no more tasks. A page may hold fewer than page_size tasks while next_cursor is non-null.", "title": "Next Cursor" }, "tasks": { "description": "Matching tasks, newest first.", "items": { "$ref": "#/$defs/GenTaskSummary" }, "title": "Tasks", "type": "array" } }, "required": [ "tasks" ], "title": "GenTaskPage", "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.