> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gmicloud.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# skyreels-v4-omni

> API usage guide for skyreels-v4-omni.

{/* source_model_id: skyreels-v4-omni */}

{/* source_updated_at: 1781741075 */}

**Model ID**

```bash theme={null}
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:

```bash theme={null}
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)

```bash theme={null}
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)

```bash theme={null}
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)

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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.