# Create an AI image or video schedule

- API version: 1.11.0
- Last updated: 2026-11-16
- Server: `https://api.ailingtu.com`
- Web document: [Create an AI image or video schedule](/en/openapi/schedule-create)
- Full schema: [JSON Schema](/en/openapi/operations/createAiGenerationSchedule.json)
- Discovery: [Operation index](/en/openapi/operations/index.json)

## POST /v1/ai/schedule/create

Operation ID: `createAiGenerationSchedule`

Create scheduled AI image or video generation tasks with prompts, references, model options, dimensions, and output count. Use the returned scheduleId to query status and assets.

Authentication: Request header `x-api-key: <YOUR_API_KEY>`; keep the key on the server and never expose it in client code, logs or shared files.

Success criteria: HTTP 2xx with code=0; for asynchronous tasks, also query the final status.

### Request parameters

| Field | Location | Type | Required | Description |
|---|---|---|---|---|
| `taskId` | body | string | No | Caller-generated task identifier; an 8-character lowercase alphanumeric value is recommended |
| `type` | body | IMAGE_GENERATION \| VIDEO_GENERATION | Yes | Media generation type |
| `params.prompt` | body | string | Yes | Image or video generation prompt |
| `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 | Yes | Select one of the image or video models listed below, matching type |
| `params.aspectRatio` | body | string | Conditional | Required for images, for example 1:1 or 9:16 |
| `params.seconds` | body | integer | Conditional | Video duration; allowed values depend on the model |
| `params.size` | body | string | Conditional | Video dimensions, for example 720x1280 |
| `params.inputReference` | body | string(uri) | No | One remote reference image URL, primarily for video generation |
| `params.inputReferences` | body | string(uri)[] | No | Ordered remote reference image URLs; data URLs are not supported |
| `params.watermark` | body | boolean | No | Whether to add a video watermark; defaults to false |
| `nums` | body | integer | Yes | Number of outputs; use 1 unless multiple results are needed |
| `businessId` | body | string | No | Optional related business object ID |
| `businessType` | body | MERCHANT_SKU \| AI_PURCHASE_TASK | No | Related business object type |
| `promptId` | body | string | No | Saved prompt ID |
| `execAt` | body | string(date-time) | No | ISO 8601 execution time; omit to create immediately |
| `name` | body | string | No | Display name for the generation schedule |

Request format: `application/json`

### Request example: Generate image

```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"
}
```

### Request example: Generate video

```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"
}
```

### Success response

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

### Response fields

Main levels are listed below. The endpoint JSON Schema is authoritative for the full structure, unions and validation rules; Required refers to the containing object.

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | integer | Yes | Fixed value: 0 |
| `message` | string | No | — |
| `data` | object | Yes | — |
| `data.scheduleId` | string | Yes | — |
| `data.taskIds` | string[] | No | — |

### Integration notes and limits

- Image models: gpt-image-2, nano-banana-2, nano-banana-2-2k, nano-banana-2-4k, seedream5.0-lite.
- Video models: gemini-omni-video, veo3.1-lite-extend, veo3.1-extend, grok-imagine-1.5, seedance2.0-mini, seedance2.0, seedance2.0-fast.
- Video durations: gemini-omni-video supports 6/8/10s; veo3.1-lite-extend and veo3.1-extend are fixed at 8s; grok-imagine-1.5 supports 6/10/15/20/25/30s; seedance2.0-mini, seedance2.0, and seedance2.0-fast support 4/8/10/12/15s.
- For images, use IMAGE_GENERATION with params.aspectRatio. For videos, use VIDEO_GENERATION with params.seconds and params.size.
- References must be accessible http/https URLs. Upload local files before passing their URLs.
- scheduleId and taskId are different. Query the same scheduleId after creation and do not recreate a task only because polling was interrupted.

### Error handling

| HTTP | Description |
|---|---|
| 400 | The request parameters or body are invalid. Fix them and retry. |
| 401 | The API key is missing or invalid. Check x-api-key. |
| 403 | The API key has no permission to call this endpoint. |
| 429 | Too many requests. Retry with exponential backoff. |
| 500 | The server failed. Retry transient failures with exponential backoff. |

Treat any non-zero business code as a failure. Do not blindly retry parameter, permission or authorization errors. If creating a publishing or generation task times out, query the existing task first instead of creating another one.

### Related endpoints

- [List AI generation tasks](/en/openapi/schedule-tasks) · [Markdown](/en/openapi/operations/listAiTasksByScheduleId.md)
