图生图接口不直接接收本地文件路径。你需要先把本地图片上传成 CutAI 资产,拿到 asset.id 后再把它传给 POST /api/generations 的 inputAssetIds。 API Key 通道只提供一步文件上传,不需要签名直传,也不需要再注册资产。

上传文件

POST /api/public/uploads
Authorization: Bearer $CUTAI_API_KEY
Content-Type: multipart/form-data
字段类型必填默认值说明
filefile是无本地文件。支持 PNG、JPEG、WebP、MP4、WebM、MOV、MP3、M4A、AAC、WAV、OGG,最大 12MB
widthnumber否null图片宽度,正整数
heightnumber否null图片高度,正整数
durationSecondsnumber否不写入视频或音频时长,正数
curl -X POST "$CUTAI_BASE_URL/api/public/uploads" \
  -H "Authorization: Bearer $CUTAI_API_KEY" \
  -F "file=@/path/to/reference.png;type=image/png" \
  -F "width=1024" \
  -F "height=1024"
响应:
{
  "asset": {
    "id": "ast_xxx",
    "uploadKey": "users/usr_xxx/uploads/abc.png",
    "publicUrl": "https://cdn.example.com/users/usr_xxx/uploads/abc.png",
    "mimeType": "image/png",
    "width": 1024,
    "height": 1024,
    "metadata": {}
  }
}
后续图生图使用 asset.id,不是上传地址或公开 URL。同一个 API Key 上传的参考资产可以直接用于后续生成任务。

创建图生图任务

创建图生图任务时,把上一步返回的 asset.id 放进 inputAssetIds。
curl -X POST "$CUTAI_BASE_URL/api/generations" \
  -H "Authorization: Bearer $CUTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generationType": "image-to-image",
    "modelId": "gpt-img2",
    "prompt": "Keep the same product, create a premium studio ad poster",
    "aspectRatio": "9:16",
    "resolution": "2K",
    "imageCount": 1,
    "inputAssetIds": ["ast_xxx"],
    "idempotencyKey": "order_10001_i2i"
  }'
模型会校验参考图数量上限。例如 grok-image-1.5 只使用 1 张参考图,gpt-img2 支持更多参考图。具体限制见创建任务。

JavaScript 示例

import { readFile } from 'node:fs/promises';
import { basename } from 'node:path';
import { fileTypeFromBuffer } from 'file-type';

const baseUrl = process.env.CUTAI_BASE_URL;
const apiKey = process.env.CUTAI_API_KEY;
const filePath = '/path/to/reference.png';
const bytes = await readFile(filePath);
const detected = await fileTypeFromBuffer(bytes);
const contentType = detected?.mime ?? 'image/png';

const form = new FormData();
form.set('file', new File([bytes], basename(filePath), { type: contentType }));
form.set('width', '1024');
form.set('height', '1024');

const uploadResponse = await fetch(`${baseUrl}/api/public/uploads`, {
  method: 'POST',
  headers: { authorization: `Bearer ${apiKey}` },
  body: form,
});
const { asset } = await uploadResponse.json();
if (!uploadResponse.ok) throw new Error('Upload failed');

const generationResponse = await fetch(`${baseUrl}/api/generations`, {
  method: 'POST',
  headers: {
    authorization: `Bearer ${apiKey}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    generationType: 'image-to-image',
    modelId: 'gpt-img2',
    prompt: 'Keep the subject and turn it into a polished commercial poster',
    inputAssetIds: [asset.id],
  }),
});

const generation = await generationResponse.json();
if (!generationResponse.ok) throw new Error(generation.error?.message ?? 'Generation failed');
console.log(generation.batch.task.id);

常见错误

HTTPcode说明
400BAD_REQUEST缺少 file、表单格式不正确,或传入了不支持的字段
401UNAUTHORIZEDAPI Key 缺失或无效
413PAYLOAD_TOO_LARGE文件超过 12MB
415UNSUPPORTED_MEDIA_TYPE文件类型不支持
400INVALID_GENERATION_REQUEST图生图任务缺少 inputAssetIds 或参数不符合模型限制