CAPI
文档目录
文档/Task API/Task API Quickstart

Task API Quickstart

Create an asynchronous Task and handle polling, completion, failure, and retries.

2 分钟阅读

此页正文目前仅提供英文版本,我们正在陆续补充中文翻译。界面与导航已完成中文化。

Video generation runs as an asynchronous task. Image generation and editing return synchronously.

Why tasks instead of blocking calls

Media generation takes seconds to minutes. Holding an HTTP connection open for that long invites timeouts and makes retries ambiguous. Tasks separate submission from retrieval:

  1. POST the generation request and receive a task_id.
  2. Poll the task endpoint for its status and result.
  3. Read the output URL from the completed task.

Submit a video task

Use the provider-neutral endpoint. The model selects an enabled video model and the provider channel remains an implementation detail. Idempotency-Key is required for safe retries.

SHELL
curl -X POST https://capi.minapp.xin/api/v1/videos \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: demo-video-001" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_VIDEO_MODEL","prompt":"A paper kite above a coastal town at sunrise"}'

The response is a task envelope. Idempotency-Key is required; repeating a request with the same key returns the existing task.

JSON
{
  "id": "video_1_demo-video-001",
  "object": "video.task",
  "status": "running"
}

Poll a task

SHELL
curl https://capi.minapp.xin/api/v1/tasks/tsk_8f21c4ba \
  -H "Authorization: Bearer YOUR_API_TOKEN"

The status is submitting, running, unknown, succeeded, or failed. The API does not currently return progress or ETA.

On completion:

JSON
{
  "id": "video_1_demo-video-001",
  "object": "video.task",
  "status": "succeeded",
  "model": "YOUR_VIDEO_MODEL",
  "result": {
    "url": "https://capi.example/api/v1/files/file_.../content?token=...",
    "file_id": "file_...",
    "archived": true
  },
  "error": null,
  "created_at": 1770000000,
  "updated_at": 1770000120
}

Generated video files are archived for 30 days. The signed result URL is valid for one hour; poll the task again to receive a fresh URL.

Handle failure

A failed task releases its reserved amount. The API returns the provider error as a message:

JSON
{
  "id": "video_1_demo-video-001",
  "object": "video.task",
  "status": "failed",
  "error": { "message": "The provider rejected the request." }
}

An unknown status means the upstream submission could not be reconciled yet. Its reserved amount stays held until the task is reconciled.

Concurrency and rate limits

The service limits the number of active video tasks per workspace. A limit or insufficient balance returns an error when the task is submitted.

Next steps

上一页Authentication下一页Quickstart