# Create an AI media generation schedule

- API version: 1.8.0
- Last updated: 2026-08-26
- Base URL: `https://api.ailingtu.com`
- Authentication: `x-api-key: <YOUR_API_KEY>`
- Success condition: HTTP 2xx and response `code === 0`
- Canonical operation schema: [JSON](/openapi/operations/createAiGenerationSchedule.json)
- All operations: [operation index](/openapi/operations/index.json)

## POST /v1/ai/schedule/create

Operation ID: `createAiGenerationSchedule`

Create an AI media generation schedule

Creates one or more AI image or video generation tasks. Use the returned scheduleId to query task status and generated assets. Keep polling the same schedule until every requested output succeeds or explicitly fails.

| 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 example: Generate an 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 a 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"
}
```

### Important notes

- 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.

### Related operations

- [GET /v1/ai/task/listByScheduleId](/openapi/operations/listAiTasksByScheduleId.md)

### Errors

| HTTP | Meaning |
|---:|---|
| 400 | Invalid request parameters or body. |
| 401 | The API key is missing or invalid. |
| 403 | The API key does not have permission for this operation. |
| 429 | Too many requests. Retry with exponential backoff. |
| 500 | Unexpected server error. Retry transient failures with exponential backoff. |