图像

图像模型可以根据提示生成图片，其中大多数还能编辑图片或根据参考图作画。两者都遵循 OpenAI 的 Images API，所以 OpenAI SDK 里的 client.images.generate() 和 client.images.edit() 改一下基础地址就能用。

下面两个示例都是真实的文件，发布前我们都会实际运行一遍。

生成

# Generate an image. The response carries a URL you can download from.
curl -sS "${OCEANTOKEN_BASE_URL:-https://api.oceantoken.ai/v1}/images/generations" \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A small lighthouse on a calm sea at dawn, watercolor",
    "size": "1024x1024",
    "n": 1
  }'

字段	作用
`model`	图像模型的 ID。
`prompt`	要画什么。
`size`	宽 x 高，比如 `1024x1024` 或 `1536x1024`。
`quality`	`low`、`medium` 或 `high`，适用于有质量档位的模型。档位越低越快、越便宜。
`n`	生成几张，适用于一次请求能出多张的模型。

模型不接受的取值会以 400 invalid_request 被拒绝，消息里会列出它接受的取值。想事先查看，见查询模型支持的选项。

响应

{
  "created": 1792000000,
  "data": [{"url": "https://..."}]
}

每张图片都以 URL 形式放在 data[].url 里，即使你请求的是 b64_json 也一样。请在 24 小时内下载：之后 URL 会失效（限制 → 保留期限）。图片也会出现在控制台的生成记录里。

编辑图片，或根据参考图作画

把模型要基于的图片发过去。用 JSON 时，把图片的 URL 或 data URL 放在 images 里：

# Edit an image, or generate from reference images: send the image's URL (or a
# data URL) in `images`. The response carries a URL for each result.
curl -sS --fail-with-body "${OCEANTOKEN_BASE_URL:-https://api.oceantoken.ai/v1}/images/edits" \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || date +%s%N)" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "Turn this logo into a glossy blue enamel pin on a white background",
    "images": ["https://docs.oceantoken.ai/img/oceantoken-mark-512.png"],
    "size": "1024x1024",
    "quality": "low"
  }'

也可以像 OpenAI SDK 和网页表单那样上传文件：

curl https://api.oceantoken.ai/v1/images/edits \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
  -F model="openai/gpt-image-2" \
  -F image=@product.png \
  -F prompt="把这件商品放在大理石厨房台面上，柔和的晨光"

多张参考图（比如一个人和一件衣服）放在同一个列表里（或者重复多个 image 字段）。每个模型能接受的数量有上限，写在它的选项里；超过会以 400 被拒绝，绝不会被悄悄截掉。
蒙版（mask，一张 PNG，透明区域标出要修改的部分）只在支持蒙版的模型上可用。不支持的模型会直接拒绝请求，而不是忽略蒙版照常运行。
/v1/images/generations 也接受参考图：这样的请求会按编辑处理。
URL 必须公开可访问。单张图片最大 25 MB，但整个请求最大 10 MB，所以大图请用 URL 发送（限制）。

查询模型支持的选项

模型接受的尺寸、质量档位、出图数量和参考图数量：

curl "https://api.oceantoken.ai/oceantoken/image/model-spec?model=openai/gpt-image-2" \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY"

返回内容的 spec 里有 aspectRatios、resolutions、qualities、maxImages（n 的最大值）和 maxReferences（参考图的最大数量）。

重试而不重复付费

图片生成出来就会扣费。请在每个请求上发送一个取值唯一的 Idempotency-Key 请求头：超时后用同一个键和同样的请求体重试，会拿回第一次的结果，而不是再生成（并再扣费）一张。见错误 → 重试会产生费用的请求。

费用

图像模型按张、按百万像素或按 token 计费，取决于模型，见计费方式。每个响应都在 x-oceantoken-cost 响应头里带上费用，控制台的日志列出每个请求。各模型的价格见 oceantoken.ai 上的模型页面。

下一步

想让对话模型读懂图片，请看图片输入。
想把图片变成视频，请看视频 → 图生视频。

生成​

响应​

编辑图片，或根据参考图作画​

查询模型支持的选项​

重试而不重复付费​

费用​

下一步​

生成

响应

编辑图片，或根据参考图作画

查询模型支持的选项

重试而不重复付费

费用

下一步