Subject Reference-to-Video

Overview

• API: Subject Reference-to-Video
• Description: Generate a video clip using a subject reference image (currently supports only a person portrait) combined with a text description.
• Model: S2V-01 (available only when model is S2V-01).

Authentication

• Use Bearer Token in the request header: Authorization: Bearer <token>.

Request Parameters

• Request Content-Type: application/json

• Request body fields:

  • model (string, required)

    • Model name, valid value: S2V-01.

  • prompt (string)

    • Text description for the video, up to 2000 characters.

  • prompt_optimizer (boolean, optional, default true)

    • Whether to auto-optimize the prompt. Set to false for finer control.

  • subject_reference (array, required)

    • Array containing the subject reference images (currently only a single image is supported).
    • Item structure:
      • type (string, required): subject type, currently only character (person portrait) is supported.
      • image (string, required): image URL or Base64-encoded data.
    • Image requirements:
      • Formats: JPG, JPEG, PNG, WebP
      • Size: under 20MB
      • Dimensions: short side greater than 300px, aspect ratio between 2:5 and 5:2

  • callback_url (string, optional)

    • Callback URL for task status updates. When configured, MiniMax will send a verification request containing challenge. The server must return the same challenge value within 3 seconds to pass verification.
    • After verification succeeds, the server will push task status updates to the URL when the status changes. The payload matches the query API response structure. Status values include processing, success, and failed.

Request Example

curl -X POST "https://api.gpt.ge/task/minimax/v1/video_generation" \
  -H "Authorization: Bearer $YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "S2V-01",
    "prompt": "A girl runs toward the camera and smiles while blinking.",
    "subject_reference": [
      {
        "type": "character",
        "image": "https://cdn.hailuoai.com/prod/2025-08-12-17/video_cover/1754990600020238321-411603868533342214-cover.jpg"
      }
    ]
  }'

Request Body Example

{
  "model": "S2V-01",
  "prompt": "A girl runs toward the camera and smiles while blinking.",
  "subject_reference": [
    {
      "type": "character",
      "image": "https://cdn.hailuoai.com/prod/2025-08-12-17/video_cover/1754990600020238321-411603868533342214-cover.jpg"
    }
  ]
}

Success Response Example

{
  "task_id": "106916112212032",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

Response Fields

• task_id (string): task ID to query status and results.
• base_resp (object): basic response information, includes status_code (integer) and status_msg (string).

Notes

• Make sure required parameters are provided, otherwise model name recognition may fail.
• subject_reference currently supports only a single subject (person portrait).
• Follow the image format and size limits to ensure good results.