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