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

# Subject-Reference to Video Generation Task



## OpenAPI

````yaml /api-reference/video/generation/api/subject-reference-to-video.json POST /v1/video_generation
openapi: 3.1.0
info:
  title: MiniMax API
  description: MiniMax video generation and file management API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.minimax.io
security:
  - bearerAuth: []
paths:
  /v1/video_generation:
    post:
      tags:
        - Video
      summary: Video Generation
      operationId: videoGeneration
      parameters:
        - name: Content-Type
          in: header
          required: true
          description: >-
            The media type of the request body. Must be set to
            `application/json` to ensure the data is sent in JSON format.
          schema:
            type: string
            enum:
              - application/json
            default: application/json
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoGenerationReq'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoGenerationResp'
components:
  schemas:
    VideoGenerationReq:
      type: object
      required:
        - model
        - subject_reference
      properties:
        model:
          type: string
          description: 'Model name. Supported values: `S2V-01`.  '
          enum:
            - S2V-01
        prompt:
          type: string
          description: Text description of the video, up to 2000 characters.
        prompt_optimizer:
          type: boolean
          description: >-
            Whether to automatically optimize the `prompt`. Defaults to `true`.
            Set to `false` for more precise control.
        subject_reference:
          type: array
          items:
            $ref: '#/components/schemas/SubjectReference'
          description: Subject reference images
        callback_url:
          type: string
          description: "A callback URL to receive asynchronous task status updates.\n1. **Validation**: Once configured, MiniMax sends a `POST` request with a `challenge` field. Your server must echo this value within 3s to validate.\n2. **Updates**: After validation, MiniMax pushes status updates when the task changes. Response structure matches the [*Query Video Generation Task* API](/api-reference/video-generation-query).  \n\n**Callback `status` values**:\n- `\"processing\"` – Task in progress\n- `\"success\"` – Task completed successfully\n- `\"failed\"` – Task failed\n\n```python\nfrom fastapi import FastAPI, HTTPException, Request\r\nimport json\r\n\r\napp = FastAPI()\r\n\r\n@app.post(\"/get_callback\")\r\nasync def get_callback(request: Request):\r\n    try:\r\n        json_data = await request.json()\r\n        challenge = json_data.get(\"challenge\")\r\n        if challenge is not None:\r\n            # Validation request, echo back challenge\r\n            return {\"challenge\": challenge}\r\n        else:\r\n            # Status update request, handle accordingly\r\n            # {\r\n            #     \"task_id\": \"115334141465231360\",\r\n            #     \"status\": \"success\",\r\n            #     \"file_id\": \"205258526306433\",\r\n            #     \"base_resp\": {\r\n            #         \"status_code\": 0,\r\n            #         \"status_msg\": \"success\"\r\n            #     }\r\n            # }\r\n            return {\"status\": \"success\"}\r\n    except Exception as e:\r\n        raise HTTPException(status_code=500, detail=str(e))\r\n\r\nif __name__ == \"__main__\":\r\n    import uvicorn\r\n    uvicorn.run(\r\n        app,  # Required\r\n        host=\"0.0.0.0\",  # Required\r\n        port=8000,  # Required, port can be customized\r\n        # ssl_keyfile=\"yourname.yourDomainName.com.key\",  # Optional, enable if using SSL\r\n        # ssl_certfile=\"yourname.yourDomainName.com.key\",  # Optional, enable if using SSL\r\n    )\n```"
      example:
        prompt: A girl runs toward the camera and winks with a smile.
        subject_reference:
          - type: character
            image:
              - >-
                https://cdn.hailuoai.com/prod/2025-08-12-17/video_cover/1754990600020238321-411603868533342214-cover.jpg
        model: S2V-01
    VideoGenerationResp:
      type: object
      properties:
        task_id:
          type: string
          description: The video generation task ID, used for querying status.
        base_resp:
          $ref: '#/components/schemas/BaseResp'
      example:
        task_id: '106916112212032'
        base_resp:
          status_code: 0
          status_msg: success
    SubjectReference:
      type: object
      required:
        - type
        - image
      properties:
        type:
          type: string
          description: Subject type, currently only `character` (face of a person).
        image:
          type: array
          items:
            type: string
          description: "Array containing the reference image (only one image supported).  \n- Requirements:  \n\t- Formats: JPG, JPEG, PNG, WebP.  \n\t- File size: < 20MB.  \n\t- Resolution: shorter side > 300px; aspect ratio between 2:5 and 5:2.  "
    BaseResp:
      type: object
      properties:
        status_code:
          type: integer
          description: >-
            The status codes and their meanings are as follows:

            - `0`, Request successful

            - `1002`, Rate limit triggered, please try again later

            - `1004`, Account authentication failed, please check if the API Key
            is correct

            - `1008`, Insufficient account balance

            - `1026`, Sensitive content detected in prompt

            - `2013`, Invalid input parameters, please check if the parameters
            are filled in as required

            - `2049`, Invalid API Key


            For more information, please refer to the [Error Code
            Reference](/api-reference/errorcode).  
        status_msg:
          type: string
          description: Status details.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        `HTTP: Bearer Auth`

        - Security Scheme Type: http

        - HTTP Authorization Scheme: `Bearer API_key`, can be found in [Account
        Management>API
        Keys](https://platform.minimax.io/user-center/basic-information/interface-key).

````