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