Skip to content

图像生成与编辑(Token 计费) ​

通过 OpenAI 兼容接口使用 gpt-image-2 token 计费通道进行图像生成与编辑

本文适用于 gpt-image-2 token 计费通道,以及需要更完整 OpenAI Images API 兼容能力的账号。

如果你的账号开通的是按张计费 SKU,请优先参考 图像生成与编辑(按张计费)。按张计费 SKU 只承诺稳定尺寸、quality=low/auto、PNG、URL 输出和 n=1。

INFO

本文不适用按张计费逆向渠道准入验收。按张渠道验收以按张计费文档中的稳定参数、edit 能力和异步任务标准为准。

快速开始 ​

bash
curl -X POST "https://aiapi.fhddos.com/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A futuristic skyline at dusk",
    "size": "1024x1024",
    "quality": "medium",
    "response_format": "b64_json"
  }'

Python SDK:

python
from openai import OpenAI

client = OpenAI(base_url="https://aiapi.fhddos.com/v1", api_key="$TOKEN")

result = client.images.generate(
    model="gpt-image-2",
    prompt="A futuristic skyline at dusk",
    size="1024x1024",
    quality="medium",
    response_format="b64_json",
)
print(result.data[0].b64_json)

文生图 /v1/images/generations ​

参数表 ​

参数类型必填说明
promptstring是图像描述文本
modelstring是固定 gpt-image-2
ninteger否生成数量,默认 1;部分兼容渠道仅支持 n=1
sizestring否widthxheight 或 auto,默认 1024x1024
qualitystring否low / medium / high / auto;平台默认 low
backgroundstring否transparent / opaque / auto
output_formatstring否png / jpeg;webp 为官方字段但不保证所有渠道可用
output_compressioninteger否0-100,仅 JPEG / WebP 生效
response_formatstring否url / b64_json,默认 b64_json
moderationstring否low / auto
userstring否终端用户标识

WARNING

stream 和 partial_images 是 OpenAI 官方定义的字段,但 gpt-image-2 官方标注不支持流式图片生成。传入时不会返回可用图片流事件。

分辨率规则 ​

token 计费通道按 OpenAI 兼容能力处理尺寸。size 参数格式为 widthxheight 或 auto,常见约束如下:

约束规则
最大边长任一边不超过 3840 px
最小总像素width x height 不低于 655,360
最大总像素width x height 不超过 8,294,400
对齐要求宽和高都必须是 16 的倍数
宽高比限制长边 : 短边不超过 3:1

常用值:

size用途
auto模型根据 prompt 自动选择尺寸
1024x1024通用方图
1536x1024横版 3:2
1024x1536竖版 2:3
2048x20482K 方图
2048x11522K 横版 16:9
1152x20482K 竖版 9:16

具体可用尺寸仍以账号实际路由到的通道能力为准。

响应体 ​

json
{
  "created": 1762789802,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUg...",
      "revised_prompt": "A futuristic skyline at dusk with neon lights"
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 4096,
    "total_tokens": 4108
  }
}
字段说明
created创建时间戳
data[].b64_jsonBase64 编码图片,response_format=b64_json 时返回
data[].url图片 URL,response_format=url 时返回
data[].revised_prompt模型优化后的提示词
usagetoken 用量;token 计费通道会优先按平台记录或上游返回的 usage 结算

URL 输出 ​

设置 response_format=url 可获取图片 URL:

python
result = client.images.generate(
    model="gpt-image-2",
    prompt="A clean studio product photo of a matte white ceramic mug",
    size="1024x1024",
    quality="low",
    response_format="url",
)
print(result.data[0].url)

平台对 URL 输出采用本地托底策略:

  1. 请求图片结果。
  2. 将图片转存到平台对象存储。
  3. 在 data[].url 返回可访问 URL。

行为是确定性的:

  • 若平台已配置对象存储,返回 data[].url。
  • 若未配置对象存储,返回 image_url_not_available。
  • 不会静默降级为 b64_json。

改图 /v1/images/edits ​

JSON 请求体 ​

通过 images[].image_url 或 images[].file_id 指定底图:

bash
curl -X POST "https://aiapi.fhddos.com/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "换种风格",
    "size": "1024x1024",
    "quality": "medium",
    "images": [
      { "image_url": "https://example.com/base-image.png" }
    ]
  }'

多参考图示例:

bash
curl -X POST "https://aiapi.fhddos.com/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "参考第 1 张的主体轮廓、第 2 张的配色和第 3 张的材质,生成一张干净的电商主图",
    "size": "1024x1024",
    "quality": "high",
    "images": [
      { "image_url": "https://example.com/reference-subject.png" },
      { "image_url": "https://example.com/reference-color.png" },
      { "image_url": "https://example.com/reference-texture.png" }
    ]
  }'

Multipart 上传 ​

bash
curl -X POST "https://aiapi.fhddos.com/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gpt-image-2" \
  -F "image=@base.png" \
  -F "mask=@mask.png" \
  -F "prompt=在天空中加入热气球"

改图参数表 ​

参数类型必填说明
promptstring是编辑指令
modelstring是固定 gpt-image-2
imagesarray否输入图像列表,最多 14 张
images[].image_urlstring否图像的公开可访问 URL
images[].file_idstring否通过 Files API 上传后获得的文件 ID
maskobject否蒙版,结构同图像引用
sizestring否输出尺寸,默认 1024x1024
qualitystring否low / medium / high / auto,默认 low
backgroundstring否transparent / opaque / auto
input_fidelitystring否high / low
output_formatstring否png / jpeg
output_compressioninteger否0-100
moderationstring否low / auto
response_formatstring否url / b64_json
ninteger否生成数量,默认 1
userstring否终端用户标识

INFO

images[].image_url 和 images[].file_id 二选一。部分兼容渠道会由平台在内部改写为 multipart 请求以保证可执行,不影响对外接口形态。

异步图片任务 ​

平台提供托管异步图片任务接口。异步接口不是 OpenAI 官方后台任务协议,而是平台先创建 image_ 任务,再由后台 worker 执行同步图像请求,最后通过轮询接口返回托管图片 URL。

文生图任务 ​

bash
curl -X POST "https://aiapi.fhddos.com/v1/images/generations/async" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean studio product photo of a matte white ceramic mug",
    "size": "1024x1024",
    "quality": "low",
    "response_format": "url"
  }'

查询任务:

bash
curl -X GET "https://aiapi.fhddos.com/v1/images/generations/{id}" \
  -H "Authorization: Bearer $TOKEN"

改图任务 ​

bash
curl -X POST "https://aiapi.fhddos.com/v1/images/edits/async" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gpt-image-2" \
  -F "prompt=将这张图片转换为干净的电商主图" \
  -F "response_format=url" \
  -F "image=@/path/to/base.png"
状态说明
pending排队中
in_progress后台执行中
completed已完成,读取 data[].url
failed失败,读取 error.code / error.message

异步任务要求平台已配置公开可访问的对象存储。未配置时,创建任务会返回 storage_not_configured。

计费 ​

token 计费通道按平台记录或上游返回的 token 用量结算:

类型价格口径
text input按输入文本 token
cached text input按缓存命中输入 token
image input改图或多模态图片输入 token
image output图片输出 token

单张预估只用于成本预估,实际账单以消费日志和控制台「模型价格」页面为准。

TIP

按张计费和 token 计费的折扣、单价、账单字段不同。对账时以消费日志中的实际金额为准,不要把展示用 token bucket 当成额外账单行。

错误码 ​

错误码说明
image_url_not_available请求 URL 输出但平台未配置对象存储
n_not_supported当前通道不支持 n>1,请拆分请求
unsupported_image_input异步改图暂不支持该输入形式
content_policy_violation内容审核未通过
suspected_black_image_from_upstream返回疑似纯黑图,已拦截

OpenAPI 参考 ​

本文档的交互式 API 参考覆盖 token 计费通道的完整请求体和响应体 schema。账号实际可用参数仍以控制台开通能力和运行时错误返回为准。

OpenAPI ​

yaml
openapi: 3.0.0
info:
  title: gpt-image-2 Token Billing API
  description: gpt-image-2 图像生成与编辑 — token 计费 OpenAI 兼容接口
  version: 1.0.0
servers:
  - url: https://aiapi.fhddos.com
    description: Fhddos 生产环境
security:
  - BearerAuth: []
paths:
  /v1/images/generations:
    post:
      tags:
        - gpt-image-2
      summary: 文生图
      description: 使用 gpt-image-2 从文本生成图像
      operationId: createGptImage2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerationRequest'
            examples:
              basic:
                summary: 基础文生图
                value:
                  model: gpt-image-2
                  prompt: A futuristic skyline at dusk
                  size: 1024x1024
                  quality: medium
              with-url-output:
                summary: 请求返回 URL
                value:
                  model: gpt-image-2
                  prompt: A clean studio product photo of a matte white ceramic mug
                  size: 1024x1024
                  quality: low
                  response_format: url
      responses:
        '200':
          description: 图像生成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
              example:
                created: 1762789802
                data:
                  - b64_json: iVBORw0KGgoAAAANSUhEUg...
                    revised_prompt: A futuristic skyline at dusk with neon lights
                usage:
                  input_tokens: 12
                  output_tokens: 4096
                  total_tokens: 4108
components:
  schemas:
    GenerationRequest:
      type: object
      required:
        - prompt
        - model
      description: gpt-image-2 文生图请求体(对齐 types.ImageGenerationRequestDoc)
      properties:
        prompt:
          type: string
          description: 图像描述文本
        model:
          type: string
          enum:
            - gpt-image-2
          description: 模型名称
        background:
          type: string
          enum:
            - transparent
            - opaque
            - auto
          description: 背景模式。transparent 输出带 alpha 通道的 PNG
        moderation:
          type: string
          enum:
            - low
            - auto
          description: 内容审核级别
        'n':
          type: integer
          minimum: 1
          default: 1
          description: 生成数量。部分兼容渠道仅支持 n=1,详见文档「渠道差异」
        output_compression:
          type: integer
          minimum: 0
          maximum: 100
          description: 压缩率,仅 jpeg/webp 生效
        output_format:
          type: string
          enum:
            - png
            - jpeg
            - webp
          description: 输出格式。webp 为官方字段但当前不支持
        partial_images:
          type: integer
          minimum: 0
          description: 官方字段。gpt-image-2 不支持流式,此字段不会生效
        quality:
          type: string
          enum:
            - low
            - medium
            - high
            - auto
          default: low
          description: 图像质量。平台默认 low(未传时自动填充)
        response_format:
          type: string
          enum:
            - url
            - b64_json
          default: b64_json
          description: url 时平台转存对象存储后返回可访问 URL
        size:
          type: string
          default: 1024x1024
          example: 1024x1024
          description: >-
            图像尺寸,格式 widthxheight 或 auto。约束:16 的倍数、单边 ≤ 3840px、总像素
            655360–8294400、长短边比 ≤ 3:1
        stream:
          type: boolean
          default: false
          description: '官方字段。gpt-image-2 标注 Streaming: Not supported,传入会返回普通 JSON'
        user:
          type: string
          description: 终端用户标识
    ImageResponse:
      type: object
      description: 对齐 types.ImageResponse
      properties:
        created:
          type: integer
          description: 创建时间戳
        background:
          type: string
          description: 实际使用的背景模式
        data:
          type: array
          items:
            $ref: '#/components/schemas/ImageResponseData'
        output_format:
          type: string
          description: 实际输出格式
        quality:
          type: string
          description: 实际质量等级
        size:
          type: string
          description: 实际输出尺寸
        usage:
          $ref: '#/components/schemas/Usage'
    ImageResponseData:
      type: object
      description: 对齐 types.ImageResponseDataInner
      properties:
        url:
          type: string
          description: 图片 URL(response_format=url 时)
        b64_json:
          type: string
          description: Base64 编码图片(response_format=b64_json 时)
        revised_prompt:
          type: string
          description: 模型优化后的提示词
        size:
          type: string
          description: 单张图片尺寸
        error:
          $ref: '#/components/schemas/ImageGenerationError'
          description: 单张图片生成失败时的错误信息(组图场景)
    Usage:
      type: object
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        total_tokens:
          type: integer
    ImageGenerationError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <your-api-key>'

Fhddos AI 用户文档