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

# SkyReels Omni Reference Video

> **[Core Function]** SkyReels Omni is a reference-driven video model that generates or edits video using reference images (@image) and/or a reference video (@video), bound by tags in the prompt. **[Strengths]** A single endpoint covers motion reference, subject/background replacement, object insertion/removal, local editing, and video extension. **[Best For]** Video subject or background swap, motion transfer onto an image, object add/remove, local video edits, and extending a reference video. **[Limitations]** Do NOT use this for pure text-to-video (use skyreels-t2v) or simple single-image animation (use skyreels-i2v). Each ref tag must appear in the prompt as @tag; ref_videos supports only one video (<=15s); a reference-type video may combine only with image-type ref_images, while an extend-type video cannot combine with ref_images. When ref_videos is provided, aspect_ratio is ignored (output matches the video). **[Routing]** Provide ref_images (type grid or image) for image references and/or a single ref_videos entry (type reference for motion/edit, type extend for continuation); the reference tags must be used in the prompt.



## OpenAPI

````yaml /model-api/skywork/skyreels-v2v.json post /skywork/skyreels-omni
openapi: 3.1.0
info:
  description: >-
    The video-to-video models API from SkyReels (Skywork). Includes Omni
    reference-driven video generation/editing, style transfer, single-shot and
    shot-switching extension, and lip sync. Tasks are asynchronous: submit, then
    poll the task endpoint for the result.
  version: 1.0.0
  contact:
    name: Modellix Support
    email: support@modellix.ai
  title: SkyReels Video-to-Video Models API
servers:
  - url: https://api.modellix.ai/api/v1
    description: The video-to-video models API from SkyReels (Skywork).
security:
  - bearerAuth: []
paths:
  /skywork/skyreels-omni:
    post:
      summary: SkyReels Omni Reference Video
      description: >-
        **[Core Function]** SkyReels Omni is a reference-driven video model that
        generates or edits video using reference images (@image) and/or a
        reference video (@video), bound by tags in the prompt. **[Strengths]** A
        single endpoint covers motion reference, subject/background replacement,
        object insertion/removal, local editing, and video extension. **[Best
        For]** Video subject or background swap, motion transfer onto an image,
        object add/remove, local video edits, and extending a reference video.
        **[Limitations]** Do NOT use this for pure text-to-video (use
        skyreels-t2v) or simple single-image animation (use skyreels-i2v). Each
        ref tag must appear in the prompt as @tag; ref_videos supports only one
        video (<=15s); a reference-type video may combine only with image-type
        ref_images, while an extend-type video cannot combine with ref_images.
        When ref_videos is provided, aspect_ratio is ignored (output matches the
        video). **[Routing]** Provide ref_images (type grid or image) for image
        references and/or a single ref_videos entry (type reference for
        motion/edit, type extend for continuation); the reference tags must be
        used in the prompt.
      operationId: skyreelsOmniAsync
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkyreelsOmniRequest'
            examples:
              imageReference:
                summary: Multi-subject image reference
                value:
                  prompt: '@Actor-1 walks through a rainy neon street at night'
                  duration: 5
                  aspect_ratio: '16:9'
                  ref_images:
                    - tag: '@Actor-1'
                      type: image
                      image_urls:
                        - https://example.com/actor.png
                  mode: std
              motionReference:
                summary: Image + reference video (motion transfer)
                value:
                  prompt: >-
                    The girl in @image1 mimics the gestures of the woman in
                    @video1
                  ref_images:
                    - tag: '@image1'
                      type: image
                      image_urls:
                        - https://example.com/image1.png
                  ref_videos:
                    - tag: '@video1'
                      type: reference
                      video_url: https://example.com/motion.mp4
                  mode: std
              extend:
                summary: Video extension
                value:
                  prompt: >-
                    Video extended @video1, someone walks over and sits on the
                    sofa
                  duration: 8
                  ref_videos:
                    - tag: '@video1'
                      type: extend
                      video_url: https://example.com/clip.mp4
                  mode: std
      responses:
        '200':
          description: Task submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncTaskResponse'
              example:
                code: 0
                message: success
                data:
                  status: pending
                  task_id: task-skyreels-omni-001
                  model_id: skyreels/skyreels-omni
                  get_result:
                    method: GET
                    url: >-
                      https://api.modellix.ai/api/v1/tasks/task-skyreels-omni-001
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    SkyreelsOmniRequest:
      type: object
      required:
        - prompt
      description: >-
        SkyReels Omni reference video request. prompt is required; provide
        ref_images and/or ref_videos to drive the reference-based task. Each ref
        tag must appear in the prompt as @tag.
      properties:
        prompt:
          type: string
          minLength: 1
          description: >-
            Text description; must reference each ref tag via @tag (max 1280
            tokens).
          example: The girl in @image1 mimics the gestures of the woman in @video1
        aspect_ratio:
          type: string
          enum:
            - '16:9'
            - '4:3'
            - '1:1'
            - '9:16'
            - '3:4'
          default: '16:9'
          description: >-
            Video aspect ratio. Ignored when ref_videos is provided (output
            matches the reference video).
          example: '16:9'
        duration:
          type: integer
          minimum: 3
          maximum: 15
          default: 5
          description: >-
            Video duration in seconds. Overridden when ref_videos.type=reference
            (matches the reference video, up to 10s).
          example: 5
        ref_images:
          type: array
          description: Reference image groups. All items must share the same type.
          items:
            $ref: '#/components/schemas/OmniRefImage'
        ref_videos:
          type: array
          maxItems: 1
          description: A single reference video (<=15s).
          items:
            $ref: '#/components/schemas/OmniRefVideo'
        resolution:
          type: string
          enum:
            - 480p
            - 720p
            - 1080p
          default: 1080p
          description: Output video resolution.
          example: 1080p
        mode:
          type: string
          enum:
            - fast
            - std
          default: std
          description: >-
            Quality/performance mode. fast is quicker (sound must be false); std
            balances speed and quality.
          example: std
        sound:
          type: boolean
          default: false
          description: >-
            Whether to generate audio. Not effective when using a video
            reference (the reference video's audio is used).
          example: false
        prompt_optimizer:
          type: boolean
          default: true
          description: Enable automatic prompt expansion/optimization.
          example: true
    AsyncTaskResponse:
      type: object
      required:
        - code
        - message
        - data
      properties:
        code:
          type: integer
          description: Response code, 0 indicates success
          example: 0
        message:
          type: string
          description: Response message
          example: success
        data:
          type: object
          required:
            - status
            - task_id
            - model_id
          properties:
            status:
              type: string
              enum:
                - pending
                - processing
              description: Task status
              example: pending
            task_id:
              type: string
              description: Unique task identifier for polling
              example: task-abc123
            model_id:
              type: string
              description: Model ID in `provider/model` format
              example: skyreels/skyreels-omni
            get_result:
              type: object
              description: API information to query the task result
              properties:
                method:
                  type: string
                  example: GET
                url:
                  type: string
                  example: https://api.modellix.ai/api/v1/tasks/task-abc123
          description: Detailed data about the submitted asynchronous task.
    OmniRefImage:
      type: object
      required:
        - tag
        - type
        - image_urls
      description: An Omni image reference group.
      properties:
        tag:
          type: string
          minLength: 1
          pattern: ^@
          description: >-
            Identifier starting with @, must appear in the prompt (e.g.
            @image1).
          example: '@image1'
        type:
          type: string
          enum:
            - grid
            - image
          description: >-
            grid = a single grid/collage image (image_urls must contain exactly
            1); image = subject/scene references (image_urls may contain 1-5).
          example: image
        image_urls:
          type: array
          description: >-
            Image URLs (jpg/jpeg/png/gif/bmp). Count: type=grid requires exactly
            1; type=image allows 1-5.
          items:
            type: string
            minLength: 1
          example:
            - https://example.com/image1.png
        audio_url:
          type: string
          description: >-
            Optional voice/audio URL for this reference (only for type=image,
            <=15s).
          example: ''
    OmniRefVideo:
      type: object
      required:
        - tag
        - type
        - video_url
      description: An Omni video reference.
      properties:
        tag:
          type: string
          minLength: 1
          pattern: ^@
          description: >-
            Identifier starting with @, must appear in the prompt (e.g.
            @video1).
          example: '@video1'
        type:
          type: string
          enum:
            - reference
            - extend
          description: >-
            reference = motion/edit reference (combine only with image-type
            ref_images); extend = video continuation (cannot combine with
            ref_images).
          example: reference
        video_url:
          type: string
          minLength: 1
          description: Video URL (MP4/MOV, <=15s).
          example: https://example.com/motion.mp4
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: 'Invalid parameters: parameter ''prompt'' is required'
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 400
            message: 'Invalid parameters: parameter ''prompt'' is required'
    Unauthorized:
      description: Unauthorized - Invalid or missing API Key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 401
            message: 'Authentication failed: invalid API key'
    TooManyRequests:
      description: Too many requests - Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          description: Maximum requests per minute
          schema:
            type: integer
            example: 100
        X-RateLimit-Remaining:
          description: Remaining quota in current window
          schema:
            type: integer
            example: 0
        X-RateLimit-Reset:
          description: Rate limit window reset time (Unix timestamp)
          schema:
            type: integer
            example: 1704067260
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 429
            message: >-
              Rate limit exceeded: 100 requests per minute, retry after 60
              seconds
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 500
            message: Internal server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API Key authentication. Format: `Bearer YOUR_API_KEY`.'

````