开发者文档

切换外观

生成图片 ​

POST/images/generations

接口说明 ​

使用官方 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；模型支持及格式组合由供应商判断。最短：1 字符；可为 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；模型支持由供应商判断。最短：1 字符；可为 null
ninteger (int32)否生成图片数量；允许为 null，取值范围 1 到 10。示例：1；最小值：1；最大值：10；可为 null
output_compressioninteger (int32)否输出压缩级别；允许为 null，取值范围 0 到 100；支持的格式组合由供应商判断。示例：100；最小值：0；最大值：100；可为 null
output_formatstring否输出图片格式；允许为 null。示例："png"；最短：1 字符；可为 null
partial_imagesinteger (int32)否流式返回的中间图片数量；允许为 null，参数组合由供应商判断。示例：1；最小值：0；最大值：3；可为 null
promptstring是图片生成提示词；须为非空字符串，模型长度限制由供应商判断。示例："一只在月光下读书的猫"
qualitystring否输出质量；允许为 null，合法值随模型而异。示例："low"；最短：1 字符；可为 null
response_formatstring否响应图片载荷格式；允许为 null。最短：1 字符；可为 null
sizestring否输出尺寸；允许为 null，提供时须为非空字符串；模型支持范围由供应商判断。示例："1024x1024"；可为 null
streamboolean否是否使用 Images SSE 事件流；省略或 null 等同 false。示例：false；可为 null
stylestring否图片风格；允许为 null；模型支持由供应商判断。最短：1 字符；可为 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响应媒体类型
request-idstringToken Factory 独立生成的平台请求编号；Anthropic 错误体的 request_id 与其相同。
retry-afterstring可选重试等待提示：非负秒数或标准 HTTP 日期。重试前仍需确认请求可安全重复。
x-request-idstringToken Factory 独立生成的平台请求编号，与 request-id 相同。

响应字段 ​

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

字段类型必填说明示例或约束
backgroundstring否实际输出背景模式。示例："opaque"；最短：1 字符；可为 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"；最短：1 字符；可为 null
qualitystring否实际输出质量。示例："high"；最短：1 字符；可为 null
sizestring否实际输出尺寸；auto 或正整数 WIDTHxHEIGHT。示例："1024x1024"；最短：1 字符；可为 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当前模型不可用否核对模型名称与当前入口的模型列表；持续出现时联系支持无
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_AVAILABLE_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 无权执行该请求否检查 API Key 权限与当前入口的模型可见性无
https://api.tokenfactory.cn/v1/images/generations409conflict_error请求与当前资源状态冲突视情况读取最新状态后修正请求或稍后重试中到高
https://api.tokenfactory.cn/v1/images/generations422unprocessable_entity请求结构正确但当前请求无法处理否按错误信息修正参数或输入内容无
https://api.tokenfactory.cn/v1/images/generations503service_unavailable服务暂不可用，请稍后重试视情况保留平台请求编号，稍后重试或联系支持中到高
https://api.tokenfactory.cn/v1/images/generations503service_busy模型服务繁忙，请稍后重试视情况参考 Retry-After 并限制重试次数；已收到输出时先确认是否可安全重复中到高
https://api.tokenfactory.cn/v1/images/generations400context_length_exceeded输入超过模型上下文限制否缩短输入或减少历史上下文后再发送无
https://api.tokenfactory.cn/v1/images/generations400missing_required_parameter缺少必填请求参数否按文档补齐错误指出的公开参数后再发送无
https://api.tokenfactory.cn/v1/images/generations400invalid_parameter请求参数的类型或格式不正确否修正错误指出的公开参数类型或格式后再发送无
https://api.tokenfactory.cn/v1/images/generations502upstream_usage_missing服务响应缺少可验证的用量信息视情况保留平台请求编号联系支持；确认可安全重复后再发送中到高

错误返回报文 ​

适用完整地址 ​

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

HTTP 400；Content-Type: application/json；响应头：request-id: string、retry-after: 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、私有异步任务生命周期或视频生成。

相关说明 ​

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

TokenFactory 词元工厂 · 开发者文档 · 返回官网

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