Asynchronous Image Generation

What is Asynchronous Generation

For time-consuming image generation requests, the platform supports asynchronous generation mode: after submitting the request, a task ID is returned immediately. The client polls for the final result — no need to hold a long connection.

Async mode suits scenarios with longer generation times and avoids request timeout interruptions. It also lets you submit multiple tasks in batch.

Workflow

Async generation has three steps: submit → poll → download.

1. Submit the task

Send a POST request to https://api.tvtapi.com/v1/images/async with your API Key (Bearer auth) and request parameters:

curl -X POST https://api.tvtapi.com/v1/images/async \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"model-name","prompt":"description text"}'

The response includes a task_id — your credential for querying and downloading.

2. Poll task status

Poll the task status using task_id:

curl https://api.tvtapi.com/v1/images/async/{task_id} \
  -H "Authorization: Bearer sk-xxxxxxxx"

Task states include: queued, in_progress, succeeded, failed. Poll every few seconds until the state becomes succeeded or failed.

3. Download the image

After the task succeeds, fetch the image via:

curl -L https://api.tvtapi.com/v1/images/async/{task_id}/content \
  -H "Authorization: Bearer sk-xxxxxxxx"

This endpoint returns a 302 redirect to the image's actual storage URL. Each image has a download limit; the task expires automatically after the timeout.

Use on the Web

If you don't want to write code, use the image workbench at /en-us/user/image-studio directly. The workbench has a built-in async toggle — once enabled, it polls automatically and displays results without manual API calls.

Notes

  • Async functionality requires an admin to enable it, and the user account must have the corresponding permission
  • Tasks have a validity period; expired tasks cannot be downloaded
  • If a task stays in in_progress for too long, the system will time out and mark it as failed