Get Generation Task
curl --request GET \
--url https://api.apipod.ai/v1/images/status/{task_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.apipod.ai/v1/images/status/{task_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.apipod.ai/v1/images/status/{task_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}falseconst options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.apipod.ai/v1/images/status/{task_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"code": 200,
"message": "success",
"data": {
"task_id": "img_task_01JEXAMPLE",
"status": "completed",
"progress": 100,
"result": [
"https://cdn.example.com/generated.png"
],
"completed_at": 1786358400,
"usage": {
"completion_tokens": 123,
"total_tokens": 456,
"cost": 0.053
}
}
}Tasks
Query image task
Retrieve status, progress, results, and errors for an asynchronous image generation task by task_id.
GET
https://api.apipod.ai
/
v1
/
images
/
status
/
{task_id}
Get Generation Task
curl --request GET \
--url https://api.apipod.ai/v1/images/status/{task_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.apipod.ai/v1/images/status/{task_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.apipod.ai/v1/images/status/{task_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}falseconst options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.apipod.ai/v1/images/status/{task_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"code": 200,
"message": "success",
"data": {
"task_id": "img_task_01JEXAMPLE",
"status": "completed",
"progress": 100,
"result": [
"https://cdn.example.com/generated.png"
],
"completed_at": 1786358400,
"usage": {
"completion_tokens": 123,
"total_tokens": 456,
"cost": 0.053
}
}
}After creating a image task, call this endpoint with the returned
task_id. Poll at a reasonable interval until the task reaches a terminal state; for production workloads, prefer callback_url on the create request.
Task statuses
status | Meaning | Recommended action |
|---|---|---|
pending | The task is queued. | Wait and poll again. |
processing | The provider is generating the result. | Wait and poll again. |
completed | The task completed; outputs are in data.result. | Download and persist the outputs. |
failed | The task failed. | Inspect the error fields and request log. |
cancelled | The task was cancelled. | Stop polling. |
Usage and cost
Whenstatus is completed, the response includes a usage object with the final amount charged for the task:
{
"task_id": "img_task_01JEXAMPLE",
"status": "completed",
"result": ["https://cdn.example.com/generated.png"],
"completed_at": 1786358400,
"usage": {
"prompt_tokens": 100,
"completion_tokens": 123,
"total_tokens": 223,
"cost": 0.053
}
}
usage.costis the settled amount in USD after any post-completion adjustment; it matches the cost shown in the dashboard.- Token fields are present only when the upstream provider reports token usage.
usageis absent while the task ispendingorprocessingand onfailedtasks.
Image metadata (layer decomposition)
Layer-decomposition models (seedream-5.0-pro-layer, seedream-5.0-flash-layer) return a base image plus up to 16 transparent PNG layers. In addition to result, completed tasks include an images array with per-image metadata. images follows the same order as result, and the base image (z_index: 0) always comes first.
{
"task_id": "img_task_01JEXAMPLE",
"status": "completed",
"result": [
"https://cdn.example.com/base.png",
"https://cdn.example.com/layer_1.png"
],
"images": [
{ "url": "https://cdn.example.com/base.png", "z_index": 0 },
{
"url": "https://cdn.example.com/layer_1.png",
"z_index": 1,
"bounding_box": {
"absolute": [528, 1286, 1011, 1418],
"normalized": [344, 837, 658, 923]
},
"name": "Bottom caption text",
"description": "White caption text at the bottom, without background elements"
}
],
"usage": { "completion_tokens": 74620, "total_tokens": 74620, "cost": 0.035 }
}
| Field | Type | Description |
|---|---|---|
images[].url | string | Same URL as the item at the same position in result. |
images[].z_index | integer | Stacking order. 0 is the base image; higher values sit on top. |
images[].bounding_box.absolute | integer[4] | Layer position on the base image in pixels: [x1, y1, x2, y2]. |
images[].bounding_box.normalized | integer[4] | The same position in 0–1000 normalized coordinates. |
images[].name | string | Layer name generated by the model. |
images[].description | string | Description of the layer content. |
resultis always an array of URL strings, so existing clients keep working without changes.imagesis present only when the model returns per-image metadata; other models never include it.- Metadata fields are optional. If the upstream omits a field, it is left out rather than returned as
null.
Authorizations
Use your APIPod API key as a Bearer token in the Authorization header.
Path Parameters
APIPod asynchronous task ID returned by the create endpoint.
Was this page helpful?