> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qingbo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 提交任务

> POST /v1/tasks — 提交异步生成任务

提交图像、视频或音频生成任务，立即返回 `task_id`。

## 请求参数

<ParamField body="model" type="string" required>
  模型名称，如 `"veo3"`, `"gpt-4o-image"`, `"sora2"`
</ParamField>

<ParamField body="action" type="string" default="generate">
  操作类型：`generate`, `edit`, `upscale`, `variation`, `blend`
</ParamField>

<ParamField body="prompt" type="string">
  生成描述文本
</ParamField>

<ParamField body="callback_url" type="string">
  任务完成时的 Webhook 回调地址
</ParamField>

<ParamField body="extra" type="object">
  模型特定参数的透传字段，直接传递给上游模型
</ParamField>

更多参数请参考 [图像生成概述](/cn/api-reference/image/overview) 或 [视频生成概述](/cn/api-reference/video/overview)。

## 响应

```json theme={"system"}
{
  "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
  "model": "veo3",
  "action": "generate",
  "status": "queued",
  "created_at": 1720000000,
  "progress": 0,
  "pre_consumed_cost": 5500
}
```

<ResponseField name="pre_consumed_cost" type="integer">
  提交时预扣的额度（quota）。任务完成后以查询接口返回的 `cost` 为准结算：
  成功 = 实际扣费；失败/取消 = 自动全额退款（`cost: 0`）。
</ResponseField>

## 请求内等待（Prefer: wait）

不想自己轮询时，加 `Prefer: wait=N` 请求头（N ≤ 60 秒）即可在一次调用里等待结果：

* **窗口内完成** → 直接返回终态完整结果（含 `result` 与 `cost`）
* **超窗未完成** → 返回当前状态 + `pre_consumed_cost`，继续用 `GET /v1/tasks/{task_id}` 轮询

```bash theme={"system"}
curl -X POST https://www.qingbo.dev/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Prefer: wait=60" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-image", "prompt": "A tiny blue circle"}'
```

适合图像生成等较快完成的任务、原型开发和测试。视频等长耗时任务建议轮询或 Webhook。

## 幂等提交（Idempotency-Key）

带 `Idempotency-Key: <唯一字符串>` 请求头提交时，24 小时内同一 key 的重复请求会
直接复用首次创建的任务（同一 `task_id`，不重复扣费）。适合网络重试场景。

## 示例

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo3",
      "action": "generate",
      "prompt": "A cat walking on the beach at sunset",
      "duration": 5
    }'
  ```

  ```python Python theme={"system"}
  import requests

  response = requests.post(
      "https://www.qingbo.dev/v1/tasks",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={
          "model": "veo3",
          "action": "generate",
          "prompt": "A cat walking on the beach at sunset",
          "duration": 5
      }
  )

  task_id = response.json()["task_id"]
  ```
</CodeGroup>