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

# Async Tasks

> Use one request envelope and one task lifecycle across models.

The Unified API separates task submission from task completion. This keeps
client timeouts short while image and video models continue working in the
background.

## Submit

`POST /v1/task/submit` accepts the common envelope:

| Field          | Type   | Required | Description                                  |
| -------------- | ------ | -------- | -------------------------------------------- |
| `model`        | string | Yes      | Public model ID.                             |
| `input`        | object | Yes      | Model-specific parameters.                   |
| `callback_url` | string | No       | HTTPS endpoint notified at a terminal state. |

## Retrieve

`GET /v1/task/{task_id}` returns the current task state.

```text theme={null}
queued → processing → succeeded
                    ↘ failed
```

Only `succeeded` and `failed` are terminal. Clients should tolerate repeated
reads of the same state.

## Choose a completion strategy

<CardGroup cols={2}>
  <Card title="Polling" icon="refresh-cw" href="/en/unified-api/polling">
    Best for local tools, scripts, and the first integration.
  </Card>

  <Card title="Callbacks" icon="webhook" href="/en/unified-api/callbacks">
    Best for services that already expose a public HTTPS endpoint.
  </Card>
</CardGroup>

<Note>
  Polling and callbacks are complementary. Keep the read endpoint available as
  the recovery path when callback delivery is delayed.
</Note>