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

# 生成视频

> 根据文本提示生成视频（异步）。

根据文本提示生成视频。这是一个**异步**端点——它会立即返回一个任务 ID（HTTP 202），视频将在后台生成。

<Warning>
  视频生成是异步的。请使用 [获取任务状态](/api-reference/jobs/get) 轮询任务状态，或在 SDK 中使用 `theo.waitForJob()`。
</Warning>

<Note>
  **AI 披露水印。** 由 Theo 返回的每个视频右下角都带有一个小型半透明的 Theo 徽标。这是一个溯源标识，用于标明该片段为 AI 生成，并且始终会被应用（无论品牌偏好设置如何）。每个片段预计会因重新编码而增加 2-15 秒的延迟。
</Note>

## 身份验证

需要 Bearer 令牌。参见 [身份验证](/api-reference/authentication)。

## 请求体

<ParamField body="prompt" type="string" required>
  要生成的视频的文本描述。
</ParamField>

<ParamField body="duration" type="string">
  目标视频时长（例如 `"5s"`、`"10s"`、`"15s"`）。
</ParamField>

<ParamField body="style" type="string">
  视觉风格（例如 `"cinematic"`、`"animation"`、`"timelapse"`）。
</ParamField>

## 请求示例

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/video \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "A 5-second animation of a rocket launch",
      "duration": "5s",
      "style": "cinematic"
    }'
  ```

  ```typescript SDK theme={null}
  const job = await theo.video({
    prompt: "A 5-second animation of a rocket launch",
    duration: "5s",
    style: "cinematic",
  });

  // Poll until complete
  const result = await theo.waitForJob(job.job_id);
  console.log(result.result); // Video URL
  ```
</CodeGroup>

## 响应（HTTP 202）

<ResponseField name="id" type="string">
  唯一的视频请求 ID（以 `vid_` 为前缀）。
</ResponseField>

<ResponseField name="job_id" type="string">
  用于轮询状态的任务 ID。
</ResponseField>

<ResponseField name="status" type="string">
  创建时始终为 `"queued"`。
</ResponseField>

<ResponseField name="created" type="string">
  ISO 8601 时间戳。
</ResponseField>

<ResponseField name="poll_url" type="string">
  用于轮询任务状态的相对 URL（例如 `/api/v1/jobs/{job_id}`）。
</ResponseField>

### 响应示例

```json theme={null}
{
  "id": "vid_abc123",
  "job_id": "job_xyz789",
  "status": "queued",
  "created": "2026-04-10T12:00:00Z",
  "poll_url": "/api/v1/jobs/job_xyz789"
}
```

## 轮询结果

使用 [获取任务状态](/api-reference/jobs/get) 端点检查进度。当 `status` 为 `"completed"` 时，`result` 字段将包含视频 URL。

```bash theme={null}
curl https://www.hitheo.ai/api/v1/jobs/job_xyz789 \
  -H "Authorization: Bearer $THEO_API_KEY"
```

## 错误

| 状态码 | 代码 | 描述 |
| - | - | - |
| 400 | `missing_prompt` | 缺少必需的 `prompt` 参数 |
| 401 | `invalid_api_key` | API 密钥缺失或无效 |
| 503 | `queue_unavailable` | 视频生成队列当前不可用——请稍后重试 |


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