Gemini 批量生图 API

模融Gemini 批量生图 API 参考。

Gemini 批量生图 API

批量图片接口是 MRXAPI 的异步扩展，使用 OpenAI 兼容的 /v1/images/batches 路径，不属于 Gemini 原生 /v1beta。它适合大量不需要即时返回的图片任务。

1. 适用场景

适用于批量提示词、离线素材生产、任务状态查询和 ZIP 下载。不适用于测量单张实时延迟或依赖即时展示的交互；单张实时请求请使用Gemini 生图 API。

2. 使用前提

批量能力需由当前部署和 API Key 分组共同启用。先查询批量模型：

curl "https://mrxapi.com/v1/images/batches/models" \
  -H "Authorization: Bearer $MRXAPI_KEY"

普通 /v1/models 或 /v1beta/models 列表中的模型不一定支持批量接口。

3. 接口总览

方法	路径	说明
`GET`	`/v1/images/batches/models`	可用于批量的模型
`POST`	`/v1/images/batches`	创建任务
`GET`	`/v1/images/batches`	查询任务列表
`GET`	`/v1/images/batches/{id}`	查询任务状态
`GET`	`/v1/images/batches/{id}/items`	查询条目
`GET`	`/v1/images/batches/{id}/items/{custom_id}/content`	下载单个输出
`GET`	`/v1/images/batches/{id}/download`	下载 ZIP
`POST`	`/v1/images/batches/{id}/cancel`	取消任务
`DELETE`	`/v1/images/batches/{id}/outputs`	删除输出文件
`DELETE`	`/v1/images/batches/{id}`	删除任务记录

4. 创建批量任务

curl --request POST "https://mrxapi.com/v1/images/batches" \
  -H "Authorization: Bearer $MRXAPI_KEY" \
  -H "Idempotency-Key: client-batch-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "task_name": "campaign-assets",
    "response_mime_type": "image/png",
    "image_size": "1K",
    "items": [
      {"custom_id":"asset-001","prompt":"未来城市晨雾，电影感","output_count":1},
      {"custom_id":"asset-002","prompt":"极简产品摄影，纯色背景","output_count":1}
    ]
  }'

5. 请求字段

字段	必填	说明
`model`	是	必须来自批量模型列表
`items`	是	至少一条任务
`items[].custom_id`	建议	调用方条目 ID，同批次内唯一
`items[].prompt`	是	每条图片描述
`items[].output_count`	否	每条输出数，受部署限制
`image_size`	否	仅使用模型/部署当前支持的值
`reference_images`	否	参考图，格式依接口响应约束

6. Idempotency-Key

每次创建任务都应携带唯一 Idempotency-Key。网络超时后先使用同一请求查询或重试该幂等键，避免重复任务和重复费用；相同幂等键配不同请求体会返回冲突。

7. 查询与下载

curl "https://mrxapi.com/v1/images/batches/BATCH_ID" \
  -H "Authorization: Bearer $MRXAPI_KEY"

任务完成后读取条目详情，成功项再下载单图或 ZIP。提交成功只表示已受理，不表示每项都成功；对失败项保留 custom_id 和错误信息后再决定重跑。

8. 取消和清理

取消会阻止尚未开始或可取消的工作，已完成项目不一定可回收。删除输出文件和删除任务记录是两个独立操作；清理前先把需要的图片保存到自己的存储。

9. 错误与验收

批量未启用、分组无权限、模型不可用、余额不足、重复 custom_id、无效参考图和幂等冲突都需要先修正再重试。验收时确认模型列表、创建、状态查询、条目下载和清理流程均使用同一 Key。