您的浏览器不支持JavaScript,请启用JavaScript以获得最佳体验。
Create an AI image or video schedule
Developer docs / AI content generation

Create an AI image or video schedule

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.

POST/v1/ai/schedule/create
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 body fields

FieldTypeRequiredDescription
taskIdstringNoCaller-generated task identifier; an 8-character lowercase alphanumeric value is recommended
typeIMAGE_GENERATION | VIDEO_GENERATIONYesMedia generation type
params.promptstringYesImage or video generation prompt
params.modelgpt-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-fastYesSelect one of the image or video models listed below, matching type
params.aspectRatiostringConditionalRequired for images, for example 1:1 or 9:16
params.secondsintegerConditionalVideo duration; allowed values depend on the model
params.sizestringConditionalVideo dimensions, for example 720x1280
params.inputReferencestring(uri)NoOne remote reference image URL, primarily for video generation
params.inputReferencesstring(uri)[]NoOrdered remote reference image URLs; data URLs are not supported
params.watermarkbooleanNoWhether to add a video watermark; defaults to false
numsintegerYesNumber of outputs; use 1 unless multiple results are needed
businessIdstringNoOptional related business object ID
businessTypeMERCHANT_SKU | AI_PURCHASE_TASKNoRelated business object type
promptIdstringNoSaved prompt ID
execAtstring(date-time)NoISO 8601 execution time; omit to create immediately
namestringNoDisplay name for the generation schedule
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.
Success response
{
  "code": 0,
  "data": {
    "scheduleId": "schedule_01k1example",
    "taskIds": [
      "task_01k1example"
    ]
  },
  "message": "success"
}
Request example · Generate image
{
  "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
{
  "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"
}

Response and errors

Main response fields come from the published contract; see the JSON Schema. Required refers to the constraint in the containing object.

FieldTypeRequiredDescription
codeintegerYesFixed value: 0
messagestringNo—
dataobjectYes—
data.scheduleIdstringYes—
data.taskIdsstring[]No—
  • HTTP 400The request parameters or body are invalid. Fix them and retry.
  • HTTP 401The API key is missing or invalid. Check x-api-key.
  • HTTP 403The API key has no permission to call this endpoint.
  • HTTP 429Too many requests. Retry with exponential backoff.
  • HTTP 500The server failed. Retry transient failures with exponential backoff.

Fix parameter, permission or authorization errors before retrying. If task creation times out, query existing tasks first and do not submit duplicates after an interrupted poll.

Last updated · 2026-11-16