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

# 获取任务状态

> 轮询异步任务（视频、研究等）的状态。

获取一个异步任务的当前状态。用于从 [Video](/api-reference/video/generate) 和 [Research](/api-reference/research/create) 端点轮询结果。

## 认证

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

## 路径参数

<ParamField path="id" type="string" required>
  异步端点返回的任务 ID（例如 `job_xyz789`）。
</ParamField>

## 请求示例

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

  ```typescript SDK theme={null}
  // 单次轮询
  const status = await theo.job("job_xyz789");
  console.log(status.status, status.progress);

  // 自动轮询直到完成（推荐）
  const result = await theo.waitForJob("job_xyz789");
  console.log(result.result);
  ```
</CodeGroup>

## 响应

<ResponseField name="id" type="string">
  任务 ID。
</ResponseField>

<ResponseField name="type" type="string">
  任务类型（例如 `"video"`、`"research"`）。
</ResponseField>

<ResponseField name="status" type="string">
  当前状态：`"queued"`、`"active"`、`"completed"` 或 `"failed"`。
</ResponseField>

<ResponseField name="progress" type="number">
  进度百分比（0–100）。
</ResponseField>

<ResponseField name="result" type="object | null">
  任务结果。在状态变为 `"completed"` 之前为 `null`。其具体结构取决于任务的 `type` —— 参见下方的[各类型的结果模式](#result-schemas-by-type)。任何提供方/模型标识始终以 Theo 品牌呈现（`engine` / `model`），绝不暴露原始上游名称。
</ResponseField>

<ResponseField name="error" type="string | null">
  当状态为 `"failed"` 时的错误信息。
</ResponseField>

<ResponseField name="created_at" type="string | null">
  任务创建的时间。
</ResponseField>

<ResponseField name="completed_at" type="string | null">
  任务完成（或失败）的时间。
</ResponseField>

### 响应示例（已完成）

`result` 是一个**对象**，而非单纯的 URL。以视频任务为例：

```json theme={null}
{
  "id": "job_xyz789",
  "type": "video",
  "status": "completed",
  "progress": 100,
  "result": {
    "videoUrl": "https://artifacts.hitheo.ai/video/xyz789.mp4",
    "model": "Theo Motion",
    "engine": "theo-motion",
    "durationMs": 90000
  },
  "error": null,
  "created_at": "2026-04-10T12:00:00Z",
  "completed_at": "2026-04-10T12:01:30Z"
}
```

### 响应示例（进行中）

```json theme={null}
{
  "id": "job_xyz789",
  "type": "research",
  "status": "active",
  "progress": 45,
  "result": null,
  "error": null,
  "created_at": "2026-04-10T12:00:00Z",
  "completed_at": null
}
```

<Tip>
  SDK 的 `theo.waitForJob(jobId, { intervalMs, maxWaitMs, signal, onProgress })` 会以可配置的间隔（默认 2 秒）自动轮询，支持整体超时（默认 5 分钟）、可选的 `AbortSignal`，以及 `onProgress` 回调。旧版的位置参数形式 `waitForJob(id, intervalMs, maxWaitMs)` 依然可用。参见[异步任务指南](/guides/async-jobs)。
</Tip>

## 各类型的结果模式

`result` 对象因任务 `type` 而异。这些结构与 SDK 中的类型化结果接口（`ResearchJobResult`、`VideoJobResult`、`ImageJobResult`、`DocumentJobResult`）一一对应 —— 使用 `theo.waitForJob<VideoJobResult>(...)` 轮询即可获得对应类型。

**`research`**

```json theme={null}
{
  "report": "# Markdown report with inline citations...",
  "sources": [{ "title": "Source title", "url": "https://..." }],
  "queries": ["generated search query"],
  "sourceCount": 8
}
```

**`video`**

```json theme={null}
{ "videoUrl": "https://...", "model": "Theo Motion", "engine": "theo-motion", "durationMs": 90000 }
```

**`image`**

```json theme={null}
{ "imageUrl": "https://...", "model": "Theo Studio", "engine": "theo-studio" }
```

**`document`**

```json theme={null}
{ "title": "Report", "format": "pdf", "downloadUrl": "https://...", "sizeBytes": 248000 }
```

## 端点

`GET /api/v1/jobs/{id}`

需要通过 Bearer 令牌进行认证。参见[认证](/api-reference/authentication)。


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