跳到主要内容
MarkdownLLMs.txt

OpenAI Images 格式

本页示例中的 {BASE_URL} 表示 https://api.uniall.ai。

已有 OpenAI Images 客户端或需要图片 URL 时使用此格式。文生图和图片编辑均提供同步接口；不适合保持长连接的客户端可使用 UniAll 异步任务。

接口​

流程方法与路径行为
文生图POST /v1/images/generations等待生成并返回图片 URL。
图片编辑POST /v1/images/edits等待生成并返回图片 URL。
异步生成或编辑POST /v1/images/tasks立即返回任务 ID。
查询异步任务GET /v1/images/tasks/{task_id}返回任务状态和结果。

鉴权​

Authorization: Bearer sk-***
Content-Type: application/json

也支持 x-api-key: sk-***，但 OpenAI 风格客户端推荐使用 Bearer 鉴权。

请求参数​

参数类型必填说明
modelstring是nano-banana-2、nano-banana-pro 或 nano-banana-2-lite。
promptstring是生成或编辑指令。
resolutionstring否0.5k、1k、2k 或 4k，默认 1k；受模型限制。
aspect_ratiostring否输出比例，例如 1:1、3:4 或 16:9。
imagesstring[]条件必填编辑使用的参考图 URL 或完整 Data URL。
ninteger否保持为 1，当前每次请求生成一张图片。
output_formatstring否输出格式，例如 png。
request_idstring否异步任务使用的非敏感业务关联 ID。

0.5K 仅适用于 nano-banana-2，必须写成 resolution: "0.5k"。

同步文生图​

curl -X POST "{BASE_URL}/v1/images/generations" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "电影感产品图：透明香水瓶放在黑色岩石上，蓝色薄雾，无文字",
    "resolution": "0.5k",
    "aspect_ratio": "1:1",
    "n": 1,
    "output_format": "png"
  }'

同步图片编辑​

curl -X POST "{BASE_URL}/v1/images/edits" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "保持人物和构图不变，把背景替换成雨夜霓虹街道",
    "images": ["https://example.com/reference/person.png"],
    "resolution": "2k",
    "aspect_ratio": "3:4",
    "n": 1,
    "output_format": "png"
  }'

参考图 URL 必须能被服务端直接访问。多张参考图按提示词描述顺序放入 images。

同步响应​

{
  "created": 1787366400,
  "data": [
    {
      "url": "https://media.example.com/generated/image.png",
      "width": 512,
      "height": 512
    }
  ]
}

从 data[0].url 读取结果；如需长期保留，请及时转存。

异步任务​

生成和编辑共用 POST /v1/images/tasks。请求包含 images 时按编辑任务处理。

curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "电影感产品图：透明香水瓶放在黑色岩石上",
    "resolution": "0.5k",
    "aspect_ratio": "1:1",
    "n": 1,
    "output_format": "png",
    "request_id": "image-20260822-0001"
  }'
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "image.generation.job",
  "model": "nano-banana-2",
  "status": "PENDING",
  "progress": 0,
  "image_url": null
}

保存 task_id；不要因为任务仍为 PENDING 就重新创建。

任务状态与结果​

curl "{BASE_URL}/v1/images/tasks/task_xxx" \
  -H "Authorization: Bearer sk-***"

开始时每 2～3 秒查询一次，等待时间变长后降到每 5～10 秒一次。?refresh=true 仅用于确实需要立即刷新上游状态的场景，不要每次轮询都添加。

状态含义处理方式
PENDING等待处理继续轮询。
IN_PROGRESS正在生成继续轮询。
COMPLETED已完成优先读取 data[0].url，再回退到 image_url。
FAILED生成失败读取公开错误并停止。
CANCELLED已取消停止轮询。
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "model": "nano-banana-2",
  "status": "COMPLETED",
  "progress": 100,
  "image_url": "https://media.example.com/generated/image.png",
  "data": [
    {
      "url": "https://media.example.com/generated/image.png",
      "width": 512,
      "height": 512
    }
  ],
  "error": null
}

旧版兼容模型名​

NanoBanana2-0.5K、NanoBananaPro-4K 等固定分辨率别名可能仍可兼容使用，但已经弃用，并可能随时移除。新代码请使用统一模型 ID 加 resolution。

计费说明​

计费取决于所选模型和分辨率，请以账号当前可见价格为准。同步请求断开或客户端超时，不代表生成已经停止。

常见错误​

  • 把 0.5K 写成 resolution: "512" 或 "512K"，正确值是 "0.5k"。
  • 为 nano-banana-pro 或 nano-banana-2-lite 请求 0.5K。
  • 参考图 URL 需要登录或临时 Cookie，导致服务端无法访问。
  • 客户端超时后立即重试，产生重复生成。
  • 根据错误消息文本分支，而不是 HTTP 状态码和结构化错误字段。

相关页面​