curl https://api.snapgen.org/v1/tasks/task_01HXYZ \
-H "Authorization: Bearer $SNAPGEN_API_KEY"
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.snapgen.org/v1/tasks/task_01HXYZ",
headers={"Authorization": f"Bearer {os.environ['SNAPGEN_API_KEY']}"},
)
with urlopen(request) as response:
task = json.load(response)
print(task["status"], task.get("result"))
const response = await fetch(
"https://api.snapgen.org/v1/tasks/task_01HXYZ",
{ headers: { Authorization: `Bearer ${process.env.SNAPGEN_API_KEY}` } },
);
const task = await response.json();
console.log(task.status, task.result);
{
"id": "task_01HXYZ",
"object": "task",
"status": "succeeded",
"model": "gpt-image-2.5-ext",
"modality": "image",
"progress": 100,
"result": {
"urls": ["https://cdn.example.com/image.png"]
},
"error": null,
"reserved_microusd": "8500",
"charged_microusd": "8500",
"created_at": 1784324432,
"completed_at": 1784324660
}
{
"id": "task_01HXYZ",
"object": "task",
"status": "failed",
"model": "gpt-image-2.5-ext",
"modality": "image",
"progress": null,
"result": null,
"error": { "code": "provider_task_failed", "message": "Provider task failed" },
"reserved_microusd": "8500",
"charged_microusd": "0",
"created_at": 1784324432,
"completed_at": 1784324655
}
{
"id": "task_01HXYZ",
"object": "task",
"status": "processing",
"model": "gpt-image-2.5-ext",
"modality": "image",
"progress": 30,
"result": null,
"error": null,
"reserved_microusd": "8500",
"charged_microusd": null,
"created_at": 1784324432,
"completed_at": null
}
Task Management
Get task status
Read a gateway task by ID for image Ext, music, dubbing, and other asynchronous jobs.
GET
/
v1
/
tasks
/
{id}
curl https://api.snapgen.org/v1/tasks/task_01HXYZ \
-H "Authorization: Bearer $SNAPGEN_API_KEY"
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.snapgen.org/v1/tasks/task_01HXYZ",
headers={"Authorization": f"Bearer {os.environ['SNAPGEN_API_KEY']}"},
)
with urlopen(request) as response:
task = json.load(response)
print(task["status"], task.get("result"))
const response = await fetch(
"https://api.snapgen.org/v1/tasks/task_01HXYZ",
{ headers: { Authorization: `Bearer ${process.env.SNAPGEN_API_KEY}` } },
);
const task = await response.json();
console.log(task.status, task.result);
{
"id": "task_01HXYZ",
"object": "task",
"status": "succeeded",
"model": "gpt-image-2.5-ext",
"modality": "image",
"progress": 100,
"result": {
"urls": ["https://cdn.example.com/image.png"]
},
"error": null,
"reserved_microusd": "8500",
"charged_microusd": "8500",
"created_at": 1784324432,
"completed_at": 1784324660
}
{
"id": "task_01HXYZ",
"object": "task",
"status": "failed",
"model": "gpt-image-2.5-ext",
"modality": "image",
"progress": null,
"result": null,
"error": { "code": "provider_task_failed", "message": "Provider task failed" },
"reserved_microusd": "8500",
"charged_microusd": "0",
"created_at": 1784324432,
"completed_at": 1784324655
}
{
"id": "task_01HXYZ",
"object": "task",
"status": "processing",
"model": "gpt-image-2.5-ext",
"modality": "image",
"progress": 30,
"result": null,
"error": null,
"reserved_microusd": "8500",
"charged_microusd": null,
"created_at": 1784324432,
"completed_at": null
}
Query a gateway task with the ID returned from an asynchronous submission. Image Ext, music generation, and dubbing tasks use this endpoint. Video clients that received
A
object: "video" from POST /v1/videos should follow the Video API workflow; GET /v1/tasks/{id} still returns the gateway task object below.
The response is the gateway’s own task document. It is not an upstream provider task envelope.
string
required
The task ID from
x-gateway-task-id, Location, or a 202 body, for example
task_01HXYZ.Response fields
string
The gateway task ID.
string
Always
task.string
queued, processing, succeeded, failed, expired, or reconciliation_required.string
The model that ran the task.
string
image, video, or audio.number | null
Progress from 0 to 100 when the gateway reports it.
object | null
Present when
status is succeeded. For Ext, result.urls is an array of public image URLs. Music tasks add fields such as tracks and lyrics; see Music generation tasks. Dubbing tasks return content_path and an empty urls list.object | null
error.code and error.message when the task failed.string
Wallet reservation in microUSD at submit time.
string | null
Settled charge in microUSD.
null until the task settles.number
Unix timestamp (seconds) of submission.
number | null
Unix timestamp (seconds) of completion.
null while running.202 from POST /v1/images/generations uses this same object. Prefer: respond-async also sets preference-applied: respond-async and Location: /v1/tasks/{id}. POST /v1/music/generations and POST /v1/audio/dubbing always return this object with HTTP 202 and a Location: /v1/tasks/{id} header.
Download task output
GET /v1/tasks/{id}/content returns the output of a succeeded task with the same API key. For a dubbing task it streams the dubbed file and supports Range requests. For tasks that deliver URLs, such as music tasks, it redirects to the first URL in result.urls. Before the task succeeds, it returns HTTP 409 with task_not_ready.
Poll every 10 to 20 seconds until succeeded or failed. Do not resubmit a reconciliation_required task to another route. Optional webhooks notify on terminal states; this GET remains the source of truth.
curl https://api.snapgen.org/v1/tasks/task_01HXYZ \
-H "Authorization: Bearer $SNAPGEN_API_KEY"
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.snapgen.org/v1/tasks/task_01HXYZ",
headers={"Authorization": f"Bearer {os.environ['SNAPGEN_API_KEY']}"},
)
with urlopen(request) as response:
task = json.load(response)
print(task["status"], task.get("result"))
const response = await fetch(
"https://api.snapgen.org/v1/tasks/task_01HXYZ",
{ headers: { Authorization: `Bearer ${process.env.SNAPGEN_API_KEY}` } },
);
const task = await response.json();
console.log(task.status, task.result);
{
"id": "task_01HXYZ",
"object": "task",
"status": "succeeded",
"model": "gpt-image-2.5-ext",
"modality": "image",
"progress": 100,
"result": {
"urls": ["https://cdn.example.com/image.png"]
},
"error": null,
"reserved_microusd": "8500",
"charged_microusd": "8500",
"created_at": 1784324432,
"completed_at": 1784324660
}
{
"id": "task_01HXYZ",
"object": "task",
"status": "failed",
"model": "gpt-image-2.5-ext",
"modality": "image",
"progress": null,
"result": null,
"error": { "code": "provider_task_failed", "message": "Provider task failed" },
"reserved_microusd": "8500",
"charged_microusd": "0",
"created_at": 1784324432,
"completed_at": 1784324655
}
{
"id": "task_01HXYZ",
"object": "task",
"status": "processing",
"model": "gpt-image-2.5-ext",
"modality": "image",
"progress": 30,
"result": null,
"error": null,
"reserved_microusd": "8500",
"charged_microusd": null,
"created_at": 1784324432,
"completed_at": null
}