接入文档

关键信息

接口地址

https://image.tokenvalid.com/v1 复制

认证方式

Authorization: Bearer sk-...

协议

POST /images/generations · POST /images/edits

改图:局部重绘与透明背景

POST /images/edits 带参考图(multipart 或 JSON 都行)。下面两项只在模型列出支持的档位可用;该档暂无线路时请求在扣费前被拒绝。

• mask - 带透明通道的 PNG,尺寸必须与第一张参考图完全一致;透明(alpha 0)的区域是要修改的区域。只能带一张参考图;选区之外的内容可能有轻微变化;不能与 background=transparent 同用。
• background - 只接受 transparent(opaque / auto 会被拒绝)。输出为 PNG:不传 output_format 时默认 png,webp 可用,传 jpeg 会被拒绝。

价格见「模型价格」页;按 token 计费的档照常按用量计费。

交付与限制

同步

缺省方式:响应里直接带图。客户端超时请设得比下面的整请求时限更长。

异步

加下面这个请求头:受理后立即返回状态与轮询地址(RFC 7240)。 Prefer: respond-async 受理:HTTP 202,字段 id, status, created, model, size, poll_after_seconds 每 5 秒轮询 GET /v1/images/results/{id}(每分钟最多 24000 次)。状态:running · succeeded · failed 结果地址保留 3 天,之后返回 410。 没有回调,请轮询;response_format=b64_json 不能与异步同用。

整请求时限

一个请求最长可能跑 480 秒,客户端超时要比它长。

参考图下限

小于 26 字节的参考图会在扣费前被拒绝(invalid_reference)。

请求大小

请求体最大 32 MB,单张参考图最大 8 MB,最多 32 张参考图,提示词最长 200000 字符。

b64_json 整批

n 大于 1 且 response_format=b64_json 时整个响应不超过 64MB(按尺寸估算,超了在扣费前直接拒绝)。

画质与用量

quality: low · medium · high · xhigh · max · auto - 不传时按 medium

响应里的 usage 由本服务按一套统一算法自算,所有模型、所有渠道相同。发布的规则版本: image-usage/8+q=medium,u=default,p=4412c2e3

total_tokens

input_tokens + output_tokens

input_tokens

text_tokens + image_tokens

text_tokens

o200k_base · if the tokenizer fails: ceil(utf8_bytes / 4)

image_tokens

each reference image in the image field (mask is not counted) · 65 + 129 * tiles (at most 581)

output_tokens

output_tokens_details.image_tokens + output_tokens_details.reasoning_tokens

输出公式

ceil(grid * (2000000 + width * height) / 4000000)

思考

a model listed in thinking_by_model adds that fixed number of reasoning tokens per image for the billed quality (an unlisted quality uses omitted_quality); they are part of output_tokens and reported in output_tokens_details.reasoning_tokens, charged at the text-and-thinking output rate

n 大于 1

text_tokens and image_tokens are counted once for the whole request and split evenly across the n images: floor(total / n) each, the remainder goes to the first image; output_tokens (and its details) are counted per image, in full

机器可读版:GET /v1/spec 的 usage_rules。

出图主机

生成的图从这些主机上取。把它们加进你的出网白名单或 CSP。

请求示例

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"
      }'