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

# Submit Task

> POST /v1/tasks — Submit an asynchronous generation task

Submit an image, video, or audio generation task and immediately receive a `task_id`.

## Request Parameters

<ParamField body="model" type="string" required>
  Model name, such as `"veo3"`, `"gpt-4o-image"`, `"sora2"`
</ParamField>

<ParamField body="action" type="string" default="generate">
  Action type: `generate`, `edit`, `upscale`, `variation`, `blend`
</ParamField>

<ParamField body="prompt" type="string">
  Generation prompt text
</ParamField>

<ParamField body="callback_url" type="string">
  Webhook URL invoked when the task completes
</ParamField>

<ParamField body="extra" type="object">
  Pass-through field for model-specific parameters; forwarded directly to the upstream model
</ParamField>

For more parameters, see [Image Generation Overview](/en/api-reference/image/overview) or [Video Generation Overview](/en/api-reference/video/overview).

## Response

```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 pre-deducted at submission. The final charge is the `cost` field returned
  by the status endpoint once the task reaches a terminal state: success = actual
  charge; failure/cancellation = automatic full refund (`cost: 0`).
</ResponseField>

## In-Request Waiting (Prefer: wait)

If you'd rather not poll, add a `Prefer: wait=N` header (N ≤ 60 seconds) to wait
for the result within a single call:

* **Completed within the window** → the full terminal result is returned directly (including `result` and `cost`)
* **Window exceeded** → the current state plus `pre_consumed_cost` is returned; continue polling `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"}'
```

Best suited for fast tasks such as image generation, prototyping, and testing.
For long-running tasks (video), prefer polling or webhooks.

## Idempotent Submission (Idempotency-Key)

Submit with an `Idempotency-Key: <unique-string>` header and repeated requests
with the same key within 24 hours reuse the originally created task (same
`task_id`, no double billing). Useful for network-retry scenarios.

## Examples

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