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