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

# 查询视频生成状态

## 说明

根据任务 ID 查询视频生成任务的当前状态、进度与最终结果。

<Note>
  视频生成为异步任务，建议创建任务后每 5–10 秒轮询一次状态，直到返回 `completed` 或 `failed`。
</Note>

## 接口概览

| 项目           | 值                                           |
| :----------- | :------------------------------------------ |
| 接口地址         | `https://api.senseaudio.cn/v1/video/status` |
| 请求方式         | `GET`                                       |
| Content-Type | `application/json`                          |
| 鉴权方式         | Bearer Token                                |

## 请求头

| 参数名             |  必填 | 说明                                      | 示例                    |
| :-------------- | :-: | :-------------------------------------- | :-------------------- |
| `Authorization` |  是  | 鉴权 Token，格式 `Bearer SENSEAUDIO_API_KEY` | `Bearer sk-123456...` |
| `Content-Type`  |  是  | 固定为 `application/json`                  | `application/json`    |

## 请求参数（Query）

| 参数名  | 类型     |  必填 | 描述            |
| :--- | :----- | :-: | :------------ |
| `id` | string |  是  | 创建任务时返回的任务 ID |

## 响应结构

| 参数名                 | 类型      | 描述                      |
| :------------------ | :------ | :---------------------- |
| `id`                | string  | 记录 ID                   |
| `model`             | string  | 模型名称                    |
| `task_id`           | string  | 任务 ID                   |
| `status`            | string  | 任务状态，见下表                |
| `progress`          | int64   | 进度百分比                   |
| `video_url`         | string  | 视频 URL（`completed` 后返回） |
| `duration`          | int64   | 实际视频时长（秒）               |
| `is_new`            | boolean | 是否为新视频                  |
| `error_message`     | string  | 错误信息（`failed` 时返回）      |
| `created_at`        | int64   | 创建时间戳                   |
| `completed_at`      | int64   | 完成时间戳                   |
| `prompt`            | string  | 提示词                     |
| `resolution`        | string  | 分辨率，如 `720p`            |
| `ratio`             | string  | 宽高比，如 `16:9`、`9:16`     |
| `content`           | array   | 描述视频的文字或图片              |
| `provider_specific` | object  | 模型特殊参数                  |

### 状态说明

| 状态值          | 说明   |
| :----------- | :--- |
| `pending`    | 等待处理 |
| `processing` | 处理中  |
| `completed`  | 已完成  |
| `failed`     | 失败   |

### 响应示例

```json theme={null}
{
  "id": "52e0c397-2f78-4c1f-8774-d51aba5e4e3c",
  "model": "Seedance-2.0",
  "task_id": "c4666acd-60fa-4e1e-8c8b-72ae129f7a4d",
  "status": "pending",
  "progress": 0,
  "duration": 10,
  "is_new": true,
  "created_at": 1773822549,
  "prompt": "",
  "resolution": "720p",
  "content": [
    {
      "type": "text",
      "text": "黄昏海边，海浪轻轻拍打礁石，镜头缓慢推进"
    }
  ],
  "ratio": "16:9"
}
```

## 代码示例

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.senseaudio.cn/v1/video/status?id=task_1234567890" \
  -H "Authorization: Bearer SENSEAUDIO_API_KEY" \
  -H "Content-Type: application/json"
  ```

  ```python Python theme={null}
  import requests
  import time

  API_URL = "https://api.senseaudio.cn/v1/video/status"
  HEADERS = {
      "Authorization": "Bearer SENSEAUDIO_API_KEY",
      "Content-Type": "application/json"
  }

  def get_video_status(task_id):
      resp = requests.get(API_URL, headers=HEADERS, params={"id": task_id})
      return resp.json() if resp.status_code == 200 else None

  def poll_video_status(task_id, max_attempts=60):
      """轮询视频状态直到完成"""
      for _ in range(max_attempts):
          result = get_video_status(task_id)
          if result:
              status = result.get("status")
              progress = result.get("progress", 0)
              print(f"状态: {status}, 进度: {progress}%")
              if status == "completed":
                  print(f"视频生成完成: {result.get('video_url')}")
                  return result
              if status == "failed":
                  print(f"生成失败: {result.get('error_message')}")
                  return result
          time.sleep(5)
      return None

  result = poll_video_status("task_1234567890")
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');

  const API_URL = 'https://api.senseaudio.cn/v1/video/status';
  const HEADERS = {
    'Authorization': 'Bearer SENSEAUDIO_API_KEY',
    'Content-Type': 'application/json'
  };

  async function getVideoStatus(taskId) {
    const res = await axios.get(API_URL, { headers: HEADERS, params: { id: taskId } });
    return res.data;
  }

  async function pollVideoStatus(taskId, maxAttempts = 60) {
    for (let i = 0; i < maxAttempts; i++) {
      const result = await getVideoStatus(taskId);
      if (result) {
        const { status, progress } = result;
        console.log(`状态: ${status}, 进度: ${progress}%`);
        if (status === 'completed') {
          console.log(`视频生成完成: ${result.video_url}`);
          return result;
        }
        if (status === 'failed') {
          console.log(`生成失败: ${result.error_message}`);
          return result;
        }
      }
      await new Promise(r => setTimeout(r, 5000));
    }
    return null;
  }

  pollVideoStatus('task_1234567890').then(console.log);
  ```
</CodeGroup>

## 注意事项

<Note>
  * **轮询建议**：视频生成需要时间，建议每 5–10 秒查询一次状态
  * **超时处理**：如果长时间处于 `processing` 状态，可能需要重新创建任务
  * **错误处理**：当 `status` 为 `failed` 时，查看 `error_message` 了解失败原因
</Note>


## OpenAPI

````yaml GET /v1/video/status
openapi: 3.1.0
info:
  title: SenseAudio Open Platform API
  description: >-
    SenseAudio 开放平台
    API，覆盖语音合成、语音识别、音色能力、音乐生成、图片生成、视频生成、智能体与大语言模型等能力。未显式说明的字段为依据素材文档推断。
  version: 1.0.0
servers:
  - url: https://api.senseaudio.cn
    description: 生产环境
security:
  - bearerAuth: []
paths:
  /v1/video/status:
    get:
      tags:
        - Video
      summary: 查询视频生成状态
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoStatusResponse'
components:
  schemas:
    VideoStatusResponse:
      type: object
      properties:
        id:
          type: string
          description: 记录 ID
        model:
          type: string
          description: 模型名称
        task_id:
          type: string
          description: 任务 ID
        status:
          type: string
          description: 任务状态
          enum:
            - pending
            - processing
            - completed
            - failed
        progress:
          type: integer
          format: int64
          description: 进度百分比
        video_url:
          type: string
          description: 视频 URL（completed 后返回）
        duration:
          type: integer
          format: int64
          description: 实际视频时长（秒）
        is_new:
          type: boolean
          description: 是否为新视频
        error_message:
          type: string
          description: 错误信息（failed 时返回）
        created_at:
          type: integer
          format: int64
          description: 创建时间戳
        completed_at:
          type: integer
          format: int64
          description: 完成时间戳
        prompt:
          type: string
          description: 提示词
        resolution:
          type: string
          description: 分辨率，如 720p、1080p
        ratio:
          type: string
          description: 宽高比，如 16:9、9:16、4:3、3:4、1:1
        content:
          type: array
          description: 描述视频的文字、图片、音频或视频
          items:
            type: object
            required:
              - type
            properties:
              type:
                type: string
                description: 内容类型
                enum:
                  - text
                  - image
                  - audio
                  - video
              text:
                type: string
                description: 文本内容（type=text 时使用）
              url:
                type: string
                description: 图片 URL（type=image 时使用）
              role:
                type: string
                description: 图片作用（type=image 时使用）
                enum:
                  - first_frame
                  - last_frame
                  - reference
              audio_url:
                type: string
                description: 音频 URL（type=audio 时使用）
              video_url:
                type: string
                description: 视频 URL（type=video 时使用）
        provider_specific:
          $ref: '#/components/schemas/VideoProviderSpecific'
    VideoProviderSpecific:
      type: object
      description: 厂商特定参数
      properties:
        generate_audio:
          type: boolean
          description: 是否生成音频
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
      description: 格式：`Bearer <API_KEY>`

````