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

## 身份驗證

需要 Bearer 令牌。參見 [身份驗證](/api-reference/authentication)。

## 請求體

<ParamField body="prompt" type="string" required>
  研究問題或主題。
</ParamField>

<ParamField body="depth" type="string" default="advanced">
  研究深度。`"basic"` 用於快速摘要，`"advanced"` 用於全面的多信息源分析。
</ParamField>

<ParamField body="max_sources" type="integer" default="10">
  可參考的最大信息源數量（1–50）。
</ParamField>

## 請求示例

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/research \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Compare React, Vue, and Svelte for enterprise apps in 2026",
      "depth": "advanced",
      "max_sources": 10
    }'
  ```

  ```typescript SDK theme={null}
  const job = await theo.research({
    prompt: "Compare React, Vue, and Svelte for enterprise apps in 2026",
    depth: "advanced",
    max_sources: 10,
  });

  // Poll until complete (check every 3s, timeout after 2min)
  const result = await theo.waitForJob(job.job_id, 3000, 120_000);
  console.log(result.result); // Full research report with citations
  ```
</CodeGroup>

## 響應（HTTP 202）

<ResponseField name="id" type="string">
  唯一的研究請求 ID（以 `res_` 為前綴）。
</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。
</ResponseField>

### 響應示例

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

## 錯誤

| 狀態碼 | 錯誤碼 | 說明 |
| - | - | - |
| 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.