Skip to main content
GET
Query Task Status

Task Status and Delay Notices

Use only status to determine whether a task has ended. Neither progress=100 nor a non-null error means the task has ended. For supported asynchronous video, image, audio, and document tasks that have been submitted and remain unfinished after more than 30 minutes of processing, the existing error field returns code=task_delayed and type=task_status. The notice states the actual processing deadline for that task. Deadlines can vary; do not treat the 2-hour deadline in the example as a fixed value. For example, when the processing deadline is 2 hours and the reserved credits have not yet been refunded:
If the processing deadline has passed but the system has not yet ended the task, status remains processing and the notice indicates that the task is waiting to be marked as failed due to timeout. This does not mean a refund has already occurred; keep polling. For these Gateway video, image, audio, and document tasks, refund notices describe only that task’s reserved credits: no refund is needed if no credits were reserved, and a completed refund is reported only after it is confirmed, without promising another refund. For failed tasks, refund information is appended to error.message while the original public error.code and error.type are preserved. usage.credits_reserved records the original reserved amount and can remain positive after a refund; it does not indicate that a refund is still pending. A delay notice itself does not change the task status or issue a refund. You can still use sync_upstream=true to proactively refresh the task status once, as described in the API reference. See Error Codes Reference for code meanings.

results Field Format

After a task completes (status=completed), results is an array whose structure varies by model. Before parsing results, check the model field in the response to determine the structure type.

Common Format (Most Models)

Grouped by task output type (type):
The url values in the common formats above are valid for 24 hours. Please save them promptly. If a special format uses a different retention period, refer to that model’s documentation.

Special Formats (By model)

The results[i] structure for the following models does not follow the common format above. Callers must handle them separately based on model.

GPT Image 2.5 Generation Metadata

image_metadata stores fields specific to the image, such as generation_id, model, and size. response_metadata stores fields shared by one generation response, such as created, background, output_format, quality, and size. In multi-image results, this information comes from the same request and must not be treated as independent usage data for each image. Other generation metadata fields are also preserved, so callers should allow additional fields. The following is a structure example. files.example.com represents a file address returned by the system, not a tested downloadable link:
New tasks for the two 2.5 models are billed by total text input, total image input, image output, and text output, without a cache discount. See the model documentation for specific rates. When cached usage is not reported, it remains unknown and does not prevent billing by the four total categories; these statistics are not included in image results. The two 2.5 models must store images in this system before successful results are published. Duplicate image addresses in metadata are also replaced with this system’s addresses. Image results contain neither the generation service’s original image address nor usage. Retention for these images is determined by this system’s file-storage policy; download and save them promptly after the task completes.

Profile Creation (No Media URL Returned)

Voice Cloning

Speech Transcription (No Media URL Returned)

Video with Seed Value

The seed field is always present: it is the corresponding integer when the generation process returns a seed; if no seed is returned for this generation, it is null. Handle it as “field always present, value may be null”.

Seedance 2.5 (HongniaoAI)

Fields such as result.output.outputUrls, result.outputs, result.videoUrl, result.videoUrls, result.video_url, and result.resultUrls come from the upstream task response. The adapter preserves these fields inside results[i].result and also exposes available fields on results[i]. HongniaoAI task responses may return seconds as a string even when the submitted request uses an integer; parse it according to its actual JSON type. Fields such as expires_at and thumbnail_url, as well as future upstream fields, may be absent. Parsers should accept missing and additional fields.

Reference Video Fast Variant Degradation Notice (degraded_reason)

PBR Material (Single Task Returns Multiple Semantically Labeled Results)

Music Generation with Lyrics Text

Parsing Recommendations

  • Read model first, then parse results: Different models under the same type may have completely different structures
  • Mind the expiration for URL results: The url values in common formats are valid for 24 hours; GPT Image 2.5 follows the file-storage policy described above. Your application should download and store them immediately upon receipt
  • Profile-type tasks return voice_id / character_id / profile_id as long-lived resource identifiers that can be used directly in subsequent task parameters

Authorizations

Authorization
string
header
required

All endpoints require Bearer Token authentication

Add the following to your request headers:

Authorization: Bearer YOUR_API_KEY

Path Parameters

task_id
string
required

Task ID, returned by the task submission endpoint

Example:

"task-unified-1757165031-uyujaw3d"

Query Parameters

sync_upstream
boolean
default:false

Whether to proactively refresh the task status before returning. Only takes effect for tasks that are still in progress and have an associated remote task; otherwise, the current task status is returned directly.

Example:

true

Response

Query successful

id
string

Task ID

Example:

"task-unified-1757165031-uyujaw3d"

object
enum<string>

Specific task type

Available options:
video.generation.task,
image.generation.task,
audio.generation.task,
llm.generation.task
Example:

"video.generation.task"

type
enum<string>

Task output type

Available options:
video,
image,
audio,
llm
Example:

"video"

model
string

Actual model name used

Example:

"lipsync-2"

status
enum<string>

Task status. Use only this field to determine whether the task has ended; neither progress=100 nor a non-null error can replace this check.

Options:

Available options:
pending,
processing,
completed,
failed
Example:

"pending"

progress
integer

Task progress percentage

Required range: 0 <= x <= 100
Example:

0

created
integer

Task creation timestamp (Unix seconds)

Example:

1757165031

results
object[] | null

Task result list; only populated when status=completed.

Structure varies by task output type (type):

General notes:

  • Result URLs are valid for 24 hours; please save them promptly
  • type=llm results are conversation responses and do not produce URLs
  • Some tasks produce non-media artifacts (voice profile / character profile creation, etc.); results contains id-type fields instead of url

Image result (type=image). Most image models only return url; some models (Patina family) also include content_type; PHOTA profile creation tasks return {result_type, profile_id} (non-image artifact)

error
object | null

Failure information or a delay notice for a task still processing; may be null. When status=failed, contains a failure description safe to show to clients. Supported submitted asynchronous tasks that remain processing after more than 30 minutes return code=task_delayed and type=task_status, with the actual processing deadline for that task. If the deadline has passed but the task has not ended, the notice indicates that it is waiting for the system to process it; this does not mean it has failed or been refunded. Delay notices state that no refund is needed when no credits were reserved, and report a completed refund only after it is confirmed, without promising another refund. For failed Gateway video, image, audio, and document tasks, refund information is appended only to message while the original public code/type are preserved. Successful tasks return null. Always use status to determine whether the task has ended.

usage
object | null

Billing information