Images API

使用 APIVN API 生成图像

通过两个 JSON 接口，根据描述生成图像或编辑参考图像。先从简单请求开始，再添加模型支持的参数。

返回文档

连接 API

向本站 API 地址发送请求，设置 Content-Type: application/json 和 Authorization: Bearer YOUR_API_KEY。也支持 x-api-key。

请将 API key 保存在服务端。示例使用环境变量，不会代您发送请求。

Base URLhttps://apivn.dev/v1

AuthorizationBearer $STALI_API_KEY

read -r -s -p "STALI_API_KEY: " STALI_API_KEY
export STALI_API_KEY
printf '\n'
curl -fsS https://apivn.dev/v1/models -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}"

验证

选择图像模型

可使用 req/gpt-image-2 或 req/gemini-3.0-pro-image。省略 model 或传入空值时，两个图像接口均默认使用 req/gpt-image-2。

模型	每次请求价格
`req/gpt-image-2` GPT Image 2	$0.0455
`req/gemini-3.0-pro-image` Gemini 3.0 Pro Image	$0.0455

调用 GET /v1/models 查看当前模型列表及 pricing.per_request。API key 必须有权使用所选模型。

查看当前价格

根据描述生成图像

POST/v1/images/generationsapplication/json

向 /v1/images/generations 发送 POST 请求，包含 model 和图像描述 prompt。示例使用 n: 1 和 size: 1024x1024。处理完成后接口返回 JSON。stream 被强制设为 false，不返回 SSE 流。

cURL 示例使用 macOS、Linux 或 WSL 中的 Bash。Python 需先运行 pip install requests 安装依赖。Node.js 需使用 18 或更新版本，将代码保存为 .mjs 文件，并使用内置 fetch。

curl --fail-with-body --dump-header image-response-headers.txt "https://apivn.dev/v1/images/generations" \
  -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "req/gpt-image-2",
  "prompt": "A small botanical robot tending a seedling, studio product photography, soft natural light, clean ivory background, no text",
  "n": 1,
  "size": "1024x1024"
}'

编辑参考图像

POST/v1/images/editsapplication/json

向 /v1/images/edits 发送 JSON 格式的 POST 请求，包含非空 prompt 和 image。图像可为 data URL、base64 字符串或公开的 http(s) URL。使用 cURL 时，请将 https://example.com/reference.png 替换为您实际可公开访问的图像 URL。使用 Python 或 Node.js 时，请将 reference.png 放在运行示例的目录中。

image 也可写为 image_url、reference_image、ref_image 或 refImage。值可为字符串或 {url: ...} 对象；建议每次请求只提供一个图像字段。编辑接口接收 JSON，不接收 multipart/form-data。图像 URL 必须可公开访问且不能包含登录信息；内部地址会被拦截。参考图像支持 PNG、JPEG、WebP 和 GIF。若 SDK 的 images.edit 方法发送 multipart/form-data，请勿直接使用该方法。此接口要求 JSON；Python requests 和 Node.js fetch 示例使用正确的请求格式。

curl --fail-with-body --dump-header image-response-headers.txt "https://apivn.dev/v1/images/edits" \
  -H "Authorization: Bearer ${STALI_API_KEY:?STALI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "req/gpt-image-2",
  "prompt": "Keep the subject and composition, change the background to a warm ivory studio",
  "image": "https://example.com/reference.png",
  "n": 1,
  "size": "1024x1024"
}'

参数与限制

整个 JSON 请求不得超过 20 MiB，包括编码后的图像。Base64 会增加数据大小。Playground 的限制另行适用。

参数	必填	说明
`model`	选填	model：图像模型 ID，默认为 req/gpt-image-2。
`prompt`	必填	prompt：图像描述或编辑指令。编辑接口要求非空字符串。
`image`	编辑时必填	向 /v1/images/edits 发送 JSON 格式的 POST 请求，包含非空 prompt 和 image。图像可为 data URL、base64 字符串或公开的 http(s) URL。参考图像支持 PNG、JPEG、WebP 和 GIF。
`size`	选填	size：示例使用 1024x1024。支持的尺寸取决于模型及供应商。
`n`	选填	n：示例请求 1 张图像。该值会转发给供应商，支持的数量取决于模型。
`quality / response_format / output_format`	选填	quality、response_format 及其他参数会被转发。请仅发送模型支持的参数；网关不保证所有选项均会生效。

读取并保存返回图像

读取 JSON 响应中的 data 数组。图像内容可能位于 b64_json、b64Json 或 url，具体取决于供应商。其他字段可能因模型而异。

{
  "data": [
    {
      "b64_json": "<base64 image bytes>"
    }
  ]
}

收到 base64 时，可解码为图像文件，或根据实际格式使用正确 MIME 类型构建 data URL。不要假设所有结果都是 PNG。收到 URL 时，可用于下载或展示图像。URL 的有效期及访问条件取决于供应商。

保存 x-apivn-request-id 以便排查。成功响应还包含 x-apivn-model、x-apivn-price-vnd-per-request 和 x-apivn-cost-vnd 响应头。

按请求计费

图像模型按 request 计费。运行前请查看 GET /v1/models 中的 pricing.per_request；余额或 API key 消费限额可能阻止请求。响应或响应头中的 token 数不用于重新计算图像模型费用。新请求可能产生新的费用。

超时或断线后不要自动重发：先前请求可能已经处理。再次调用前，请查看 Usage 历史记录，并保存 request ID，以便核对或联系支持。

计费

谨慎处理错误

网关错误格式为 {type: "error", error: {type, message, ...}}。请读取 HTTP 状态码和 error.message，并在可用时保存 request ID。

HTTP	错误	处理方法
400	`invalid_request_error`	检查 JSON、模型、接口、prompt 和参考图像。413：减小整个请求的数据大小。
401	`authentication_error`	检查 API key。403：检查模型权限。402：检查余额、月度限额或待支付款项。
402	`insufficient_balance / api_key_monthly_limit / outstanding_undercharge`	检查余额、月度限额或待支付款项。
403	`model_not_allowed`	检查模型权限。402：检查余额、月度限额或待支付款项。
413	`request_too_large`	请减小整个请求的数据大小，包括 base64 数据。供应商或模型可能设有低于网关 JSON 上限的限制。
429	`rate_limit_error`	降低频率，并遵循返回的 Retry-After 或 retry_after_ms。502/503：供应商或服务可能暂时不可用。
502 / 503	`api_error / service_unavailable`	供应商或服务可能暂时不可用。

错误与重试

发送请求前

检查 API key、模型权限和当前价格。向正确接口发送 JSON，控制数据大小，并从一张图像开始。兼容 base64 和 URL 两种结果，保存 request ID，确认结果后再决定是否再次调用。

检查 API key 和模型权限。
在 /v1/models 中确认模型及价格。
检查 JSON、prompt 和图像数据。
兼容 base64 和 URL 结果。
查看 Usage 历史记录；保存 request ID，以便核对或联系支持。