Skip to main content
调用 POST /v1/images/generations 创建图像生成任务后，接口会立即返回一个 task_id。由于图像生成为异步执行，您需要使用本接口轮询任务状态，直到任务完成后获取生成结果。

​
接口端点

GET https://geekapis.com/v1/images/generations/{task_id}

​
路径参数

​
task_id
string
required
图像生成任务 ID，或创建任务时传入的 client_business_id。使用 client_business_id 时，查询范围限定在当前 API Key 所属用户下。

​
响应字段

​
id
string
任务唯一标识符。
​
client_business_id
string
客户侧自定义业务 ID。仅当创建任务时传入 client_business_id 时返回。
​
object
string
对象类型，固定为 generation.task。
​
model
string
本次任务所使用的图像生成模型名称。
​
status
string
任务当前状态，取值如下：
  • queued — 排队等待处理
  • in_progress — 处理中
  • completed — 成功完成
  • failed — 任务失败
​
progress
integer
任务进度百分比，范围 0–100。
​
created_at
integer
任务创建时间（Unix 时间戳）。
​
completed_at
integer
任务完成时间（Unix 时间戳），仅任务完成时返回。
​
expires_at
integer
图片 URL 过期时间（Unix 时间戳），仅任务完成时返回。图片生成结果在完成后 24 小时内有效，请及时下载保存。
​
result.data
array
任务结果数据，仅任务成功完成时返回。
​
error.code
string
错误代码，仅任务失败时返回。
​
error.message
string
错误描述信息，仅任务失败时返回。

​
轮询策略

推荐轮询参数
  • 初始等待：2 秒（任务提交后先等待再首次查询）
  • 轮询间隔：3 秒
  • 最大等待时长：120 秒
  • 典型完成时间：5–30 秒

​
Python 轮询示例

import time
import requests

def poll_image_task(task_id: str, api_key: str) -> dict:
    url = f"https://geekapis.com/v1/images/generations/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    time.sleep(2)  # 初始等待
    for _ in range(40):  # 最多轮询 120s
        resp = requests.get(url, headers=headers).json()
        if resp["status"] in ("completed", "failed"):
            return resp
        time.sleep(3)
    raise TimeoutError("任务超时")

​
任务状态说明

状态说明是否终态建议操作
queued任务排队等待处理❌等待 2–3 秒后重试查询
in_progress任务正在处理中❌等待 3–5 秒后重试查询
completed任务成功完成✅从 result.data[0].url 获取图片
failed任务处理失败✅检查 error 字段信息

​
错误码说明

状态码说明
400请求参数错误
401认证失败
402余额不足
404任务不存在
422参数验证失败
429请求频率超限
500服务器内部错误