> ## Documentation Index
> Fetch the complete documentation index at: https://docs-vip.apigo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# /api/v3/contents/generations/tasks/{task_id}

> 按任务 ID 查询生成状态与结果。

使用 `Authorization: Bearer <API_KEY>` 鉴权。

## 任务状态

| status | 说明 |
| - | - |
| `queued` | 排队中 |
| `running` | 生成中 |
| `succeeded` | 生成成功，成片地址位于 `content.video_url` |
| `failed` | 生成失败，原因位于 `error` |
| `cancelled` | 已取消 |
| `expired` | 已过期 |

`queued` 和 `running` 需继续轮询，其余为终态。建议每 10 秒查询一次。

## 结果字段

* `content.video_url` 是有时效的下载地址，请在过期前转存。过期后再查询不再返回 `video_url`。
* `content.expireAt` 是 `video_url` 的过期时间（Unix 秒）。
* `created_at`、`updated_at` 为 Unix 秒。
* `usage` 为实际用量。
* `priority`、`safety_identifier` 等字段是否返回，取决于创建时是否传入以及任务状态。

## 生成失败

任务创建后也可能生成失败。此时查询接口返回 HTTP 200，`status` 为 `failed`，`error` 中包含 `code`、`type` 和 `message`。参数或内容审核导致的失败返回对应错误码；服务内部或上游原因导致的失败，`code` 为 `InternalServiceError`。

```json theme={null}
{
  "id": "task_20261020080000abcdef",
  "model": "dreamina-seedance-2-0-260128",
  "status": "failed",
  "error": {
    "code": "InternalServiceError",
    "type": "InternalServerError",
    "message": "Media generation failed."
  },
  "created_at": 1792396500,
  "updated_at": 1792396620
}
```


## OpenAPI

````yaml api-reference/openapi.json GET /api/v3/contents/generations/tasks/{task_id}
openapi: 3.1.0
info:
  title: OpenAPI Plant Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api-vip.apigo.ai
security:
  - bearerAuth: []
paths:
  /api/v3/contents/generations/tasks/{task_id}:
    get:
      summary: 查询 Seedance 视频生成任务
      description: 按任务 ID 查询生成状态与结果。
      parameters:
        - name: task_id
          in: path
          required: true
          description: 创建任务时返回的 `id`。
          schema:
            type: string
            example: task_20261020080000abcdef
      responses:
        '200':
          description: 任务详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeedanceTask'
              example:
                id: task_20261020080000abcdef
                model: dreamina-seedance-2-0-260128
                status: succeeded
                content:
                  video_url: https://media.example.com/result.mp4?signature=xxx
                  expireAt: 1792483200
                created_at: 1792396500
                updated_at: 1792396800
                resolution: 720p
                ratio: '16:9'
                duration: 5
                generate_audio: true
                framespersecond: 24
                priority: 0
                usage:
                  completion_tokens: 100000
                  total_tokens: 100000
        '401':
          description: API Key 缺失或无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeedanceErrorResponse'
              example:
                error:
                  code: AuthenticationError
                  message: The API key is missing or invalid.
                  param: ''
                  type: Unauthorized
        '403':
          description: 余额不足，或 IP 白名单、模型权限不允许调用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeedanceErrorResponse'
              example:
                error:
                  code: AccountOverdueError
                  message: Your account balance is insufficient.
                  param: ''
                  type: Forbidden
        '404':
          description: 任务不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeedanceErrorResponse'
              example:
                error:
                  code: NotFound
                  message: The specified task task_20261020080000abcdef is not found.
                  param: ''
                  type: NotFound
        '429':
          description: 请求过频或达到 API Key 额度
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeedanceErrorResponse'
              example:
                error:
                  code: AccountRateLimitExceeded
                  message: Too many requests, please retry later.
                  param: ''
                  type: TooManyRequests
components:
  schemas:
    SeedanceTask:
      type: object
      properties:
        id:
          type: string
          description: 任务 ID。
        model:
          type: string
          description: 模型 ID。
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - failed
            - cancelled
            - expired
          description: >-
            任务状态。`queued`、`running`
            为进行中；`succeeded`、`failed`、`cancelled`、`expired` 为终态。
        content:
          type: object
          description: 生成结果，`status=succeeded` 时返回。
          properties:
            video_url:
              type: string
              description: 成片下载地址，有时效，请及时转存。
            expireAt:
              type: integer
              description: '`video_url` 的过期时间，Unix 秒。'
        error:
          type: object
          description: 失败原因，`status=failed` 时返回。
          properties:
            code:
              type: string
              description: 错误码，例如 `InvalidParameter`。
            message:
              type: string
              description: 错误描述。
            type:
              type: string
              description: 错误类型，例如 `BadRequest`。
        created_at:
          type: integer
          description: 创建时间，Unix 秒。
        updated_at:
          type: integer
          description: 更新时间，Unix 秒。
        resolution:
          type: string
          description: 输出分辨率，例如 `720p`。
        ratio:
          type: string
          description: 画面比例，例如 `16:9`、`1:1`。
        duration:
          type: integer
          description: 视频时长（秒）。
        generate_audio:
          type: boolean
          description: 是否生成声音。使用参考音频或参考视频原声时传 `true`。
        framespersecond:
          type: integer
          description: 帧率。
        priority:
          type: integer
          description: 任务优先级。传入后会在查询结果中回传。
        safety_identifier:
          type: string
          description: 终端用户标识，建议使用不可逆的哈希值。传入后会在查询结果中回传。
        usage:
          type: object
          description: 实际用量。
          properties:
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
    SeedanceErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          description: 错误对象。
          properties:
            code:
              type: string
              description: 错误码，例如 `InvalidParameter`。
            message:
              type: string
              description: 错误描述。
            param:
              type: string
              description: 出错的参数名，可能为空。
            type:
              type: string
              description: 错误类型，例如 `BadRequest`。
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.