查询图片任务 - APIPod Docs

查询生成任务

curl --request GET \
  --url https://api.apipod.ai/v1/images/status/{task_id} \
  --header 'Authorization: Bearer <token>'

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))

}

const 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
    }
  }
}

GET

https://api.apipod.ai

images

status

{task_id}

查询生成任务

curl --request GET \
  --url https://api.apipod.ai/v1/images/status/{task_id} \
  --header 'Authorization: Bearer <token>'

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))

}

const 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
    }
  }
}

创建图片任务后，使用响应中的 task_id 调用本接口。任务完成前可以按合理间隔轮询；生产环境优先在创建请求中设置 callback_url。

任务状态

`status`	含义	建议动作
`pending`	任务正在排队。	继续等待或轮询。
`processing`	提供商正在生成。	继续等待或轮询。
`completed`	任务完成，结果位于 `data.result`。	下载并持久化结果。
`failed`	任务失败。	检查错误字段和请求日志。
`cancelled`	任务已取消。	停止轮询。

用量与费用

status 为 completed 时，响应会包含 usage 对象，记录该任务的最终扣费金额：

{
  "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.cost 是完成后多退少补结算后的最终金额（美元），与控制台显示的费用一致。
token 字段仅在上游提供商上报 token 用量时出现。
任务处于 pending、processing 或 failed 时不返回 usage。

图片元数据（图层拆分）

图层拆分模型（seedream-5.0-pro-layer、seedream-5.0-flash-layer）会返回一张底图和最多 16 个透明 PNG 图层。任务完成后，除 result 外还会返回 images 数组，携带每张图片的元数据。images 与 result 顺序一致，底图（z_index: 0）始终在第一位。

{
  "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": "底部说明文字",
      "description": "提取底部白色说明文字，不包含其他背景元素"
    }
  ],
  "usage": { "completion_tokens": 74620, "total_tokens": 74620, "cost": 0.035 }
}

字段	类型	说明
`images[].url`	string	与 `result` 中同一位置的 URL 相同。
`images[].z_index`	integer	图层叠放顺序。`0` 为底图，数值越大越靠上。
`images[].bounding_box.absolute`	integer[4]	图层在底图上的像素坐标 `[x1, y1, x2, y2]`。
`images[].bounding_box.normalized`	integer[4]	同一位置的 0–1000 归一化坐标。
`images[].name`	string	模型给出的图层名称。
`images[].description`	string	图层内容描述。

result 始终是 URL 字符串数组，现有客户端无需任何改动。
只有返回逐图元数据的模型才会出现 images，其它模型不会包含该字段。
元数据字段均为可选；上游未返回某个字段时会直接省略，而不是返回 null。

授权

Authorization

string

header

必填

在 Authorization 请求头中使用 Bearer APIPod_API_KEY。

路径参数

task_id

string

必填

创建接口返回的 APIPod 异步任务 ID。

响应

200 - application/json

任务状态

code

integer

必填

HTTP 状态码。

message

string

必填

响应消息。

Allowed value: "success"

data

object

必填

响应数据。

Show child attributes

​任务状态

​用量与费用

​图片元数据（图层拆分）

授权

路径参数

响应

任务状态

用量与费用

图片元数据（图层拆分）