Skip to content

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.

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

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

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