curl https://api.freemodel.app/v1/tasks/task_01HXYZ \
-H "Authorization: Bearer $FREEMODEL_API_KEY"
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.freemodel.app/v1/tasks/task_01HXYZ",
headers={"Authorization": f"Bearer {os.environ['FREEMODEL_API_KEY']}"},
)
with urlopen(request) as response:
task = json.load(response)
print(task["status"], task.get("result"))
const response = await fetch(
"https://api.freemodel.app/v1/tasks/task_01HXYZ",
{ headers: { Authorization: `Bearer ${process.env.FREEMODEL_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 and other asynchronous jobs.
GET
/
v1
/
tasks
/
{id}
curl https://api.freemodel.app/v1/tasks/task_01HXYZ \
-H "Authorization: Bearer $FREEMODEL_API_KEY"
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.freemodel.app/v1/tasks/task_01HXYZ",
headers={"Authorization": f"Bearer {os.environ['FREEMODEL_API_KEY']}"},
)
with urlopen(request) as response:
task = json.load(response)
print(task["status"], task.get("result"))
const response = await fetch(
"https://api.freemodel.app/v1/tasks/task_01HXYZ",
{ headers: { Authorization: `Bearer ${process.env.FREEMODEL_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 uses 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 or video.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.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}.
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.freemodel.app/v1/tasks/task_01HXYZ \
-H "Authorization: Bearer $FREEMODEL_API_KEY"
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.freemodel.app/v1/tasks/task_01HXYZ",
headers={"Authorization": f"Bearer {os.environ['FREEMODEL_API_KEY']}"},
)
with urlopen(request) as response:
task = json.load(response)
print(task["status"], task.get("result"))
const response = await fetch(
"https://api.freemodel.app/v1/tasks/task_01HXYZ",
{ headers: { Authorization: `Bearer ${process.env.FREEMODEL_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
}