OneMux/文档中心/图片模型

图片模型

通过 OneMux 图片模型接口进行图片生成和图片编辑。

接口说明

图片模型使用独立的 Images 接口,不要把图片生成请求发送到 /v1/chat/completions。

  • 图片生成: POST https://api.onemux.net/v1/images/generations
  • 图片编辑: POST https://api.onemux.net/v1/images/edits
  • 鉴权: Authorization: Bearer YOUR_API_KEY
  • 模型: 使用当前模型列表接口返回的实际图片模型 ID

先获取当前可用模型:

curl https://api.onemux.net/v1/models \
  -H "Authorization: Bearer $ONEMUX_API_KEY"

图片模型是否支持生成、编辑、参考图、尺寸、质量、输出格式等参数,以模型列表和实际上游能力为准。

图片生成

使用 /v1/images/generations 发送文生图请求。

curl https://api.onemux.net/v1/images/generations \
  -H "Authorization: Bearer $ONEMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL_ID",
    "prompt": "一只坐在窗边的橘猫,午后自然光,写实摄影风格",
    "size": "1024x1024",
    "quality": "medium"
  }'

常用参数:

参数必填说明
model是当前可用的图片模型 ID
prompt是图片内容描述
size否图片尺寸,支持范围由模型决定
quality否图片质量,支持值由模型决定
n否生成数量,支持范围由模型决定
response_format否b64_json 或 url,仅支持的模型可用
background否透明或不透明背景,仅支持的模型可用
output_format否png、jpeg、webp,仅支持的模型可用

不要把某个模型支持的参数直接用于其他图片模型。遇到 model_not_found、invalid_model 或参数不支持错误时,请先确认模型 ID 和模型能力。

图片编辑

使用 /v1/images/edits 编辑已有图片。常见 OpenAI 兼容图片模型使用 multipart/form-data 上传图片:

curl https://api.onemux.net/v1/images/edits \
  -H "Authorization: Bearer $ONEMUX_API_KEY" \
  -F "model=YOUR_IMAGE_MODEL_ID" \
  -F "image[]=@input.png" \
  -F "prompt=将背景改为浅蓝色,保持主体和文字不变" \
  -F "size=1024x1024"

多张参考图可以重复传入 image[],例如:

-F "image[]=@person.png" \
-F "image[]=@product.png"

图片数量、图片格式、遮罩、参考图 URL 和 JSON 编辑格式由模型及上游渠道决定。只有模型明确支持时,才使用这些参数。

Python 调用

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ONEMUX_API_KEY"],
    base_url="https://api.onemux.net/v1",
)

result = client.images.generate(
    model="YOUR_IMAGE_MODEL_ID",
    prompt="一张简洁的蓝色科技风产品海报",
    size="1024x1024",
)

print(result.data[0].b64_json or result.data[0].url)

图片编辑通常需要直接提交 multipart 文件。如果当前 Python SDK 版本不支持目标模型的编辑参数,请使用上面的 cURL 请求。

返回结果

成功响应通常包含 data 数组:

{
  "created": 1760000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ]
}

部分模型在请求 response_format 为 url 时返回图片地址:

{
  "created": 1760000000,
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}

返回 Base64 时,请根据实际图片格式保存文件;返回 URL 时,请及时下载并自行保存,避免临时地址过期。

计费说明

图片模型不统一使用 Token 计费。OneMux 会按照模型当前发布的计费规则结算,可能包括:

  • 按生成图片张数计费
  • 按图片分辨率或质量档位计费
  • 按图片输入、输出 Token 或其他上游用量计费

实际价格、计费单位和支持规格以 模型目录 中对应模型的当前说明为准。请求失败通常不会产生成功结果对应的图片费用,但具体行为以页面显示和服务端返回为准。

常见问题

为什么不能使用对话接口生成图片?

图片模型使用独立的 Images 路由。发送到 /v1/chat/completions 或其他不匹配的接口,可能返回模型不支持该端点或参数错误。

为什么模型名称可以查询到,但请求仍然失败?

请检查模型是否允许图片生成或图片编辑、当前 API Key 是否有权限、请求参数是否属于该模型支持范围,以及对应上游渠道是否可用。

为什么返回的是 Base64 而不是图片链接?

不同模型或 response_format 设置会决定返回格式。收到 b64_json 时,需要在客户端自行解码保存;收到 url 时,需要下载返回地址。

图片生成很慢怎么办?

高分辨率、高质量或复杂编辑请求可能需要更长时间。客户端应设置合理的请求超时时间,不要因为客户端超时就重复提交相同请求,以免产生重复任务或费用。

GPT Image 2.6:SVG、GIF 与复杂度

GPT Image 2.6 系列新增 SVG 输出、GIF 动图输出和 complexity 参数。这些能力仅适用于支持它们的模型和上游渠道。

输出 SVG

SVG 用于图片生成,不用于图片编辑。调用生成接口时设置 output_format 为 svg,并将 n 设为 1。响应中的图片数据为 Base64,解码后保存为 .svg 文件。

{
  "model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
  "prompt": "一个简洁的蓝色几何图形标志",
  "output_format": "svg",
  "n": 1
}

部分上游配置可能还要求额外的 svg 对象,例如 svg.model。只有模型或渠道说明明确要求时才添加。并非所有图片模型和渠道都支持 SVG。

输出 GIF 动图

支持该能力的 GPT Image 2.6 模型可在图片生成接口中设置 output_format 为 gif。在模型支持时,可用 frame_count 和 frame_duration_ms 设置动画帧数和每帧时长。GIF 属于生成能力,不要假设图片编辑接口也能返回 GIF。

{
  "model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
  "prompt": "一只蓝色小鸟循环拍打翅膀的动画",
  "output_format": "gif",
  "frame_count": 6,
  "frame_duration_ms": 200
}

复杂度参数

GPT Image 2.6 系列支持 complexity:low、medium、high。简单修改可尝试较低复杂度,文字密集或布局复杂的图片可尝试较高复杂度。它与 quality 是不同参数,复杂度较高时生成可能更慢。

{
  "model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
  "prompt": "一张细节丰富的城市街景编辑插画",
  "complexity": "high",
  "quality": "high"
}

以上参数不是所有模型通用。若接口提示参数不支持,请移除可选参数,或确认所选模型和渠道的能力。