StarVideos O3: Create Video Task (Text, Image, Frame Modes)

POST /v1/starvideos/videos — Generate 3–15s videos with starvideos_o3. Supports text, multi-image reference, first/last frame, and video reference.

Submit an asynchronous video generation task using the starvideos_o3 model. The endpoint returns a task id immediately — you then poll the Query Video Task endpoint until the task completes. StarVideos O3 supports a rich set of generation modes: pure text-to-video, single or multi-image reference, first/last frame guidance, video reference, and combined image + video reference.

Base URL

https://zcbservice.aizfw.cn/kyyReactApiServer

Endpoint

POST /v1/starvideos/videos

Authentication

Authorization: Bearer YOUR_API_KEY

Model

This endpoint supports a single model:

Model	Duration	Aspect Ratios	Notes
starvideos_o3	3–15s (default 3s)	9:16, 1:1, 16:9	Multi-mode: text, image ref, first/last frame, video ref

Request Parameters

model · string · required

Model name. Must be starvideos_o3.

prompt · string · required

Text description of the video content, including subject, action, camera movement, and visual style.

Example: "Cyberpunk cityscape at night, camera slowly pushing forward"

duration · integer

Output video duration in seconds. Applies to text-to-video, image reference, and first/last frame modes.

• Default: 3
• Supported range: 3–15 seconds

When using referenceVideos (video reference, image + video, or multi-image + video modes), the output duration and aspect ratio are determined by the reference video — this field is ignored.

ratio · string

Output aspect ratio. Applies to text-to-video, image reference, and first/last frame modes.

• Default: 9:16
• Supported values: 9:16, 1:1, 16:9

When using referenceVideos, the aspect ratio follows the reference video’s dimensions — this field is ignored.

Image Reference Parameters

referenceImages · array

Array of image reference URLs. Used in image reference mode and combined image + video reference mode.

Constraints:

• Image reference only (no video): up to 7 images
• Combined with referenceVideos: up to 4 images

Example: ["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"]

First / Last Frame Parameters

first_image · string

URL of the first-frame image. For first/last frame mode — must be used together with last_image.

Cannot be combined with referenceImages or referenceVideos.

last_image · string

URL of the last-frame image. For first/last frame mode — must be used together with first_image.

Cannot be combined with referenceImages or referenceVideos.

Video Reference Parameters

referenceVideos · array

Array of reference video URLs. Enables video reference mode. Maximum 1 video.

• Reference video duration must be 3–10 seconds
• When provided, output duration and ratio follow the reference video
• Can be combined with referenceImages (up to 4 images)

Example: ["https://example.com/reference.mp4"]

first_image / last_image are mutually exclusive with referenceImages and referenceVideos. You cannot mix first/last frame mode with reference media mode in the same request.

Generation Modes

StarVideos O3 supports the following mutually exclusive modes:

Mode	Required Fields	Optional Fields
Text-to-video	model, prompt	duration, ratio
Image reference	model, prompt, referenceImages (1–7)	duration, ratio
First/last frame	model, prompt, first_image, last_image	duration, ratio
Video reference	model, prompt, referenceVideos (1 video)	— duration/ratio from video
Image + Video	model, prompt, referenceImages (1–4), referenceVideos (1)	— duration/ratio from video

Response Fields

id · string

Unique task identifier. Save this value — you’ll use it to poll the Query Video Task endpoint.

object · string

Object type. Always "video".

created · integer

Unix timestamp of when the task was created.

model · string

The model name used for this task. Always "starvideos_o3".

status · string

Task status at creation. Always "queued" on successful submission.

Lifecycle values:

• queued — task accepted and waiting in queue
• processing — model is actively generating
• completed — generation finished; video_url is available
• failed — generation failed; see error

error · string

Error message. null on successful submission.

Code Examples

cURL (Text-to-Video)

curl --request POST \
  --url https://zcbservice.aizfw.cn/kyyReactApiServer/v1/starvideos/videos \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "starvideos_o3",
    "prompt": "Cyberpunk cityscape at night, camera slowly pushing forward",
    "duration": 5,
    "ratio": "16:9"
  }'

Example Response

{
  "id": "video_starvideos_o3_1234567890",
  "object": "video",
  "created": 1774836724,
  "model": "starvideos_o3",
  "status": "queued",
  "error": null
}

Next Steps

After receiving the task id, poll the Query Video Task endpoint to check status and retrieve video_url when generation completes.