Guide

Asynchronous media tasks: submit, retrieve and verify

Preview guide

Paste into an AI assistant to help with integration. Documentation and examples only; no real credentials.

# Asynchronous media tasks: submit, retrieve and verify

Use the model task protocol. Generic /async is retired (410), and /get-async was removed (404). Poll the corresponding task endpoint and verify the resulting media.

## Beginner: choose the model task protocol

Copy the exact model ID and submit example from the marketplace. Poll only when the response actually returns a task ID. HTTP 200 does not prove that media generation completed.

## Retired generic wrapper

`/async/*` is retired and returns HTTP 410 `endpoint_deprecated` after authentication; `/get-async` was removed and returns 404. Do not prefix arbitrary paths with `/async` or use the old nested task and Base64 result envelope. Synchronous and SSE requests keep their original protocols.

## Pair submission with retrieval

| Submission protocol | Retrieval endpoint | Successful / failed terminal state |
| --- | --- | --- |
| Unified video or asynchronous image | `GET /v1/videos/{task_id}` | Adapter-specific; commonly completed / failed |
| Native FLUX flux-3-image | `GET /flux/v1/get_result?id={task_id}` | Ready / Error |
| Suno v2 | `GET /suno/v2/fetch/{task_id}` | data.status: SUCCESS / FAILURE |
| Kling | `GET /kling/v1/{category}/{kind}/{task_id}` | data.status: SUCCESS / FAILURE |
| Midjourney | `GET /mj/task/{task_id}/fetch` | status: SUCCESS / FAILURE |

Preserve the Kling category/kind and any Midjourney mode prefix used at submission. IDs, response fields and status capitalization differ by protocol. Use the owning account and appropriately authorized key.

## Retrieve and download

This example only retrieves an existing FLUX task:

```bash
curl --fail-with-body "$BASE_URL/flux/v1/get_result?id=$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"
```

Wait while Pending, download result.sample when Ready, and stop with the reported error when Error. `GET /v1/videos/{task_id}/content` returns media bytes on success, not JSON. Result links and retention depend on the protocol and storage configuration; save needed results promptly.

## Backoff, timeouts and usage

Use bounded backoff such as 1, 2, 4 and 8 seconds, a maximum interval and an overall deadline. A timeout may occur after upstream acceptance; never blindly resubmit. Save task and request IDs and use request IDs to correlate usage logs. Precharging and settlement do not imply successful generation.

## Expert: recovery and diagnostics

`GET /v1/images/generations/result?request_id=...` recovers stored image URLs; it is not a general task endpoint. processing_or_not_found cannot distinguish pending, missing, inaccessible or URL-less results. Do not poll indefinitely or resubmit automatically. Acceptance requires a successful terminal state and readable media; receiving a task ID alone is insufficient.

## Use cases

- Long-running media and batch requests
- Avoid client timeouts and retrieve results reliably

## API paths

- /v1/videos
- /v1/videos/{task_id}
- /flux/v1/get_result
- /suno/v2/fetch/{task_id}

## Related guides

- [API endpoint and capability matrix](https://api.tu-zi.com/en/docs/use-cases/endpoint-matrix): Confirm the exact model and enabled endpoint in the marketplace first, then select a protocol here. A registered route only means the gateway recognizes it, not that every model or channel supports it.
- [Video generation and asynchronous API guide](https://api.tu-zi.com/en/docs/use-cases/video-generation): Design video generation as an asynchronous job system with idempotent submit, persisted IDs, bounded polling or verified callbacks, terminal handling, output transfer, and moderation.
- [File and media input, output, and lifecycle](https://api.tu-zi.com/en/docs/use-cases/files-media): The gateway `/v1/files` routes are currently not implemented. Attach files in a form supported by the target model and endpoint, and treat every input or output URL as a permissioned resource with a lifecycle.
- [Billing, usage, and cost reconciliation](https://api.tu-zi.com/en/docs/use-cases/billing-usage): Use the marketplace and current group for price. Retain model, path, Request-ID, usage or task ID, then reconcile the final consumption log instead of inferring cost from an early balance change.

## Frequently asked questions

### Can I prefix a request with /async?

No. The retired endpoint returns 410; use the model task protocol.

### Does HTTP 200 mean completion?

Verify the terminal task status and media, not just HTTP status.

### Should I resubmit after a timeout?

Check existing tasks and request logs first to avoid duplicate charged work.

## Sources

- OpenAI API Reference: https://developers.openai.com/api/reference/overview
- Gemini API Errors: https://ai.google.dev/gemini-api/docs/api-errors
- Claude API Errors: https://platform.claude.com/docs/en/api/errors

## Documentation source

Source: https://api.tu-zi.com/en/docs/use-cases/async-tasks

Reviewed: 2026-11-02

This document is an integration reference. Provider-native APIs may differ from this site's APIs; use the corresponding API Reference and model marketplace to confirm the site URL, authentication, model ID, group and parameters. This document does not certify live success for every model or upstream service. It contains documentation and examples, without the current user's credentials or request history.

Direct answerUse the model task protocol. Generic /async is retired (410), and /get-async was removed (404). Poll the corresponding task endpoint and verify the resulting media.

Updated 2026-11-02 · Reviewed 2026-11-02

Beginner: choose the model task protocol

Copy the exact model ID and submit example from the marketplace. Poll only when the response actually returns a task ID. HTTP 200 does not prove that media generation completed.

Retired generic wrapper

/async/* is retired and returns HTTP 410 endpoint_deprecated after authentication; /get-async was removed and returns 404. Do not prefix arbitrary paths with /async or use the old nested task and Base64 result envelope. Synchronous and SSE requests keep their original protocols.

Pair submission with retrieval

Submission protocol	Retrieval endpoint	Successful / failed terminal state
Unified video or asynchronous image	`GET /v1/videos/{task_id}`	Adapter-specific; commonly completed / failed
Native FLUX flux-3-image	`GET /flux/v1/get_result?id={task_id}`	Ready / Error
Suno v2	`GET /suno/v2/fetch/{task_id}`	data.status: SUCCESS / FAILURE
Kling	`GET /kling/v1/{category}/{kind}/{task_id}`	data.status: SUCCESS / FAILURE
Midjourney	`GET /mj/task/{task_id}/fetch`	status: SUCCESS / FAILURE

Preserve the Kling category/kind and any Midjourney mode prefix used at submission. IDs, response fields and status capitalization differ by protocol. Use the owning account and appropriately authorized key.

Retrieve and download

This example only retrieves an existing FLUX task:

curl --fail-with-body "$BASE_URL/flux/v1/get_result?id=$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

Wait while Pending, download result.sample when Ready, and stop with the reported error when Error. GET /v1/videos/{task_id}/content returns media bytes on success, not JSON. Result links and retention depend on the protocol and storage configuration; save needed results promptly.

Backoff, timeouts and usage

Use bounded backoff such as 1, 2, 4 and 8 seconds, a maximum interval and an overall deadline. A timeout may occur after upstream acceptance; never blindly resubmit. Save task and request IDs and use request IDs to correlate usage logs. Precharging and settlement do not imply successful generation.

Expert: recovery and diagnostics

GET /v1/images/generations/result?request_id=... recovers stored image URLs; it is not a general task endpoint. processing_or_not_found cannot distinguish pending, missing, inaccessible or URL-less results. Do not poll indefinitely or resubmit automatically. Acceptance requires a successful terminal state and readable media; receiving a task ID alone is insufficient.

Use cases

Long-running media and batch requests
Avoid client timeouts and retrieve results reliably

API protocols

/v1/videos
/v1/videos/{task_id}
/flux/v1/get_result
/suno/v2/fetch/{task_id}

FAQ

Can I prefix a request with /async?

No. The retired endpoint returns 410; use the model task protocol.

Does HTTP 200 mean completion?

Verify the terminal task status and media, not just HTTP status.

Should I resubmit after a timeout?

Check existing tasks and request logs first to avoid duplicate charged work.