接入文档
把任意 OpenAI 协议兼容的客户端指到下面的地址,用访问令牌鉴权。
关键信息
- 接口地址
-
https://image.tokenvalid.com/v1 - 认证方式
Authorization: Bearer sk-...- 协议
-
POST /images/generations
模型与规格
每个模型接受什么。档位决定出图多大、以及这一张多少钱;每一档的合法尺寸见下面那张表。
| 模型 | 档位 | 缺省尺寸 | 参考图上限 |
|---|---|---|---|
gemini-3.1-flash-image
亦作 nano-banana-2
|
1k 2k 4k | 1024x1024 | 14 |
gemini-3-pro-image
亦作 nano-banana-pro
|
1k 2k 4k | 1024x1024 | 14 |
gpt-image-2
|
1k 2k 4k | 1024x1024 | 16 |
gpt-image-2.5-flare
|
1k 2k 4k | 1024x1024 | 16 |
gpt-image-2.5-sunburst
|
1k 2k 4k | 1024x1024 | 16 |
image-test
|
不分档 | — | — |
seedream-5.0-open
|
2k 4k | 2048x2048 | — |
seedream-5-0-pro-open
|
1k 2k 4k | 1024x1024 | — |
size 有三种写法:精确像素串(1024x1024)、画幅串(16:9,落最便宜的那一档)、或 auto。
尺寸
size 能写的全部像素串。行是画幅,列是档位。
| 画幅 | 1k | 2k | 4k |
|---|---|---|---|
1:1 |
1024x1024 | 2048x2048 | 2880x2880 |
4:3 |
1152x864 | 2048x1536 | 3200x2400 |
3:4 |
864x1152 | 1536x2048 | 2400x3200 |
3:2 |
1536x1024 | 2304x1536 | 3456x2304 |
2:3 |
1024x1536 | 1536x2304 | 2304x3456 |
16:9 |
1344x768 | 2048x1152 | 3840x2160 |
9:16 |
768x1344 | 1152x2048 | 2160x3840 |
21:9 |
1536x656 | 2304x992 | 3840x1648 |
5:4 |
1120x896 | 1920x1536 | 3200x2560 |
4:5 |
896x1120 | 1536x1920 | 2560x3200 |
不传 size 时用的画幅: 1k = 1:1 · 2k = 1:1 · 4k = 16:9
参数
这个接口认识的全部参数,以及它们各自会被怎么处理。标为「拒绝」的会让请求失败,并返回下面那个错误码。
| 参数 | 处置 | 取值 |
|---|---|---|
model |
生效 | gemini-3.1-flash-image · gemini-3-pro-image · gpt-image-2 · gpt-image-2.5-flare · gpt-image-2.5-sunburst · image-test · seedream-5.0-open · seedream-5-0-pro-open |
prompt |
生效 | <必填,非空字符串> |
size |
生效 | 41 个取值 —— 见上表 |
response_format |
生效 | url · b64_json |
quality |
生效 | low · medium · high · auto |
output_format |
生效 | png · jpeg · webp |
stream |
收下但不生效 | true · false |
partial_images |
收下但不生效 | 0 · 1 · 2 · 3 |
user |
收下但不生效 | <任意字符串> |
n |
拒绝 |
n_not_supported
|
mask |
拒绝 |
mask_not_supported
|
output_compression |
拒绝 |
output_compression_not_supported
|
background |
拒绝 |
background_not_supported
|
moderation |
拒绝 |
moderation_not_supported
|
style |
拒绝 |
style_not_supported
|
错误码
响应体里的 error.code、它是什么意思,以及换一条通路重试有没有意义。
| 错误码 | 含义 | 换条通路重试 |
|---|---|---|
abandoned |
the request was interrupted before it finished; it was refunded | 没用 |
async_b64_unsupported |
asynchronous submission cannot be combined with response_format=b64_json | 没用 |
async_storage_unavailable |
storage is temporarily unavailable; this request was fully refunded | 没用 |
async_unavailable |
this replica does not accept asynchronous submissions | 没用 |
background_not_supported |
background is not supported | 没用 |
body_too_large |
the request body exceeds the size limit | 没用 |
content_policy_violation |
rejected by content moderation; revise the prompt or reference images instead of retrying | 没用 |
draining |
this node is restarting; retry shortly | 没用 |
duplicate_request |
a request with this Idempotency-Key already exists | 没用 |
edits_not_supported |
this model does not support image-to-image | 没用 |
generation_failed |
image generation failed; the request was refunded | 没用 |
image_conversion_failed |
image format or size conversion failed | 没用 |
image_pixels_too_large |
the upstream returned an image larger than our processing limit | 没用 |
image_too_large |
the upstream returned an image larger than our storage limit | 没用 |
insufficient_quota |
insufficient API balance for this request | 没用 |
internal_error |
internal error | 有用 |
invalid_api_key |
the API key is invalid or disabled | 没用 |
invalid_json |
the request body is not valid JSON | 没用 |
invalid_multipart |
the multipart body could not be parsed | 没用 |
invalid_output_format |
output_format must be one of png, jpeg, webp | 没用 |
invalid_reference |
a reference image is not a valid image file | 没用 |
invalid_response_format |
response_format must be one of: url, b64_json | 没用 |
mask_not_supported |
mask is not supported yet; the whole image is regenerated | 没用 |
missing_api_key |
Authorization: Bearer <key> is required | 没用 |
model_not_allowed |
this API key is not allowed to use the requested model | 没用 |
model_required |
model is required | 没用 |
model_spec_missing |
unknown model; check the name against GET /v1/models | 没用 |
moderation_not_supported |
moderation cannot be configured per request | 没用 |
n_not_supported |
n>1 is not supported yet; request one image per call | 没用 |
no_channel_available |
no route is currently available for this model | 没用 |
no_image_returned |
the upstream answered without an image | 有用 |
not_found |
no request with this id | 没用 |
output_compression_not_supported |
output_compression is not supported; conversion uses a fixed quality | 没用 |
poll_rate_limit_exceeded |
polling too frequently | 没用 |
prompt_required |
prompt is required | 没用 |
rate_limit_exceeded |
too many requests; slow down | 没用 |
ratio_not_supported |
this aspect ratio is not available on the current route | 没用 |
reference_image_required |
the prompt asks to edit or reference an image but the request carries none; send the image via /v1/images/edits | 没用 |
reference_too_large |
a reference image exceeds the size limit | 没用 |
request_not_supported |
this request is not supported for the model; the error names the offending part | 没用 |
server_busy |
this node has too many requests in flight; retry shortly | 没用 |
size_not_allowed |
size is not a valid value (the error names the closest valid one) | 没用 |
size_not_supported |
this size is not available on the current route | 没用 |
style_not_supported |
style is not supported | 没用 |
tier_not_available |
this model does not offer the requested tier (the error lists the available tiers) | 没用 |
too_many_concurrent_requests |
too many requests in flight at once | 没用 |
too_many_reference_images |
too many reference images | 没用 |
upstream_account_problem |
the upstream could not process this request | 有用 |
upstream_busy |
the upstream could not finish this request in time | 有用 |
upstream_error |
the upstream failed to process this request | 有用 |
upstream_rate_limited |
the current routes are rate limited; back off and retry | 有用 |
upstream_rejected |
the upstream rejected this request | 有用 |
upstream_send_failed |
the connection to the upstream failed | 没用 |
upstream_timeout |
the upstream did not answer in time | 有用 |
upstream_undersized |
the upstream returned an image far smaller than requested | 有用 |
upstream_unreachable |
the upstream could not be reached | 有用 |
出图主机
生成的图从这些主机上取。把它们加进你的出网白名单或 CSP。
https://image1.tokenvalid.com
https://image2.tokenvalid.com
请求示例
curl https://image.tokenvalid.com/v1/images/generations \
-H "Authorization: Bearer $XTOKEN_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "a paper crane on a desk",
"size": "1024x1024"
}'