创建一个图片生成 task。 
POST /api/generations

​
请求参数

字段类型必填默认值说明
promptstring是无图片提示词，trim 后 1-12000 字符
modelIdstring否gpt-img2-officialgpt-img2、gpt-img2-official、gpt-img2-5-flare、gpt-img2-5-sunburst、nano-banana-pro、nano-banana2、nano-banana 或 grok-image-1.5
generationTypestring否text-to-imagetext-to-image 或 image-to-image
aspectRatiostring否模型默认值；当前图片模型通常为 9:16Auto、1:1、2:3、3:2、3:4、4:3、9:16、16:9；不同模型会进一步校验支持范围
resolutionstring否2.5 为 1K，其他模型为 2K1K、2K、4K；gpt-img2 只接受 1K，调用时需显式传入
qualitystring否lowlow、medium、high，按模型校验。两个 2.5 模型暂不开放 xhigh、max；不接受 auto
backgroundstring否autoOfficial 和两个 2.5 模型支持 auto、opaque、transparent；其他模型只接受 auto
imageCountnumber否1生成数量；上限取决于模型
inputAssetIdsstring[]图生图时是[]图生图参考资产 ID；image-to-image 必须传，公共接口最多 14 张，且受各模型上限约束
idempotencyKeystring否自动生成随机 key建议传入，trim 后最多 128 字符，用于防止重复提交
未知字段会被拒绝。所有字符串字段都会先 trim，再进入业务逻辑。 两个 2.5 模型支持 15 种固定比例：1:1、2:3、3:2、3:4、4:3、9:16、16:9、5:4、4:5、2:1、1:2、21:9、9:21、3:1、1:3。暂不开放 Auto 或自定义像素，输出统一为 PNG。4K 是分辨率档位，实际像素取决于比例，例如方图为 2880×2880。

​
计费

模型分辨率价格
gpt-img21K18 credits / 张
Official / 2.5，low1K / 2K / 4K18 / 18 / 36 credits / 张
Official / 2.5，medium1K / 2K / 4K60 / 120 / 180 credits / 张
Official / 2.5，high1K / 2K / 4K250 / 450 / 750 credits / 张
nano-banana-pro1K / 2K80 credits / 张
nano-banana-pro4K100 credits / 张
nano-banana21K60 credits / 张
nano-banana22K80 credits / 张
nano-banana24K120 credits / 张
nano-banana任意分辨率参数25 credits / 张
grok-image-1.5任意分辨率参数30 credits / 张
表内为不含参考图的基础价。使用 POST /api/pricing/quote 获取当前账户的单张报价，图片规格包含 kind: "image"、modelId、resolution、quality；Official 和两款 2.5 编辑还需传 referenceImageCount。报价包含参考图附加费及账户调价；不可定价组合返回 credits: null，不能据基础价提交。两款 2.5 基础价相同。 GPT Image 2 Official、Flare、Sunburst 每张参考图加收 10 基础积分 / 张输出图。参考资产 ID 去重后计数，上传重复 ID 不重复计费；实际提交侧按已授权的资产列表计算，不接受客户端自报费用。平台公开接口最多支持 14 张参考图。 例如 1K / low、5 张参考图：输出 1 张为 18 + 5 × 10 = 68 基础积分，输出 4 张为 68 × 4 = 272 基础积分。各输出任务分别应用账户倍率并取整；失败按该任务实际扣费退款，历史已提交任务不补扣新附加费。 总扣费为逐张计算并取整后的积分之和。创建 task 时会同时保存比例、分辨率、质量、背景和完整请求快照，重试沿用原任务。失败仅退回对应子任务的实扣积分。

​
模型限制

模型数量上限参考图上限备注
gpt-img2814公共接口有效上限；仅支持 1K
gpt-img2-official414三档质量，支持透明背景
gpt-img2-5-flare414快速生成，三档质量，15 种固定比例
gpt-img2-5-sunburst414精细编辑，三档质量，15 种固定比例
nano-banana-pro414Gemini 3 Pro image preview
nano-banana2414Gemini 3.1 Flash image preview
nano-banana414APIMart 仅支持 1K 输出，本平台分辨率参数不影响计费
grok-image-1.5101仅支持 1:1、16:9、9:16、3:2、2:3；文生图走 generation；图生图走 APIMart edit 接口，仅使用第一张参考图

​
示例

curl -X POST "$CUTAI_BASE_URL/api/generations" \
  -H "Authorization: Bearer $CUTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A clean product poster with dramatic studio lighting",
    "modelId": "gpt-img2-5-flare",
    "aspectRatio": "16:9",
    "resolution": "2K",
    "imageCount": 2,
    "idempotencyKey": "order_10001"
  }'

​
响应

{
  "batch": {
    "request": {
      "imageCount": 2,
      "modelId": "gpt-img2-5-flare",
      "aspectRatio": "16:9",
      "resolution": "2K",
      "prompt": "A clean product poster with dramatic studio lighting"
    },
    "results": [
      {
        "job": {
          "id": "job_xxx",
          "status": "queued"
        },
        "assets": []
      }
    ],
    "totalCreditCost": 40,
    "balanceAfterCredits": 960
  },
  "billing": {
    "totalCreditCost": 40,
    "balanceAfterCredits": 960
  }
}
HTTP 状态码为 202 表示任务已入队或已被接受。 billing.totalCreditCost 是本次 task 预扣的积分。billing.balanceAfterCredits 是任务接受后的账户剩余积分。为了兼容旧调用方，batch.totalCreditCost 和 batch.balanceAfterCredits 仍会保留同样的值。

​
JavaScript 示例

const response = await fetch(`${process.env.CUTAI_BASE_URL}/api/generations`, {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.CUTAI_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'A clean product poster with dramatic studio lighting',
    modelId: 'gpt-img2-5-flare',
    aspectRatio: '16:9',
    resolution: '2K',
    imageCount: 2,
    idempotencyKey: 'order_10001',
  }),
});

const payload = await response.json();
if (!response.ok) throw new Error(payload.error?.message ?? 'CutAI request failed');
console.log(payload.batch);