> ## 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.

# C1 Reference-to-Video (Fusion)

> [Core Function] PixVerse c1 reference-to-video (fusion) generates a video from a prompt while preserving subjects from 1-7 reference images; each reference can be tagged as subject/background and named for @-reference in the prompt. [Strengths] Precise multi-subject composition and identity preservation. [Best For] Putting specific characters/objects into a new scene, multi-character interactions. [Limitations] Do NOT use this for single-image animation (use Image-to-Video), two-frame transitions (use First-Last-Frame), or text-only generation (use Text-to-Video). It requires 1-7 reference images and a required aspect_ratio, and supports up to 1080p and a maximum of 15s. [Routing] Use when the user provides one or more reference images to be fused into the video, especially when distinguishing subject vs background or naming references for the prompt. The v6 and c1 reference-to-video variants accept identical parameters; choose the version the user requests.



## OpenAPI

````yaml /model-api/pixverse/pixverse-i2v.json post /pixverse/c1-r2v
openapi: 3.1.0
info:
  description: >-
    The image-to-video models API from PixVerse. Includes single-image-to-video,
    first-last-frame transition, and reference-to-video (fusion). 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: PixVerse Image-to-Video Models API
servers:
  - url: https://api.modellix.ai/api/v1
    description: The image-to-video models API from PixVerse.
security:
  - bearerAuth: []
paths:
  /pixverse/c1-r2v:
    post:
      summary: C1 Reference-to-Video (Fusion)
      description: >-
        [Core Function] PixVerse c1 reference-to-video (fusion) generates a
        video from a prompt while preserving subjects from 1-7 reference images;
        each reference can be tagged as subject/background and named for
        @-reference in the prompt. [Strengths] Precise multi-subject composition
        and identity preservation. [Best For] Putting specific
        characters/objects into a new scene, multi-character interactions.
        [Limitations] Do NOT use this for single-image animation (use
        Image-to-Video), two-frame transitions (use First-Last-Frame), or
        text-only generation (use Text-to-Video). It requires 1-7 reference
        images and a required aspect_ratio, and supports up to 1080p and a
        maximum of 15s. [Routing] Use when the user provides one or more
        reference images to be fused into the video, especially when
        distinguishing subject vs background or naming references for the
        prompt. The v6 and c1 reference-to-video variants accept identical
        parameters; choose the version the user requests.
      operationId: pixverseC1R2VAsync
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PixverseR2VRequest'
            examples:
              basic:
                summary: Reference images with role and name
                value:
                  reference_images:
                    - url: https://example.com/hero.png
                      type: subject
                      ref_name: hero
                    - url: https://example.com/forest.png
                      type: background
                  prompt: '@hero runs across @forest under the northern lights'
                  duration: 5
                  quality: 720p
                  aspect_ratio: '16:9'
      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-pixverse-r2v-002
                  model_id: pixverse/c1-r2v
                  get_result:
                    method: GET
                    url: https://api.modellix.ai/api/v1/tasks/task-pixverse-r2v-002
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    PixverseR2VRequest:
      type: object
      required:
        - reference_images
        - prompt
        - duration
        - quality
        - aspect_ratio
      description: >-
        PixVerse reference-to-video (fusion) request. Fuses 1-7 reference images
        into a video; each reference image is an OBJECT carrying a url plus
        optional role (type) and a name (ref_name) referenceable in the prompt
        via @ref_name. NOTE: unlike xai/vidu (flat URL string arrays), PixVerse
        reference_images items are objects. Used by both v6 and c1 (the path
        determines the model version).
      properties:
        reference_images:
          type: array
          minItems: 1
          maxItems: 7
          description: >-
            Reference images (1-7) fused into the generated video. Each item is
            an object: a publicly accessible image URL, plus optional role
            (type: subject/background) and a name (ref_name) you can reference
            in the prompt via @ref_name for precise multi-subject control.
          items:
            type: object
            required:
              - url
            properties:
              url:
                type: string
                minLength: 1
                description: Reference image URL (publicly accessible; png/jpeg/jpg/webp).
                example: https://example.com/hero.png
              type:
                type: string
                enum:
                  - subject
                  - background
                description: >-
                  Role of this reference image: subject (main character/object)
                  or background (scene). Optional.
                example: subject
              ref_name:
                type: string
                maxLength: 30
                description: >-
                  Optional name (<=30 chars) for this reference. Reference it in
                  the prompt via @ref_name for precise multi-subject
                  composition, e.g. prompt "@hero runs through @forest".
                example: hero
          example:
            - url: https://example.com/hero.png
              type: subject
              ref_name: hero
            - url: https://example.com/forest.png
              type: background
        prompt:
          type: string
          minLength: 1
          maxLength: 5000
          description: >-
            Text prompt; may reference named images via @ref_name (e.g. "@hero
            in @forest").
          example: '@hero runs across @forest under the northern lights'
        duration:
          type: integer
          minimum: 1
          maximum: 15
          description: Video duration in seconds (required).
          example: 5
        quality:
          type: string
          enum:
            - 360p
            - 540p
            - 720p
            - 1080p
          description: Output resolution (required).
          example: 720p
        aspect_ratio:
          type: string
          enum:
            - '16:9'
            - '9:16'
            - '1:1'
            - '3:4'
            - '4:3'
            - '2:3'
            - '3:2'
            - '21:9'
          description: Video aspect ratio (required).
          example: '16:9'
        seed:
          type: integer
          minimum: 0
          maximum: 2147483647
          description: Random seed (omit for random).
          example: 0
        generate_audio_switch:
          type: boolean
          default: false
          description: Whether to generate audio.
          example: false
    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: pixverse/v6-r2v
            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.
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: 'Invalid parameters: parameter ''image'' is required'
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 400
            message: 'Invalid parameters: parameter ''image'' 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`.'

````