# Omni reference

## 1. Task Submission

- https://api-gateway.skyreels.ai/api/v1/video/omni-video/submit

Request Parameters
Parameter Name Type Required Description Default Value Constraints
api_key string Yes Used for account authentication and rate limiting. N/A -
prompt string Yes The prompt describing the video to generate. N/A Max length: 1280 tokens.
aspect_ratio string No Aspect ratio of the generated video. 16:9 Supported values: '16:9', '4:3', '1:1', '9:16', '3:4'. Note: This parameter is ignored if ref_videos is provided, as the output dimensions will automatically align with the reference video.
duration int No Duration of the generated video. 5 Duration range: 3–15 seconds. Note: This parameter is overridden if ref_videos is provided; in such cases, the output duration will match the reference video (up to 10 seconds).
ref_images List[ReferenceImage] No List of reference images (Subject, Scene, Style, Keyframes, etc.). See ReferenceImage details below. N/A Max 4 subject references
ref_videos List[ReferenceVideo] No List of reference video configurations. See ReferenceVideo details below. N/A ref_videos supports only a single video reference (max 10s).
sound bool No Whether the generated video includes sound effects. False When using video reference, the sound is not effective; no audio by default.
prompt_optimizer bool No Enables automatic prompt expansion and refinement to achieve higher visual fidelity and alignment. True -
mode string No The quality/performance mode. std Supported values: "fast", "std", and "pro". "fast" offers faster generation, "std" balances speed and quality, and "pro" delivers higher quality. All modes output at 1080p. Currently, only "std" is supported; "fast" and "pro" support will be added later.
Reference Object Definitions
ReferenceImage Type
Parameter Name Type Required Description Constraints
tag string Yes Identifier for the reference group. Must start with @ and appear in the prompt, such as @subject1, @image1, etc.
type string Yes Type of image reference. keyframe: Used for keyframe reference tasks. Works with the time_stamp field to display a specific reference image at a designated time in the video.
image_urls List[str] Yes List of image URLs. keyframe: 1 image
time_stamp int No Target timestamp for the reference (applies only to keyframe). e.g., 0 for the first frame; duration for the last frame.
ReferenceVideo Type
Parameter Name Type Required Description Constraints
tag string Yes Identifier for the video reference. Must start with @ and appear in the prompt, such as @video1, etc.
type string Yes Type of video reference. reference: Used for video reference tasks, e.g., motion reference.
video_url string Yes The video URL. Supports MP4, MOV. Max 10s.
Response Parameters
Field Name Type Description
task_id string The task ID, used for subsequent queries.
msg string A message describing the result.
code int Status code (200 for success, 422 for parameter error, 500 for server error).
status string Status identifier ("ok" indicates success).
data object Response data, null on successful submission.
trace_id string Request trace ID.
Request Example

1. Keyframe Video Generation
   curl -X POST "https://api-gateway.skyreels.ai/api/v1/video/omni-video/submit" -H "Content-Type: application/json" -d '{
   "api_key": "YOUR_API_KEY",
   "prompt": "The King @image1 anxiously searched for the destination on the map, suddenly made a surprise discovery, ran out of the door, and summoned a flying dragon. The dragon lowered its body @image2, the King mounted it, and the dragon took off. The King rode the dragon forward, flying over a village @image3.",
   "duration": 5,
   "aspect_ratio": "16:9",
   "ref_images": [
   {
   "tag": "@image1",
   "type": "keyframe",
   "image_urls": ["http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/2015_k2v_0.png"],
   "time_stamp": 0
   },
   {
   "tag": "@image2",
   "type": "keyframe",
   "image_urls": ["http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/2015_k2v_1.png"],
   "time_stamp": 2
   },
   {
   "tag": "@image3",
   "type": "keyframe",
   "image_urls": ["http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/2015_k2v_2.png"],
   "time_stamp": 5
   }
   ],
   "sound": false,
   "prompt_optimizer": true,
   "mode": "std"
   }'

2. Multi-subject Reference Video Generation
   curl -X POST "https://api-gateway.skyreels.ai/api/v1/video/omni-video/submit" -H "Content-Type: application/json" -d '{
   "api_key": "YOUR_API_KEY",
   "prompt": "Captured in a gritty anime style, this sequence reveals @Actor-1 caught in a moment of intense physical suffering. <bgm>A low, resonant ambient drone plays in the background, creating an atmosphere of deep unease and tension</bgm>. @Actor-1 says with a strained and pained voice, <dialogue>好痛，超痛的</dialogue><voice_ref>行くな！今がその時だろう。我が息子が怪人に连れ去られたんだぞ！あれから24时间が経とうとしているのに、まだ突入せんとは何事だ！ </voice_ref>. As he continues to grimace against a background of purple haze, he adds, <dialogue>全身上下都很痛</dialogue><voice_ref>行くな！今がその时だろう。我が息子が怪人に连れ去られたんだぞ！あれから24时间が経とうとしているのに、まだ突入せんとは何事だ！ </voice_ref>. The frame hard cuts to a shot of @Actor-1's torso as he pulls a black shirt over his highly defined abdominal muscles, which are wrapped in white bandages. <sfx>The soft, rhythmic rustle of fabric is heard as the garment slides over his skin</sfx>. The camera tilts up to follow the movement until his face is revealed again. @Actor-1 speaks with a raspy, exhausted tone, <dialogue>喉嚨好渴</dialogue><voice_ref>行くな！今がその时だろう。我が息子が怪人に连れ去られたんだぞ！あれから24时间が経とうとしているのに、まだ突入せんとは何事だ！ </voice_ref>, then <dialogue>还有食物</dialogue><voice_ref>行くな！今がその时だろう。我が息子が怪人に连れ去られたんだぞ！あれから24时间が経とうとしているのに、まだ突入せんとは何事だ！ </voice_ref>, and finally <dialogue>我需要能补充血气的东西</dialogue><voice_ref>行くな！今がその时だろう。我が息子が怪人に连れ去られたんだぞ！あれから24时间が経とうとしているのに、まだ突入せんとは何事だ！ </voice_ref>. The background is a dark, cold concrete room, and the low-frequency background music persists throughout the scene",
   "duration": 5,
   "aspect_ratio": "16:9",
   "ref_images": [
   {
   "tag": "@Actor-1",
   "type": "subject",
   "image_urls": ["http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/1004_mo2v_0.jpg"]
   }
   ],
   "sound": true,
   "prompt_optimizer": true,
   "mode": "std"
   }'

3. Grid Reference Image to Video
   curl -X POST "https://api-gateway.skyreels.ai/api/v1/video/omni-video/submit" -H "Content-Type: application/json" -d '{
   "api_key": "YOUR_API_KEY",
   "prompt": "Create a video showing how to make tomato and egg noodles based on the grid of pictures in @image1.",
   "duration": 5,
   "aspect_ratio": "16:9",
   "ref_images": [
   {
   "tag": "@image1",
   "type": "image",
   "image_urls": ["http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/2017_gi2v_0.png"]
   }
   ],
   "sound": false,
   "prompt_optimizer": true,
   "mode": "std"
   }'

4. Video Motion Reference
   curl -X POST "https://api-gateway.skyreels.ai/api/v1/video/omni-video/submit" -H "Content-Type: application/json" -d '{
   "api*key": "YOUR_API_KEY",
   "prompt": "The man in @image_1 imitates the actions of the red male in @video_1, and the monkey in @image_2 imitates the actions of the dog in @video_1, while keeping the background of @video_1.",
   "duration": 5,
   "aspect_ratio": "16:9",
   "ref_images": [
   {
   "tag": "@image_1",
   "type": "image",
   "image_urls": ["http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/9037*%E8%BF%90%E5%8A%A8%E5%8F%82%E8%80%83*0.png"]
   },
   {
   "tag": "@image_2",
   "type": "image",
   "image_urls": ["http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/9037*%E8%BF%90%E5%8A%A8%E5%8F%82%E8%80%83*1.png"]
   }
   ],
   "ref_videos": [
   {
   "tag": "@video_1",
   "type": "reference",
   "video_url": "http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/9037*%E8%BF%90%E5%8A%A8%E5%8F%82%E8%80%83_2.mp4"
   }
   ],
   "sound": false,
   "prompt_optimizer": true,
   "mode": "std"
   }'

5. Video Subject Replacement
   curl -X POST "https://api-gateway.skyreels.ai/api/v1/video/omni-video/submit" -H "Content-Type: application/json" -d '{
   "api*key": "YOUR_API_KEY",
   "prompt": "Replace the rabbit in @video_1 with the velvet rabbit from @image_1.",
   "duration": 5,
   "aspect_ratio": "9:16",
   "ref_images": [
   {
   "tag": "@image_1",
   "type": "image",
   "image_urls": ["http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/9001*%E4%B8%BB%E4%BD%93%E6%9B%BF%E6%8D%A2*0.jpg"]
   }
   ],
   "ref_videos": [
   {
   "tag": "@video_1",
   "type": "base",
   "video_url": "http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/9001*%E4%B8%BB%E4%BD%93%E6%9B%BF%E6%8D%A2_1.mp4"
   }
   ],
   "sound": false,
   "prompt_optimizer": true,
   "mode": "std"
   }'

6. Video Background Replacement
   curl -X POST "https://api-gateway.skyreels.ai/api/v1/video/omni-video/submit" -H "Content-Type: application/json" -d '{
   "api*key": "YOUR_API_KEY",
   "prompt": "Replace the background in @video_1 with the Pyramids of Giza from @image_1.",
   "duration": 5,
   "aspect_ratio": "16:9",
   "ref_images": [
   {
   "tag": "@image_1",
   "type": "image",
   "image_urls": ["http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/9027*%E8%83%8C%E6%99%AF%E6%9B%BF%E6%8D%A2*0.png"]
   }
   ],
   "ref_videos": [
   {
   "tag": "@video_1",
   "type": "base",
   "video_url": "http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/9027*%E8%83%8C%E6%99%AF%E6%9B%BF%E6%8D%A2_1.mp4"
   }
   ],
   "sound": false,
   "prompt_optimizer": true,
   "mode": "std"
   }'

7. Video Object Removal
   curl -X POST "https://api-gateway.skyreels.ai/api/v1/video/omni-video/submit" -H "Content-Type: application/json" -d '{
   "api*key": "YOUR_API_KEY",
   "prompt": "Remove the thin-framed gold spectacles from the man's hands and face in the central foreground of @video_1.",
   "duration": 5,
   "aspect_ratio": "9:16",
   "ref_videos": [
   {
   "tag": "@video_1",
   "type": "base",
   "video_url": "http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/10009*%E7%89%A9%E4%BD%93%E5%88%A0%E9%99%A4_0.mp4"
   }
   ],
   "sound": false,
   "prompt_optimizer": true,
   "mode": "std"
   }'

8. Video Object Insertion
   curl -X POST "https://api-gateway.skyreels.ai/api/v1/video/omni-video/submit" -H "Content-Type: application/json" -d '{
   "api*key": "YOUR_API_KEY",
   "prompt": "Remove the thin-framed gold spectacles from the man's hands and face in the central foreground of @video_1.",
   "duration": 5,
   "aspect_ratio": "9:16",
   "ref_videos": [
   {
   "tag": "@video_1",
   "type": "base",
   "video_url": "http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/10009*%E7%89%A9%E4%BD%93%E5%88%A0%E9%99%A4_0.mp4"
   }
   ],
   "sound": false,
   "prompt_optimizer": true,
   "mode": "std"
   }'

9. Local Video Editing
   curl -X POST "https://api-gateway.skyreels.ai/api/v1/video/omni-video/submit" -H "Content-Type: application/json" -d '{
   "api*key": "YOUR_API_KEY",
   "prompt": "Replace the girl's clothing in @video_1 with the red superhero bodysuit from @image_1.",
   "duration": 5,
   "aspect_ratio": "9:16",
   "ref_images": [
   {
   "tag": "@image_1",
   "type": "image",
   "image_urls": ["http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/9013*%E5%B1%80%E9%83%A8%E4%BF%AE%E6%94%B9*0.png"]
   }
   ],
   "ref_videos": [
   {
   "tag": "@video_1",
   "type": "base",
   "video_url": "http://skyreels-api.oss-cn-hongkong.aliyuncs.com/examples/reference2video/assets/9013*%E5%B1%80%E9%83%A8%E4%BF%AE%E6%94%B9_1.mp4"
   }
   ],
   "sound": false,
   "prompt_optimizer": true,
   "mode": "std"
   }'

## 2. Task Query
- https://api-gateway.skyreels.ai/api/v1/video/omni-video/task/{task_id}

Response Parameters
Field Name	Type	Description
task_id	string	The task ID.
msg	string	Status message (contains error info on failure).
code	int	Status code (200 for success, 422 for parameter error, 500 for server error).
status	string	Task status, includes: "submitted", "pending", "running", "failed", "unknown".
data	object	Contains video data on success, null for other statuses.
trace_id	string	Request trace ID.
Data Field Details (when status is "success"):
Field Name	Type	Description
video_url	string	URL of the generated video.
duration	int	Video duration in seconds.
resolution	string	Video resolution.
Request Example
curl -X GET "https://api-gateway.skyreels.ai/api/v1/video/omni-video/task/{task_id}"