# 创建 AI 图片或视频生成任务

- API 版本：1.10.0
- 最后更新：2026-09-29
- 服务地址：`https://api.ailingtu.com`
- 网页文档：[创建 AI 图片或视频生成任务](/openapi/schedule-create)
- 完整接口约束：[JSON Schema](/openapi/operations/createAiGenerationSchedule.json)
- 接口发现：[接口索引](/openapi/operations/index.json)

## POST /v1/ai/schedule/create

接口标识：`createAiGenerationSchedule`

创建 AI 图片或视频生成计划，支持提示词、参考图、模型、尺寸和批量数量。使用响应中的 scheduleId 查询任务状态与生成结果。

鉴权：请求头 `x-api-key: <YOUR_API_KEY>`；密钥仅保存在服务端。

成功判断：HTTP 2xx 且响应 code=0；异步任务还需查询最终状态。

### 请求参数

| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `taskId` | body | string | 否 | 调用方生成的任务标识；建议使用 8 位小写字母或数字 |
| `type` | body | IMAGE_GENERATION \| VIDEO_GENERATION | 是 | 生成内容类型 |
| `params.prompt` | body | string | 是 | 图片或视频生成提示词 |
| `params.model` | body | gpt-image-2 \| nano-banana-2 \| nano-banana-2-2k \| nano-banana-2-4k \| seedream5.0-lite \| gemini-omni-video \| veo3.1-lite-extend \| veo3.1-extend \| grok-imagine-1.5 \| seedance2.0-mini \| seedance2.0 \| seedance2.0-fast | 是 | 根据 type 选择下方列出的图片或视频模型 |
| `params.aspectRatio` | body | string | 条件必填 | 图片生成时使用，例如 1:1、9:16 |
| `params.seconds` | body | integer | 条件必填 | 视频生成时长；可选值取决于模型 |
| `params.size` | body | string | 条件必填 | 视频尺寸，例如 720x1280 |
| `params.inputReference` | body | string(uri) | 否 | 单张远程参考图 URL，主要用于视频生成 |
| `params.inputReferences` | body | string(uri)[] | 否 | 按顺序传入的远程参考图 URL；不支持 data URL |
| `params.watermark` | body | boolean | 否 | 视频是否添加水印，默认 false |
| `nums` | body | integer | 是 | 生成数量，未指定多结果时建议传 1 |
| `businessId` | body | string | 否 | 需要关联的业务对象 ID |
| `businessType` | body | MERCHANT_SKU \| AI_PURCHASE_TASK | 否 | 业务对象类型 |
| `promptId` | body | string | 否 | 已保存的提示词 ID |
| `execAt` | body | string(date-time) | 否 | ISO 8601 执行时间；省略时立即创建 |
| `name` | body | string | 否 | 生成计划显示名称 |

请求格式：`application/json`

### 请求示例：生成图片

```json
{
  "taskId": "img8a1b2",
  "type": "IMAGE_GENERATION",
  "params": {
    "prompt": "A clean product hero image on a bright studio background",
    "model": "gpt-image-2",
    "aspectRatio": "1:1",
    "inputReferences": [
      "https://static.ailingtu.com/ai-images/product-reference.jpg"
    ]
  },
  "nums": 1,
  "name": "Product hero image"
}
```

### 请求示例：生成视频

```json
{
  "taskId": "vid8c3d4",
  "type": "VIDEO_GENERATION",
  "params": {
    "prompt": "A clean 10-second product reveal video with a slow camera push-in",
    "model": "gemini-omni-video",
    "seconds": 10,
    "size": "720x1280",
    "inputReferences": [
      "https://static.ailingtu.com/ai-images/product-reference.jpg"
    ],
    "watermark": false
  },
  "nums": 1,
  "name": "Product reveal video"
}
```

### 成功响应

```json
{
  "code": 0,
  "data": {
    "scheduleId": "schedule_01k1example",
    "taskIds": [
      "task_01k1example"
    ]
  },
  "message": "success"
}
```

### 响应字段

以下列出主要层级；完整结构、联合类型及校验规则以接口 JSON Schema 为准。必填指字段所在对象中的约束。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | integer | 是 | 固定值：0 |
| `message` | string | 否 | — |
| `data` | object | 是 | — |
| `data.scheduleId` | string | 是 | — |
| `data.taskIds` | string[] | 否 | — |

### 接入说明与限制

- 图片模型：gpt-image-2、nano-banana-2、nano-banana-2-2k、nano-banana-2-4k、seedream5.0-lite。
- 视频模型：gemini-omni-video、veo3.1-lite-extend、veo3.1-extend、grok-imagine-1.5、seedance2.0-mini、seedance2.0、seedance2.0-fast。
- 视频时长：gemini-omni-video 支持 6/8/10 秒；veo3.1-lite-extend 和 veo3.1-extend 固定 8 秒；grok-imagine-1.5 支持 6/10/15/20/25/30 秒；seedance2.0-mini、seedance2.0 和 seedance2.0-fast 支持 4/8/10/12/15 秒。
- 图片生成传 IMAGE_GENERATION 与 params.aspectRatio；视频生成传 VIDEO_GENERATION、params.seconds 和 params.size。
- 参考图必须是可访问的 http/https URL；本地文件需先上传后再传入 URL。
- scheduleId 与 taskId 不同。创建成功后请使用 scheduleId 查询本计划的任务列表，不要因轮询中断而重复创建。

### 错误处理

| HTTP | 说明 |
|---|---|
| 400 | 请求参数或请求体无效，请修正后重试。 |
| 401 | API 密钥缺失或无效，请检查 x-api-key。 |
| 403 | API 密钥没有此接口的调用权限。 |
| 429 | 请求过于频繁，请采用指数退避重试。 |
| 500 | 服务端发生错误；对于暂时性故障采用指数退避重试。 |

业务 code 非零时也应按失败处理。不要对参数、权限或授权错误盲目重试。创建发布或生成任务超时后先查询原任务，避免重复创建。

### 相关接口

- [查询 AI 生成任务结果](/openapi/schedule-tasks) · [Markdown](/openapi/operations/listAiTasksByScheduleId.md)