Model ID

skyreels-v4-omni

Calling method: async

skyreels-v4-omni API Usage Guide

Overview

skyreels-v4-omni is the V4 reference-driven generation/editing model. Unlike skyreels-v4-text-to-video, Omni requires references and supports workflows such as:

keyframe-guided generation
subject/background replacement
motion/style transfer from reference video
local edits and object insertion/removal

Important: at least one of ref_images or ref_videos must be provided, otherwise upstream returns 422 (At least one reference must be provided).

Authentication

All Request Queue API requests require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Provider-side SkyReels credentials are injected by backend config.

Submit Omni Request

Base URL

https://console.gmicloud.ai

Endpoint

POST /api/v1/ie/requestqueue/apikey/requests

Example (image references)

curl -X POST "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "skyreels-v4-omni",
    "payload": {
      "prompt": "Use @subject1 as the main character and animate @keyframe1 into a cinematic shot",
      "duration": 5,
      "aspect_ratio": "16:9",
      "sound": false,
      "mode": "std",
      "ref_images": [
        {
          "tag": "@subject1",
          "type": "subject",
          "image_urls": ["https://example.com/subject.png"]
        },
        {
          "tag": "@keyframe1",
          "type": "keyframe",
          "time_stamp": 0,
          "image_urls": ["https://example.com/frame0.png"]
        }
      ]
    }
  }'

Example (video reference)

curl -X POST "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "skyreels-v4-omni",
    "payload": {
      "prompt": "Transfer camera motion from @video1 while preserving the subject style",
      "mode": "std",
      "ref_videos": [
        {
          "tag": "@video1",
          "type": "reference",
          "video_url": "https://example.com/ref.mp4"
        }
      ]
    }
  }'

Request Parameters

Parameter	Type	Required	Description	Default	Constraints
`model`	string	Yes	Model identifier	-	Must be `"skyreels-v4-omni"`
`payload.prompt`	string	Yes	Prompt text; tags in refs must appear in prompt	-	Max ~1280 tokens
`payload.feature_mode`	string (enum)	No	UI/workflow hint only; not forwarded upstream	`image_reference`	`image_reference`, `video_reference`, `editing`
`payload.duration`	integer	No	Output duration in seconds	5	3-15; removed when `ref_videos` exists
`payload.aspect_ratio`	string (enum)	No	Output ratio	`16:9`	`16:9`, `4:3`, `1:1`, `9:16`, `3:4`; ignored with `ref_videos`
`payload.ref_images`	json array	No	Image reference objects (`tag`, `type`, `image_urls`, optional `time_stamp`)	-	At least one ref required if no `ref_videos`; subject refs max 4
`payload.ref_videos`	json array	No	Video reference objects (`tag`, `type`, `video_url`)	-	Max one reference video, max ~10s
`payload.sound`	boolean	No	Enable sound effects	false	Not effective in some video-reference scenarios
`payload.prompt_optimizer`	boolean	No	Auto prompt refinement	true	Optional
`payload.mode`	string (enum)	No	Quality/perf mode	`std`	Documented `fast`, `std`, `pro`; currently only `std` is supported

Response (Request Accepted)

{
  "request_id": "660f9500-f30c-52e5-b827-557766550000",
  "model": "skyreels-v4-omni",
  "status": "queued",
  "created_at": 1750442925,
  "updated_at": 1750442925,
  "queued_at": 1750442925
}

Check Request Status

Endpoint

GET /api/v1/ie/requestqueue/apikey/requests/{request_id}

Example

curl -X GET "https://console.gmicloud.ai/api/v1/ie/requestqueue/apikey/requests/660f9500-f30c-52e5-b827-557766550000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success Response Example

{
  "request_id": "660f9500-f30c-52e5-b827-557766550000",
  "model": "skyreels-v4-omni",
  "status": "success",
  "outcome": {
    "video_url": "https://storage.googleapis.com/your-bucket/generated-video.mp4",
    "thumbnail_image_url": "https://storage.googleapis.com/your-bucket/generated-thumbnail.jpg",
    "duration": 5,
    "resolution": "1920x1080"
  }
}

Request Status Values

Status	Description
`queued`	Request is waiting to be processed
`processing`	Generation is in progress
`success`	Generation completed successfully
`failed`	Generation failed
`cancelled`	Request was cancelled

Routing and Endpoint Notes

Provider endpoint used by this model:

Submit: POST https://api-gateway.skyreels.ai/api/v1/video/omni-video/submit
Query: GET https://api-gateway.skyreels.ai/api/v1/video/omni-video/task/{task_id}

Prompt-only generation should use skyreels-v4-text-to-video instead of Omni.

Overview

Model Quickstarts

Agents

Coding Tools

AgentBox Guides

Migration Guides

skyreels-v4-omni

skyreels-v4-omni API Usage Guide

Overview

Authentication

Submit Omni Request

Base URL

Endpoint

Example (image references)

Example (video reference)

Request Parameters

Response (Request Accepted)

Check Request Status

Endpoint

Example

Success Response Example

Request Status Values

Routing and Endpoint Notes

​skyreels-v4-omni API Usage Guide

​Overview

​Authentication

​Submit Omni Request

​Base URL

​Endpoint

​Example (image references)

​Example (video reference)

​Request Parameters

​Response (Request Accepted)

​Check Request Status

​Endpoint

​Example

​Success Response Example

​Request Status Values

​Routing and Endpoint Notes

skyreels-v4-omni API Usage Guide

Overview

Authentication

Submit Omni Request

Base URL

Endpoint

Example (image references)

Example (video reference)

Request Parameters

Response (Request Accepted)

Check Request Status

Endpoint

Example

Success Response Example

Request Status Values

Routing and Endpoint Notes