开发者文档

切换外观

生成图片 ​

POST/images/generations
鉴权
Bearer API Key
执行方式
按所调用的完整地址执行
查看调用示例

接口说明 ​

使用官方 Images Generations JSON 合同生成图片；支持 JSON 或真实 SSE，成功终态必须提供可信 Token Usage 或经绑定批准的输出图片数事实。

请求 ​

  • 方法：POST

  • 鉴权：Authorization: Bearer ${TOKENFACTORY_API_KEY}

请求头 ​

名称必填值或类型说明
Authorization是Bearer ${TOKENFACTORY_API_KEY}Token Factory API Key
Content-Type是application/json请求体媒体类型

路径参数：无

查询参数：无

请求字段 ​

字段类型必填说明示例或约束
backgroundstring否背景模式；允许为 null。transparent 仅适用于支持透明背景的 GPT Image 模型，并须搭配 png 或 webp。可选值："transparent"、"opaque"、"auto"；可为 null
modelstring否OpenAI 官方可选且允许为 null 的图片模型 ID；省略或为 null 且只使用普通参数时，Token Factory 按官方兼容默认选择 dall-e-2；若使用 GPT Image 专用参数，平台为确定性选路选择 gpt-image-2。后者是 Token Factory 的平台默认，不是 OpenAI 对未指定模型所承诺的固定 slug。示例："YOUR_IMAGE_MODEL_ID"；可为 null
moderationstring否内容审核级别；允许为 null，仅适用于支持该参数的 GPT Image 模型。可选值："low"、"auto"；可为 null
ninteger (int32)否生成图片数量；允许为 null，取值范围 1 到 10。示例：1；最小值：1；最大值：10；可为 null
output_compressioninteger (int32)否JPEG/WebP 输出压缩级别；允许为 null，取值范围 0 到 100，仅与 output_format=jpeg/webp 组合使用。示例：100；最小值：0；最大值：100；可为 null
output_formatstring否输出图片格式；允许为 null。示例："png"；可选值："png"、"jpeg"、"webp"；可为 null
partial_imagesinteger (int32)否流式返回的中间图片数量；允许为 null，仅在 stream=true 时使用。示例：1；最小值：0；最大值：3；可为 null
promptstring是图片生成提示词；dall-e-2 最长 1000 字符、dall-e-3 最长 4000 字符，GPT Image 模型最长 32000 字符。示例："一只在月光下读书的猫"
qualitystring否输出质量；允许为 null，合法值随模型而异。示例："low"；可选值："standard"、"hd"、"low"、"medium"、"high"、"auto"；可为 null
response_formatstring否响应图片载荷格式；允许为 null。可选值："url"、"b64_json"；可为 null
sizestring否输出尺寸；允许为 null。合法值随模型而异；gpt-image-2 还支持满足边长、像素与宽高比限制的 WIDTHxHEIGHT。示例："1024x1024"；可为 null
streamboolean否是否使用 Images SSE 事件流；省略或 null 等同 false。示例：false；可为 null
stylestring否图片风格；允许为 null，仅适用于 dall-e-3。可选值："vivid"、"natural"；可为 null
userstring否用于 OpenAI 安全监测的终端用户标识；若提供必须是字符串。—

请求报文 ​

媒体类型：application/json

json
{
  "model": "YOUR_MODEL_ID",
  "output_format": "png",
  "prompt": "一只在月光下读书的猫",
  "size": "1024x1024",
  "stream": false
}

响应 ​

成功状态：200

响应头 ​

名称值或类型说明
Content-Typeapplication/json 或 text/event-stream响应媒体类型
retry-afterstring上游限流或暂时不可用时保留的重试等待秒数。
x-ratelimit-limit-input-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-limit-output-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-limit-requestsstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-limit-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-remaining-input-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-remaining-output-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-remaining-requestsstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-remaining-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-reset-input-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-reset-output-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-reset-requestsstring上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-reset-tokensstring上游返回时安全保留的 OpenAI 限额信息。
x-request-idstring本次 OpenAI 协议请求的关联 ID；上游未提供时由 Token Factory 生成。

响应字段 ​

OpenAI Images 成功终态；官方新增字段保持开放。 下表完整列出当前公开协议明确声明的字段；开放扩展只允许未声明的附加字段，不会放宽已声明字段的必填、类型或枚举约束。

字段类型必填说明示例或约束
backgroundstring否实际输出背景模式。示例："opaque"；可选值："transparent"、"opaque"；可为 null
createdinteger (int64)是创建时间 Unix 秒。示例：1787832000
dataobject[]是真实输出图片数组；成功响应至少包含一张图片。示例：[{"b64_json":"...","revised_prompt":"一只在月光下读书的猫"}]；最少：1 项
data[].b64_jsonstring否Base64 编码的图片数据；允许为 null。示例："..."；可为 null
data[].revised_promptstring否模型修订后的提示词；允许为 null。示例："一只在月光下读书的猫"；可为 null
data[].urlstring否临时图片 URL；允许为 null。可为 null
output_formatstring否实际输出图片格式。示例："png"；可选值："png"、"webp"、"jpeg"；可为 null
qualitystring否实际输出质量。示例："high"；可选值："low"、"medium"、"high"；可为 null
sizestring否实际输出尺寸。示例："1024x1024"；可选值："1024x1024"、"1024x1536"、"1536x1024"、"auto"；可为 null
usageobject否TOKEN_USAGE 绑定时必需的可信生成用量；OUTPUT_IMAGE 绑定按 data 中真实图片数计费；两类事实均缺失时失败关闭。官方字段可省略或为 null。示例：{"input_tokens":14,"input_tokens_details":{"image_tokens":0,"text_tokens":14}...；可为 null
usage.input_tokensinteger (int32)父字段存在时必填输入 Token 数。示例：14；最小值：0
usage.input_tokens_detailsobject父字段存在时必填输入 Token 分类明细。示例：
usage.input_tokens_details.image_tokensinteger (int32)父字段存在时必填图片 Token 数。示例：0；最小值：0
usage.input_tokens_details.text_tokensinteger (int32)父字段存在时必填文本 Token 数。示例：14；最小值：0
usage.output_tokensinteger (int32)父字段存在时必填输出 Token 数。示例：32；最小值：0
usage.output_tokens_detailsobject否输出 Token 分类明细；官方可省略。示例：
usage.output_tokens_details.image_tokensinteger (int32)父字段存在时必填图片 Token 数。示例：32；最小值：0
usage.output_tokens_details.text_tokensinteger (int32)父字段存在时必填文本 Token 数。示例：0；最小值：0
usage.total_tokensinteger (int32)父字段存在时必填输入与输出 Token 总数。示例：46；最小值：0

返回报文 ​

媒体类型：application/json

json
{
  "background": "opaque",
  "created": 1787832000,
  "data": [
    {
      "b64_json": "...",
      "revised_prompt": "一只在月光下读书的猫"
    }
  ],
  "output_format": "png",
  "quality": "high",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 14,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 14
    },
    "output_tokens": 32,
    "output_tokens_details": {
      "image_tokens": 32,
      "text_tokens": 0
    },
    "total_tokens": 46
  }
}

SSE 返回报文 ​

媒体类型：text/event-stream

允许事件：image_generation.partial_image、image_generation.completed、error

协议终态：image_generation.completed、error

text
event: image_generation.partial_image
data: {"type":"image_generation.partial_image","b64_json":"...","created_at":1787832000,"size":"1024x1024","quality":"high","background":"opaque","output_format":"png","partial_image_index":0}

event: image_generation.completed
data: {"type":"image_generation.completed","b64_json":"...","created_at":1787832000,"size":"1024x1024","quality":"high","background":"opaque","output_format":"png","usage":{"input_tokens":14,"input_tokens_details":{"text_tokens":14,"image_tokens":0},"output_tokens":32,"total_tokens":46}}

只有上方列出的协议终态才表示流正常结束；连接中断不代表请求未执行。若已经收到部分内容，不要无条件重放同一请求。

错误 ​

适用完整地址状态错误码常见触发重试建议动作结果风险
https://api.tokenfactory.cn/v1/images/generations401invalid_api_keyAuthorization 缺失、Bearer 格式错误、Key 不可用或账户未实名否检查 Bearer API Key、Key 状态与实名状态无
https://api.tokenfactory.cn/v1/images/generations400model_not_found模型存在，但不具备当前端点要求的能力否改用支持当前端点能力的模型，或改为调用该模型支持的端点无
https://api.tokenfactory.cn/v1/images/generations404model_not_found模型不存在、未上架或当前入口不可用否调用模型列表并改用当前入口可用模型无
https://api.tokenfactory.cn/v1/images/generations404MODEL_ROUTING_PROTOCOL_UNSUPPORTED模型未开放当前 API 接口对应协议否改用该模型已开放的协议或其他模型无
https://api.tokenfactory.cn/v1/images/generations503MODEL_ROUTING_NOT_CONFIGURED模型的协议路由尚未配置视情况稍后重试；持续出现时联系平台确认路由配置无
https://api.tokenfactory.cn/v1/images/generations503MODEL_ROUTING_POLICY_INVALID模型协议路由策略状态异常视情况稍后重试；持续出现时联系平台检查路由策略无
https://api.tokenfactory.cn/v1/images/generations503MODEL_ROUTING_NO_HEALTHY_ROUTE模型当前没有健康供应路线是，退避后指数退避后重试或临时改用其他模型无
https://api.tokenfactory.cn/v1/images/generations429insufficient_balance账户可用余额不足否充值后重新发起请求无
https://api.tokenfactory.cn/v1/images/generations429balance_daily_limit_exceeded账户当天余额消费已达到自助上限否调整每日上限或等待次日恢复无
https://api.tokenfactory.cn/v1/images/generations413request_too_large请求体超过平台接收上限否缩小请求体后重试无
https://api.tokenfactory.cn/v1/images/generations400invalid_request_error请求参数或请求体缺字段、格式错误或不受支持否修正请求后重试无
https://api.tokenfactory.cn/v1/images/generations502upstream_error供应商连接失败或返回异常响应视情况确认未收到有效结果后再决定是否重试中到高
https://api.tokenfactory.cn/v1/images/generations504upstream_timeout供应商在平台超时时间内未完成响应视情况先确认是否已有部分输出，再决定是否重试中到高
https://api.tokenfactory.cn/v1/images/generations500internal_error平台内部出现未预期错误视情况确认未收到有效结果并记录请求时间后再决定是否重试中到高
https://api.tokenfactory.cn/v1/images/generations405method_not_allowed请求方法不是该公开地址允许的方法否改用文档列出的 HTTP 方法无
https://api.tokenfactory.cn/v1/images/generations415unsupported_media_typeContent-Type 与该公开地址要求的媒体类型不一致否按文档发送正确 Content-Type无
https://api.tokenfactory.cn/v1/images/generations403permission_denied当前 API Key 或上游账户无权执行该请求否检查权限、模型可见性与供应商授权无
https://api.tokenfactory.cn/v1/images/generations409conflict_error请求与上游资源当前状态冲突视情况读取最新状态后修正请求或稍后重试中到高
https://api.tokenfactory.cn/v1/images/generations422unprocessable_entity请求结构正确但上游无法处理其中的语义否按错误信息修正参数或输入内容无

错误返回报文 ​

适用完整地址 ​

https://api.tokenfactory.cn/v1/images/generations

HTTP 400；Content-Type: application/json；响应头：retry-after: string、x-ratelimit-limit-input-tokens: string、x-ratelimit-limit-output-tokens: string、x-ratelimit-limit-requests: string、x-ratelimit-limit-tokens: string、x-ratelimit-remaining-input-tokens: string、x-ratelimit-remaining-output-tokens: string、x-ratelimit-remaining-requests: string、x-ratelimit-remaining-tokens: string、x-ratelimit-reset-input-tokens: string、x-ratelimit-reset-output-tokens: string、x-ratelimit-reset-requests: string、x-ratelimit-reset-tokens: string、x-request-id: string

json
{
  "error": {
    "code": "model_not_found",
    "message": "模型存在，但不具备当前端点要求的能力",
    "param": null,
    "type": "invalid_request_error"
  }
}

适用完整地址：https://api.tokenfactory.cn/v1/images/generations

供应商非 2xx 响应会归一化为当前公开协议的错误信封，并只保留安全响应头；502、504 或连接中断时，调用结果可能未知。

限制与计费 ​

适用完整地址限制或计费说明
https://api.tokenfactory.cn/v1/images/generations请求成功后按通用余额计费；余额不足时调用失败。
受全局请求体上限约束。
模型上下文与输出限制依当前模型和上游事实而定。
仅支持 Images Generations JSON 操作；支持协议声明的返回格式与真实流式事件。
不支持 Images Variations、私有异步任务生命周期或视频生成。
余额计费调用不会自动改用 Coding Plan 权益。

调用示例 ​

cURL · https://api.tokenfactory.cn/v1/images/generations ​

sh
curl --request POST "https://api.tokenfactory.cn/v1/images/generations" --silent --show-error --fail-with-body --max-time 60 --header "Authorization: Bearer ${TOKENFACTORY_API_KEY}" --header "Content-Type: application/json" --data "{\"model\":\"${TOKENFACTORY_MODEL_ID}\",\"prompt\":\"一只在月光下读书的猫\",\"stream\":false}"

相关说明 ​

请求与响应按当前 OpenAI 兼容能力开放；供应商扩展字段可能随所选模型变化。

Token Factory · 国产合规 AI Gateway

无锡伟瑞达科技有限公司 · 苏ICP备2025202631号-3 · 苏公网安备32021302003207号