GRGlobalRouter Docs
Console

Images / POST

Create image task

create异步图片生成任务，并通过 polling_url query完成状态。

Endpoints

Mobile only shows the endpoint list. View parameter details and examples on desktop.

MethodEndpointDescription
POST/api/v1/imagesOpenRouter 风格create图片，可returns URL 或 b64_json。
POST/api/v1/image-taskscreate异步图片生成任务，并通过 polling_url query完成状态。
GET/api/v1/image-tasks/{image_task_id}query异步图片任务状态、产物和计费摘要。
POST/api/v1/image-tasks

适合即梦图片生成等长耗时任务。create请求只落库入本地队列并returns虚拟 task id；后台 worker 负责 submit/poll、落结果和计费 finalize。需要立即returns图片时使用 Create images。

Back to Images endpoint list

Request parameters

FieldTypeRequiredDescription
modelstringYesGlobalRouter 图片models ID，例如 jimeng_t2i_v31。
promptstringYesImage generation prompt.
input_referencesobject[]No参考图列表，每项包含 type=image_url 与 image_url.url。
nintegerNo生成图片数量，默认 1，最大值按models能力配置。
sizestringNo图片尺寸，WxH 格式，例如 2048x1152。不要与 resolution 或 aspect_ratio 同时传；GHYZ 异步图生图支持的尺寸见下方注意事项。
aspect_ratiostringNo画幅比例，支持 1:1、2:3、3:2、3:4、4:3、4:5、5:4、16:9、9:16。
resolutionstringNo分辨率档位 1K、2K、4K，需与 aspect_ratio 一起传；支持的尺寸见下方注意事项。
qualitystringNo质量档位，例如 auto、low、medium、high。
seedintegerNoRandom seed.
output_formatstringNoOutput format, such as png, jpeg, or webp.
response_formatstringNoreturns url 或 b64_json。
provider.provider_idstringNo指定 provider，例如 doubao_gr。create时选定后，submit/poll 都固定使用该 provider。
provider.optionsobjectNoProvider-keyed options，不允许包含 AK/SK。
webhook_urlstringNoHTTPS webhook URL。完成或失败通知通过后台 outbox 投递。
metadataobjectNo客户端元数据。req_key 不需要传，服务端由 model + provider_model_id 推导。

Response fields

FieldTypeRequiredDescription
idstringYesGR 虚拟图片任务 ID，例如 imgtask_xxx。
objectstringYes固定为 image.task。
statusstringYesqueued、submitting、submitted、in_progress、completed、failed、expired 等。
modelstringYes请求models。
providerstringYescreate时固定的 provider。
polling_urlstringYesquery任务状态的相对 URL。
dataobject[]Nocompleted 后returns图片明细。
data[].urlstringNoImage URL.
data[].b64_jsonstringNoBase64 image content.
usageobjectNo后台 poll worker 完成计费后的用量摘要。
errorobjectNo失败原因。

Errors

400ROUTER_IMAGE_TASK_PROVIDER_RELATION_NOT_FOUND

models没有可用 provider 绑定或 provider_model_id/req_key 缺失。

429ROUTER_IMAGE_TASK_QUEUE_FULL

租户或 API key 的异步图片队列已满。

503ROUTER_IMAGE_TASK_QUEUE_DISABLED

异步图片任务队列已关闭。

Notes

  • req_key 由服务端根据 model 和 provider_model_id 推导，普通客户端不需要传。
  • 已create任务的 provider 固定在 image_tasks.provider_id，poll 阶段不会按 model 重新路由。
  • 以下尺寸适用于 GHYZ 异步图生图（model=gpt-image-2）；其它models按其能力配置。
  • 1K（9 个）：1:1 1024x1024、2:3 1024x1536、3:2 1536x1024、3:4 1152x1536、4:3 1536x1152、4:5 1216x1520、5:4 1520x1216、16:9 1536x864、9:16 864x1536。
  • 2K（9 个）：1:1 2048x2048、2:3 1344x2016、3:2 2016x1344、3:4 1536x2048、4:3 2048x1536、4:5 1600x2000、5:4 2000x1600、16:9 2048x1152、9:16 1152x2048。
  • 4K（9 个）：1:1 2880x2880、2:3 2336x3504、3:2 3504x2336、3:4 2448x3264、4:3 3264x2448、4:5 2560x3200、5:4 3200x2560、16:9 3840x2160、9:16 2160x3840。
  • 也可以只传 resolution 与 aspect_ratio：resolution 取 1K、2K、4K，aspect_ratio 取 1:1、2:3、3:2、3:4、4:3、4:5、5:4、16:9、9:16，服务端会换算为对应尺寸（例如 resolution=2K + aspect_ratio=16:9 等于 2048x1152）；size 取 auto 时尺寸由上游决定。
  • 尺寸约束：宽高都必须是 16 的倍数，最长边不超过 3840，宽高比不超过 3:1，总像素在 655360 到 8294400 之间；超限请求会在提交上游时失败，任务最终状态为 failed。
  • 计费按输出像素分档：不超过 2360000 像素与超过 2360000 像素是两个档位，例如 2048x1152（2359296 像素）与 2048x2048（4194304 像素）属于不同档位。