Video Generation - GravitexAI Documentation

Introduction

The video generation API supports text-to-video, image-to-video, video-to-video, and more. Through a unified API interface, you can call multiple mainstream video generation models including Sora 2, Veo, Ali Wanxiang, and Doubao Seedance. Important Note: Video generation is an asynchronous task. You need to first submit a task to get a task ID, then poll the task status until it succeeds.

Supported Models and Features

Model Series	Model Name	Supported Features
Sora 2	`sora-2`	Text-to-video, Image-to-video, Video-to-video (Remix mode)
Google Veo	`veo-3.0-fast-generate-001`	Text-to-video (first frame mode)
	`veo-3.1-fast-generate-preview`	Text-to-video (first frame mode, first/last frame mode)
Ali Wanxiang	`wan2.5-t2v-preview`	Text-to-video
	`wan2.5-i2v-preview`	Image-to-video (first frame mode)
Doubao Seedance	`doubao-seedance-1-0-lite-t2v-250428`	Text-to-video
	`doubao-seedance-1-0-lite-i2v-250428`	Image-to-video (first frame mode, first/last frame mode, reference image mode)
	`doubao-seedance-1-0-pro-250528`	Text-to-video (first frame mode)
	`doubao-seedance-1-5-pro-251215`	Text-to-video, Image-to-video (first frame mode, first/last frame mode), with audio
	`doubao-seedance-1-5-pro-251215-noAudio`	Text-to-video, Image-to-video (first frame mode, first/last frame mode), silent video

Feature Description:

Text-to-Video (T2V): Generate video from text prompts only
Image-to-Video (I2V): Generate video based on reference images
- First Frame Mode: Use first frame image as starting scene
- First/Last Frame Mode: Use first and last frame images to control video start and end scenes
- Reference Image Mode: Use reference images as style reference (only supported by some models)
Video-to-Video (Remix): Regenerate based on existing video (only Sora 2 supports)

Authentication

Authorization

string

required

Bearer Token, e.g. Bearer sk-xxxxxxxxxx

API Endpoints

Submit Video Task

POST /v1/video/generations Submit a video generation task and return a task ID for subsequent queries.

Query Video Task

GET /v1/video/generations/{task_id} Query the status and results of a video generation task by task ID.

Path Parameters

task_id

string

required

Video generation task ID returned by the submit task interface

Response Examples

Task Status Description:

Status	Description	Suggested Action
`queued`	Task queued, waiting for processing	Continue polling
`in_progress`	Task being processed	Continue polling
`succeeded`	Task completed successfully	Download video
`failed`	Task failed	View error reason

Response Example (Queued):

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "queued",
  "format": "mp4"
}

Response Example (In Progress):

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "in_progress",
  "format": "mp4"
}

Response Example (Completed):

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "succeeded",
  "format": "mp4"
}

Response Example (Failed):

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "failed",
  "format": "mp4",
  "error": {
    "code": 400,
    "message": "Prompt contains inappropriate content"
  }
}

Usage Example

curl -X GET "https://api.gravitex.ai/v1/video/generations/video_69095b4ce0048190893a01510c0c98b0" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"

Download Video

GET /v1/video/generations/download?id={videoId} Download completed video files (Sora 2 only).

Query Parameters

string

required

Video ID returned by the query task interface (task_id)

Response Example

{
  "success": true,
  "generation_id": "video_69095b4ce0048190893a01510c0c98b0",
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "format": "mp4",
  "size": 15728640,
  "base64": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB...",
  "data_url": "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB..."
}

Response Field Description:

Field	Type	Description
`success`	boolean	Success status
`generation_id`	string	Generation ID (same as videoId)
`task_id`	string	Task ID
`format`	string	Video format (fixed as `"mp4"`)
`size`	number	Video file size (bytes)
`base64`	string	Base64 encoded video data
`data_url`	string	Data URL format video data, can be used directly in frontend `<video>` tags

Usage Example

curl -X GET "https://api.gravitex.ai/v1/video/generations/download?id=video_69095b4ce0048190893a01510c0c98b0" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"

Submit Video Task

POST /v1/video/generations Submit a video generation task and return a task ID for subsequent queries.

Usage Examples

Sora 2
Veo
Ali Wanxiang
Doubao Seedance

1. Text-to-Video (Basic Example)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cute little cat playing in the garden, sunny and warm",
    "seconds": "4",
    "size": "720x1280"
  }'

2. Text-to-Video (Landscape, 8 seconds)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cute little cat playing in the garden, sunny and warm",
    "seconds": "8",
    "size": "1280x720"
  }'

3. Image-to-Video (First Frame Mode)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cute little cat playing in the garden, sunny and warm",
    "seconds": "4",
    "size": "720x1280",
    "input_reference": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
  }'

4. Remix Mode (Video-to-Video)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "Change the video to a night scene with stars",
    "seconds": "4",
    "size": "720x1280",
    "remix_from_video_id": "video_69095b4ce0048190893a01510c0c98b0"
  }'

1. Text-to-Video (Basic Example)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "Aerial view of a sci-fi city at dawn, sunlight piercing through clouds",
    "durationSeconds": 8,
    "aspectRatio": "16:9",
    "resolution": "1080p",
    "fps": 24,
    "generateAudio": true,
    "personGeneration": "allow_all",
    "addWatermark": false
  }'

2. Text-to-Video (Portrait, with Random Seed)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "Aerial view of a sci-fi city at dawn, sunlight piercing through clouds",
    "durationSeconds": 6,
    "aspectRatio": "9:16",
    "resolution": "720p",
    "fps": 30,
    "generateAudio": false,
    "personGeneration": "allow_adult",
    "addWatermark": true,
    "seed": 12345,
    "sampleCount": 2
  }'

3. Image-to-Video (First Frame Mode)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "Generate video based on this image, scene gradually unfolds",
    "durationSeconds": 8,
    "aspectRatio": "16:9",
    "resolution": "1080p",
    "fps": 24,
    "image": "data:image/png;base64,iVBORw0KGgoAAxxxx...",
    "generateAudio": true,
    "personGeneration": "dont_allow",
    "addWatermark": false
  }'

4. Image-to-Video (First/Last Frame Mode, only veo-3.1 supports)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-fast-generate-preview",
    "prompt": "Transition from first image to second image",
    "durationSeconds": 8,
    "aspectRatio": "16:9",
    "resolution": "1080p",
    "fps": 24,
    "image": "data:image/png;base64,iVBORw0KGgoAAxxxx...",
    "lastFrame": "data:image/png;base64,iVBORw0KGgoAAyyyy...",
    "generateAudio": true,
    "seed": 67890,
    "sampleCount": 1
  }'

1. Text-to-Video (Basic Example)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.5-t2v-preview",
    "prompt": "A kitten slowly opens its eyes, ears gently twitch, camera slowly pushes in",
    "duration": 5,
    "size": "1280*720",
    "smart_rewrite": true,
    "generate_audio": true
  }'

2. Text-to-Video (10 seconds, 1080p, with Random Seed)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.5-t2v-preview",
    "prompt": "A kitten slowly opens its eyes, ears gently twitch, camera slowly pushes in",
    "duration": 10,
    "size": "1920*1080",
    "smart_rewrite": false,
    "generate_audio": false,
    "seed": 123456
  }'

3. Image-to-Video (First Frame Mode)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.5-i2v-preview",
    "prompt": "Kitten slowly opens its eyes, ears gently twitch, camera slowly pushes in",
    "duration": 5,
    "resolution": "720p",
    "smart_rewrite": true,
    "generate_audio": true,
    "image": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
  }'

4. Image-to-Video (with Custom Audio)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.5-i2v-preview",
    "prompt": "Kitten slowly opens its eyes, ears gently twitch, camera slowly pushes in",
    "duration": 10,
    "resolution": "1080p",
    "smart_rewrite": false,
    "generate_audio": false,
    "audio_url": "https://example.com/audio.mp3",
    "image": "data:image/png;base64,iVBORw0KGgoAAxxxx...",
    "seed": 789012
  }'

1. Text-to-Video (T2V, Basic Example)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-t2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A cute kitten playing in a garden, sunny day --ratio 16:9 --dur 5 --rs 720p --wm false"
        }
      ]
    }
  }'

2. Text-to-Video (T2V, Full Parameters)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-t2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A cute kitten playing in a garden, sunny day --ratio 9:16 --dur 10 --rs 1080p --fps 30 --wm true --seed 12345"
        }
      ]
    }
  }'

3. Image-to-Video (First Frame Mode)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A girl opens her eyes and looks gently at the camera --ratio adaptive --dur 5 --rs 720p --wm false"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
          }
        }
      ]
    }
  }'

4. Image-to-Video (First/Last Frame Mode, only lite-i2v supports)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A blue-green jingwei bird transforms into human form --rs 720p --dur 5 --fps 24 --cf false --wm false --seed 67890"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
          },
          "role": "first_frame"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAyyyy..."
          },
          "role": "last_frame"
        }
      ]
    }
  }'

5. Image-to-Video (Reference Image Mode, only lite-i2v supports)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "[图1] A boy wearing glasses and blue T-shirt and [图2] corgi dog, sitting on [图3] lawn, 3D cartoon style --rs 720p --dur 5 --ratio 16:9 --wm false"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/ref1.png"
          },
          "role": "reference_image"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/ref2.png"
          },
          "role": "reference_image"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/ref3.png"
          },
          "role": "reference_image"
        }
      ]
    }
  }'

6. Pro Model (First Frame Mode)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A girl opens her eyes and looks gently at the camera --ratio 16:9 --dur 5 --rs 1080p --wm false"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
          }
        }
      ]
    }
  }'

7. 1.5 Pro Model (Text-to-Video, with Audio)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-5-pro-251215",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A cute kitten playing in a sunny garden, gentle breeze --ratio 16:9 --dur 6 --rs 720p --wm false"
        }
      ],
      "return_last_frame": true,
      "callback_url": "https://your-domain.com/callback"
    }
  }'

8. 1.5 Pro Model (Image-to-Video First/Last Frame, Silent)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-5-pro-251215-noAudio",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "Transition from static scene to dynamic motion --ratio 9:16 --dur 8 --rs 480p --wm false --seed 12345"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
          },
          "role": "first_frame"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAyyyy..."
          },
          "role": "last_frame"
        }
      ],
      "return_last_frame": true
    }
  }'

Response Example

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "submitted",
  "format": "mp4"
}

Request Parameters

model

string

required

Model identifier, supported models and features:Sora 2 Series:

sora-2 - Supports text-to-video, image-to-video, video-to-video (Remix mode)

Google Veo Series:

veo-3.0-fast-generate-001 - Text-to-video (first frame mode)
veo-3.1-fast-generate-preview - Text-to-video (first frame mode, first/last frame mode)

Ali Wanxiang Series:

wan2.5-t2v-preview - Text-to-video
wan2.5-i2v-preview - Image-to-video (first frame mode)

Doubao Seedance Series:

doubao-seedance-1-0-lite-t2v-250428 - Text-to-video
doubao-seedance-1-0-lite-i2v-250428 - Image-to-video (first frame mode, first/last frame mode, reference image mode)
doubao-seedance-1-0-pro-250528 - Text-to-video (first frame mode)
doubao-seedance-1-5-pro-251215 - Text-to-video, Image-to-video (first frame mode, first/last frame mode), with audio, duration 4-12s, resolution 480p/720p
doubao-seedance-1-5-pro-251215-noAudio - Text-to-video, Image-to-video (first frame mode, first/last frame mode), silent video, duration 4-12s, resolution 480p/720p

prompt

string

Video generation prompt, describing scene actions and settings. Note: Doubao Seedance series models do not require this field, the prompt should be written directly in the text field of the metadata.content array

image

string

Reference image for image-to-video (supports Base64 or URL format)

duration

integer

default:"5"

Video duration (seconds), different models support different durations

resolution

string

default:"720p"

Video resolution: 480p, 720p, 1080p, 4k

aspect_ratio

string

default:"16:9"

Aspect ratio: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, adaptive (adaptive, only supported by some models)

Model-Specific Parameters

Different models support different specific parameters. Below are detailed descriptions by model series:

Sora 2
Veo
Ali Wanxiang
Doubao Seedance

seconds

string|integer

default:"4"

Video duration (seconds), supports: 4, 8, 12

size

string

default:"720x1280"

Video resolution, supports: 720x1280 (portrait), 1280x720 (landscape)

input_reference

string

Reference image (supports URL or Base64 format), for image-to-video

remix_from_video_id

string

Remix mode: Regenerate based on existing video ID (must start with video_)

durationSeconds

integer

default:"4"

Video duration (seconds), supports: 4, 6, 8

aspectRatio

string

default:"16:9"

Aspect ratio, only supports: 16:9, 9:16

resolution

string

default:"1080p"

Resolution, supports: 720p, 1080p

fps

integer

default:"24"

Frame rate, default 24

image

string

First frame reference image (supports URL or Base64 format)

lastFrame

string

Last frame reference image (supports URL or Base64 format), only veo-3.1 series supports

generateAudio

boolean

default:"false"

Whether to generate synchronized audio. Fast models ignore this parameter and always include audio

personGeneration

string

default:"allow_all"

Person generation strategy: allow_all (all ages), allow_adult (adults only), dont_allow (no persons)

addWatermark

boolean

default:"false"

Whether to add watermark

seed

integer

Random seed for reproducing results

sampleCount

integer

default:"1"

Number of videos to generate per request, range: 1-4

duration

integer

default:"5"

Video duration (seconds), supports: 5, 10

resolution

string

default:"720p"

Video resolution, supports: 480p, 720p, 1080p

size

string

Video size (t2v mode only), format: width*height, e.g. 1280*720

smart_rewrite

boolean

default:"false"

Whether to enable intelligent prompt expansion

generate_audio

boolean

default:"false"

Whether to generate synchronized audio with video

audio_url

string

Custom audio file URL (HTTPS format)

seed

integer

Random seed, range: 0-2147483647

metadata.content

array

required

Content array, must be placed in the metadata object. Must include text and optional images. Parameters are controlled through special markers in text prompts:

--rs or --resolution: Resolution (480p, 720p, 1080p)
--ratio: Aspect ratio (16:9, 9:16, 1:1, 4:3, 3:4, adaptive, note that doubao-seedance-1-0-lite-t2v-250428 does not support adaptive)
--dur or --duration: Duration (seconds, e.g. 5, 10)
--fps or --framespersecond: Frame rate (e.g. 24, 30)
--seed: Random seed
--wm or --watermark: Watermark toggle (true, false)
--cf or --camerafixed: Fixed camera (true, false, only lite models support)

1.5 Pro Series Limitations:

Duration: 4-12 seconds
Resolution: 480p, 720p only
Generation modes: Text-to-video, First frame mode, First/last frame mode

metadata.content array format:

{
  "metadata": {
    "content": [
      {
        "type": "text",
        "text": "Prompt content --ratio 16:9 --dur 5 --rs 720p --wm false"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "data:image/png;base64,..."
        },
        "role": "first_frame"  // Optional: first_frame, last_frame, reference_image
      }
    ],
    "return_last_frame": true,  // Whether to return last frame (1.5 Pro series)
    "callback_url": "https://your-domain.com/callback"  // Optional callback URL
  }
}

Complete Examples

Doubao Seedance Series

Doubao Seedance series models use a special parameter passing method: all parameters are passed through special markers in the prompt, and images are passed through the metadata.content array.

1. Text-to-Video (T2V)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-t2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A cute kitten playing in a garden, sunny day --ratio 16:9 --dur 5 --rs 720p --wm false"
        }
      ]
    }
  }'

2. Image-to-Video - First Frame Mode

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A girl opens her eyes and looks gently at the camera --ratio adaptive --dur 5 --rs 720p --wm false"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
          }
        }
      ]
    }
  }'

3. Image-to-Video - First/Last Frame Mode (Only lite-i2v supports)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A blue-green jingwei bird transforms into human form --rs 720p --dur 5 --cf false"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAxxxx..."
          },
          "role": "first_frame"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,iVBORw0KGgoAAyyyy..."
          },
          "role": "last_frame"
        }
      ]
    }
  }'

4. Image-to-Video - Reference Image Mode (Only lite-i2v supports)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "[图1] A boy wearing glasses and blue T-shirt and [图2] corgi dog, sitting on [图3] lawn, 3D cartoon style --rs 720p --dur 5"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/ref1.png"
          },
          "role": "reference_image"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/ref2.png"
          },
          "role": "reference_image"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/ref3.png"
          },
          "role": "reference_image"
        }
      ]
    }
  }'

Important Notes:

The content array must be placed in the metadata object
All parameters must be passed through special markers in the prompt (e.g., --ratio 16:9)
Images must be placed in the metadata.content array using image_url type
First/last frame mode requires two images, marked with role: "first_frame" and role: "last_frame" respectively
Reference image mode requires using [图1], [图2] etc. in the prompt to reference images, with images marked role: "reference_image"
doubao-seedance-1-0-lite-t2v-250428 does not support image input and adaptive aspect ratio
doubao-seedance-1-0-pro-250528 only supports first frame mode

Sora 2 Complete Example
Veo Complete Example
Ali Wanxiang Complete Example
Doubao Seedance Complete Example

1. Submit Video Generation Task

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cute kitten playing in a garden, sunny day, warm scene",
    "seconds": "4",
    "size": "720x1280"
  }'

Response Example:

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "submitted",
  "format": "mp4"
}

2. Poll Task Status

curl -X GET "https://api.gravitex.ai/v1/video/generations/video_69095b4ce0048190893a01510c0c98b0" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"

Task Status Description:

Status	Description	Recommended Action
`queued`	Task queued, waiting for processing	Continue polling
`in_progress`	Task processing	Continue polling
`succeeded`	Task completed successfully	Download video
`failed`	Task failed	Check failure reason

Response Example (Queued):

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "queued",
  "format": "mp4"
}

Response Example (Processing):

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "in_progress",
  "format": "mp4"
}

Response Example (Completed):

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "succeeded",
  "format": "mp4"
}

Response Example (Failed):

{
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "status": "failed",
  "format": "mp4",
  "error": {
    "code": 400,
    "message": "Prompt contains inappropriate content"
  }
}

Important Note:

When task status is queued or in_progress, you need to poll regularly (recommended every 3-5 seconds)
When status becomes succeeded, you can use task_id as videoId to download the video
When status becomes failed, you can check the error field for failure reason

3. Download Video (Sora 2 Exclusive)

Use the task_id returned after successful polling (as videoId) to download the video:

curl -X GET "https://api.gravitex.ai/v1/video/generations/download?id=video_69095b4ce0048190893a01510c0c98b0" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"

Note: The value of the id parameter is the task_id returned after successful polling in step 2.Response Example:

{
  "success": true,
  "generation_id": "video_69095b4ce0048190893a01510c0c98b0",
  "task_id": "video_69095b4ce0048190893a01510c0c98b0",
  "format": "mp4",
  "size": 15728640,
  "base64": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB...",
  "data_url": "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQAAB..."
}

Response Field Description:

Field Name	Type	Description
`success`	boolean	Whether successful
`generation_id`	string	Generation ID (same as videoId)
`task_id`	string	Task ID
`format`	string	Video format (fixed as `"mp4"`)
`size`	number	Video file size (bytes)
`base64`	string	Base64-encoded video data
`data_url`	string	Video data in Data URL format, can be directly used in frontend `<video>` tag

1. Submit Video Generation Task

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "Aerial view of a sci-fi city at dawn, sunlight piercing through clouds",
    "durationSeconds": 8,
    "aspectRatio": "16:9",
    "resolution": "1080p",
    "generateAudio": true,
    "image": "https://example.com/start-frame.png",
    "lastFrame": "https://example.com/end-frame.png"
  }'

Response Example:

{
  "task_id": "video_1234567890abcdef",
  "status": "submitted",
  "format": "mp4"
}

2. Poll Task Status

curl -X GET "https://api.gravitex.ai/v1/video/generations/video_1234567890abcdef" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"

Response Example (Completed):

{
  "task_id": "video_1234567890abcdef",
  "status": "succeeded",
  "format": "mp4",
  "url": "https://gravitex-ads.oss-cn-guangzhou.aliyuncs.com/2025/11/18/abc123/veo-demo-1.mp4"
}

Note: For Veo and Ali Wanxiang, when the task succeeds, the video URL is directly included in the response, no additional download step is needed.

1. Submit Video Generation Task

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.5-i2v-preview",
    "prompt": "A kitten slowly opens its eyes, ears gently twitch, camera slowly pushes in",
    "image": "https://example.com/cat.jpg",
    "duration": 5,
    "resolution": "720p",
    "smart_rewrite": true,
    "generate_audio": true
  }'

Response Example:

{
  "task_id": "ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97",
  "status": "submitted",
  "format": "mp4"
}

2. Poll Task Status

curl -X GET "https://api.gravitex.ai/v1/video/generations/ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"

Response Example (Completed):

{
  "task_id": "ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97",
  "status": "succeeded",
  "format": "mp4",
  "url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/.../video.mp4?Expires=..."
}

1. Text-to-Video (T2V)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "Multiple shots. A detective enters a dimly lit room. He examines clues on the table, picks up an item. Camera turns to him thinking. --ratio 16:9 --dur 5"
        }
      ]
    }
  }'

2. Image-to-Video - First Frame Mode (I2V)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A girl holding a fox, the girl opens her eyes, looks gently at the camera, the fox hugs friendly, camera slowly pulls out, the girl'\''s hair is blown by the wind --ratio adaptive --dur 5"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/first-frame.png"
          }
        }
      ]
    }
  }'

3. Image-to-Video - First/Last Frame Mode (Only lite-i2v supports)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "A blue-green jingwei bird transforms into human form --rs 720p --dur 5 --cf false"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/first-frame.png"
          },
          "role": "first_frame"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/last-frame.png"
          },
          "role": "last_frame"
        }
      ]
    }
  }'

4. Image-to-Video - Reference Image Mode (Only lite-i2v supports)

curl -X POST "https://api.gravitex.ai/v1/video/generations" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-lite-i2v-250428",
    "metadata": {
      "content": [
        {
          "type": "text",
          "text": "[图1] A boy wearing glasses and blue T-shirt and [图2] corgi dog, sitting on [图3] lawn, 3D cartoon style"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/ref1.png"
          },
          "role": "reference_image"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/ref2.png"
          },
          "role": "reference_image"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/ref3.png"
          },
          "role": "reference_image"
        }
      ]
    }
  }'

Response Example:

{
  "task_id": "cgt-2025123456-abcd",
  "status": "submitted",
  "format": "mp4"
}

5. Poll Task Status

curl -X GET "https://api.gravitex.ai/v1/video/generations/cgt-2025123456-abcd" \
  -H "Authorization: Bearer sk-xxxxxxxxxx"

Response Example (Completed):

{
  "task_id": "cgt-2025123456-abcd",
  "status": "succeeded",
  "format": "mp4",
  "url": "https://ark-content-generation-cn-beijing.tos-cn-beijing.volces.com/.../video.mp4?X-Tos-Algorithm=..."
}

Supported Models

Sora 2 Series

Model Name: sora-2 Core Capabilities:

✅ Text-to-video (pure text description generates video)
✅ Image-to-video (single image + text generates video)
✅ Remix mode (regenerate based on existing video)

Supported Parameters:

seconds: Video duration (4, 8, 12 seconds), default 4 seconds
size: Video resolution (720x1280 portrait, 1280x720 landscape), default 720x1280
width / height: Video width and height (automatically converted to size parameter)
input_reference: Reference image (supports URL or Base64 format), for image-to-video
remix_from_video_id: Remix mode, regenerate based on existing video ID (must start with video_)

Notes:

Video generation is an asynchronous task, need to first submit task to get task_id, then poll task status
When task status is succeeded, use task_id as videoId to call download interface to get video
Download interface returns Base64-encoded video data, can be directly used for frontend playback or saved as file
Image input formats support JPEG, PNG, image size must exactly match size parameter for image-to-video

Veo Series

Model Names: veo-3.1-generate-preview, veo-3.1-fast-generate-preview, veo-3.0-generate-preview, veo-3.0-fast-generate-001 Core Capabilities:

✅ Text-to-video
✅ Image-to-video (supports first frame and last frame constraints)
✅ Audio generation

Supported Parameters:

durationSeconds: Video duration (4, 6, 8 seconds)
aspectRatio: Aspect ratio (16:9, 9:16)
resolution: Resolution (720p, 1080p)
generateAudio: Whether to generate audio
image: First frame reference image
lastFrame: Last frame reference image
seed: Random seed

Ali Wanxiang Series

Model Name: wan2.5-i2v-preview Core Capabilities:

✅ Image-to-video
✅ Supports custom audio upload
✅ Intelligent prompt expansion
✅ Auto-generate synchronized audio with video

Supported Parameters:

duration: Video duration (5, 10 seconds)
resolution: Video resolution (480p, 720p, 1080p)
smart_rewrite: Whether to enable intelligent prompt expansion
generate_audio: Whether to generate synchronized audio with video
audio_url: Custom audio file URL
seed: Random seed

Doubao Seedance Series

Model Names:

doubao-seedance-1-0-pro-250528 - Pro version, supports text-to-video and image-to-video (first frame mode)
doubao-seedance-1-0-lite-t2v-250428 - Lite version text-to-video
doubao-seedance-1-0-lite-i2v-250428 - Lite version image-to-video, supports first frame, first/last frame, reference image three modes
doubao-seaweed-1-0-t2v-250428 - Seaweed version text-to-video
wan2-1-14b-i2v-250417 - Wanxiang version image-to-video
wan2-1-14b-flf2v-250417 - Wanxiang version first/last frame generation

Core Capabilities:

✅ Text-to-video (T2V)
✅ Image-to-video - First frame mode (I2V)
✅ Image-to-video - First/last frame mode (only doubao-seedance-1-0-lite-i2v-250428 and wan2-1-14b-flf2v-250417 support)
✅ Image-to-video - Reference image mode (only doubao-seedance-1-0-lite-i2v-250428 supports)

Supported Parameters (controlled through special markers in text prompts):

--rs / --resolution: Resolution (480p, 720p, 1080p)
--ratio: Aspect ratio (16:9, 9:16, 1:1, 4:3, 3:4, adaptive)
--dur / --duration: Duration (seconds, e.g. 5, 10)
--fps / --framespersecond: Frame rate (e.g. 24, 30)
--seed: Random seed
--wm / --watermark: Watermark toggle (true, false)
--cf / --camerafixed: Fixed camera (true, false, only lite models support)

Image Input Format:

In metadata.content array, image items can be marked via role field:
- first_frame: First frame image
- last_frame: Last frame image
- reference_image: Reference image (use [图N] in prompt to reference)

Notes:

doubao-seedance-1-0-lite-t2v-250428 only supports text-to-video, does not support image input
Reference image mode of doubao-seedance-1-0-lite-i2v-250428 does not support 1080p resolution
doubao-seedance-1-0-lite-t2v-250428 does not support adaptive aspect ratio

Best Practices

Polling Strategy

Python Polling Example
JavaScript Polling Example

import requests
import time

def poll_task_status(task_id, api_key, max_wait_time=300):
    """Poll task status until completion"""
    url = f"https://api.gravitex.ai/v1/video/generations/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    start_time = time.time()
    while True:
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")
        
        print(f"Current status: {status}")
        
        if status == "succeeded":
            video_url = data.get("url")
            print(f"✅ Task completed! Video URL: {video_url}")
            return video_url
        elif status == "failed":
            error_msg = data.get("metadata", {}).get("output", {}).get("message", "Unknown error")
            print(f"❌ Task failed: {error_msg}")
            return None
        
        # Check timeout
        if time.time() - start_time > max_wait_time:
            print("⏰ Wait timeout")
            return None
        
        # Wait 5 seconds before querying again
        time.sleep(5)

async function pollTaskStatus(taskId, apiKey, maxWaitTime = 300000) {
  const url = `https://api.gravitex.ai/v1/video/generations/${taskId}`;
  const headers = { 'Authorization': `Bearer ${apiKey}` };
  
  const startTime = Date.now();
  
  while (true) {
    const response = await fetch(url, { headers });
    const data = await response.json();
    const status = data.status;
    
    console.log(`Current status: ${status}`);
    
    if (status === 'succeeded') {
      const videoUrl = data.url;
      console.log(`✅ Task completed! Video URL: ${videoUrl}`);
      return videoUrl;
    } else if (status === 'failed') {
      const errorMsg = data.metadata?.output?.message || 'Unknown error';
      console.error(`❌ Task failed: ${errorMsg}`);
      throw new Error(errorMsg);
    }
    
    // Check timeout
    if (Date.now() - startTime > maxWaitTime) {
      throw new Error('Wait timeout');
    }
    
    // Wait 5 seconds before querying again
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

FAQ

General Questions
Sora 2
Veo
Ali Wanxiang
Doubao Seedance

How long does video generation take?

Usually takes 1-5 minutes, depending on video duration, resolution, and server load.

How long are generated videos valid?

Video URLs are valid for approximately 24 hours. It is recommended to download and save immediately after receiving the response.

What image input formats are supported?

Supports PNG, JPEG, JPG, WEBP formats, maximum file size 10MB.

What video durations are supported?

Supports 4 seconds, 6 seconds, and 8 seconds.

How to generate audio?

Set generateAudio: true parameter, system will automatically generate synchronized audio with video.

What video durations are supported?

Supports 5 seconds and 10 seconds.

How to upload custom audio?

Provide audio_url parameter, pointing to a publicly accessible audio file URL.

How to set video parameters?

Doubao Seedance model parameters are controlled through special markers in text prompts, for example: --rs 720p --ratio 16:9 --dur 5 --fps 24 --seed 12345

What image-to-video modes are supported?

First Frame Mode: Supported by all models that support image-to-video
First/Last Frame Mode: Only doubao-seedance-1-0-lite-i2v-250428 and wan2-1-14b-flf2v-250417 support
Reference Image Mode: Only doubao-seedance-1-0-lite-i2v-250428 supports, can use [图1], [图2] etc. in prompt to reference multiple reference images

How to configure callback notification?

Set callback_url field in metadata, task status changes will automatically push results to that URL.

What aspect ratios are supported?

Most models support 16:9, 9:16, 1:1, 4:3, 3:4, adaptive (adaptive). Note that doubao-seedance-1-0-lite-t2v-250428 does not support adaptive.

Image Generation

View image generation API documentation

Model List

View all supported model information

Documentation Index

​Introduction

​Supported Models and Features

​Authentication

​API Endpoints

​Submit Video Task

​Query Video Task

​Path Parameters

​Response Examples

​Usage Example

​Download Video

​Query Parameters

​Response Example

​Usage Example

​Submit Video Task

​Usage Examples

​Response Example

​Request Parameters

​Model-Specific Parameters

​Complete Examples

​Doubao Seedance Series

​1. Text-to-Video (T2V)

​2. Image-to-Video - First Frame Mode

​3. Image-to-Video - First/Last Frame Mode (Only lite-i2v supports)

​4. Image-to-Video - Reference Image Mode (Only lite-i2v supports)

​1. Submit Video Generation Task

​2. Poll Task Status

​3. Download Video (Sora 2 Exclusive)

​1. Submit Video Generation Task

​2. Poll Task Status

​1. Submit Video Generation Task

​2. Poll Task Status

​1. Text-to-Video (T2V)

​2. Image-to-Video - First Frame Mode (I2V)

​3. Image-to-Video - First/Last Frame Mode (Only lite-i2v supports)

​4. Image-to-Video - Reference Image Mode (Only lite-i2v supports)

​5. Poll Task Status

​Supported Models

​Sora 2 Series

​Veo Series

​Ali Wanxiang Series

​Doubao Seedance Series

​Best Practices

​Polling Strategy

​FAQ

​Related Resources

Image Generation

Model List

Introduction

Supported Models and Features

Authentication

API Endpoints

Submit Video Task

Query Video Task

Path Parameters

Response Examples

Usage Example

Download Video

Query Parameters

Response Example

Usage Example

Submit Video Task

Usage Examples

Response Example

Request Parameters

Model-Specific Parameters

Complete Examples

Doubao Seedance Series

1. Text-to-Video (T2V)

2. Image-to-Video - First Frame Mode

3. Image-to-Video - First/Last Frame Mode (Only lite-i2v supports)

4. Image-to-Video - Reference Image Mode (Only lite-i2v supports)

1. Submit Video Generation Task

2. Poll Task Status

3. Download Video (Sora 2 Exclusive)

1. Submit Video Generation Task

2. Poll Task Status

1. Submit Video Generation Task

2. Poll Task Status

1. Text-to-Video (T2V)

2. Image-to-Video - First Frame Mode (I2V)

3. Image-to-Video - First/Last Frame Mode (Only lite-i2v supports)

4. Image-to-Video - Reference Image Mode (Only lite-i2v supports)

5. Poll Task Status

Supported Models

Sora 2 Series

Veo Series

Ali Wanxiang Series

Doubao Seedance Series

Best Practices

Polling Strategy

FAQ

Related Resources