{
  "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.minimaxi.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/video_generation": {
      "post": {
        "summary": "Video Generation",
        "operationId": "videoGeneration",
        "tags": ["Video"],
        "parameters": [
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "description": "请求体的媒介类型，请设置为 `application/json` 确保请求数据的格式为 JSON.",
            "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": "模型名称。可用值： `S2V-01`.  ",
            "enum": ["S2V-01"]
          },
          "prompt": {
            "type": "string",
            "description": "视频的文本描述，最大 2000 字符."
          },
          "prompt_optimizer": {
            "type": "boolean",
           "description": "是否自动优化 `prompt`，默认为 `true`。设为 `false` 可进行更精确的控制"
          },
          "subject_reference": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SubjectReference"
            },
            "description": "主体参考，仅当 `model` 为 `S2V-01` 时可用。目前仅支持单个主体"
          },
          "callback_url": {
            "type": "string",
            "description": "接收任务状态更新通知的回调 URL。支持通过 callback_url 参数可以配置回调，以接收任务状态的更新的异步通知。\n\n地址验证：配置后，MiniMax 服务器会向 callback_url 发送一个 POST 请求，请求体中包含 challenge 字段。服务端需要在 3 秒内原样返回该 challenge 值以完成验证\n状态更新：验证成功后，每当任务状态变更时，MiniMax 都会向该 URL 推送最新的任务状态。推送的数据结构与调用查询视频生成任务接口的响应体一致\n\n回调返回的\"status\"包括以下状态：\n- `\"processing\"` - 生成中\n- `\"success\"` - 成功\n- `\"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,  # 必选\r\n        host=\"0.0.0.0\",  # 必选\r\n        port=8000,  # 必选，端口可设置\r\n        # ssl_keyfile=\"yourname.yourDomainName.com.key\",  # 可选，看是否开启ssl\r\n        # ssl_certfile=\"yourname.yourDomainName.com.key\",  # 可选，看是否开启ssl\r\n    )\n```"
          },
          "aigc_watermark": {
            "type": "boolean",
            "description": "是否在生成的视频中添加水印，默认为 `false`"
          }
        },
        "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": "视频生成任务的 ID，用于后续查询任务状态"
          },
          "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": "主体类型，当前仅支持 `character` (人物面部)"
          },
          "image": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "包含主体参考图的数组（目前仅支持单张图片）\n\n- 图片要求：\n\t- 格式：JPG, JPEG, PNG, WebP\n\t- 体积：小于 20MB\n\t- 尺寸：短边像素大于 300px，长宽比在 2:5 和 5:2 之间  "
          }
        }
      },
      "BaseResp": {
        "type": "object",
        "properties": {
          "status_code": {
            "type": "integer",
            "description": "状态码及其分别含义如下：\n- 0：请求成功\n- 1002：触发限流，请稍后再试\n- 1004：账号鉴权失败，请检查 API-Key 是否填写正确\n- 1008：账号余额不足\n- 1026：视频描述涉及敏感内容，请调整\n- 2013：传入参数异常，请检查入参是否按要求填写\n- 2049：无效的api key，请检查api key\n\n更多内容可查看[错误码列表](/api-reference/errorcode)"
          },
          "status_msg": {
            "type": "string",
            "description": "具体错误详情"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
         "description": "`HTTP: Bearer Auth`\n - Security Scheme Type: http\n - HTTP Authorization Scheme: Bearer API_key，用于验证账户信息，可在 [账户管理>接口密钥](https://platform.minimaxi.com/user-center/basic-information/interface-key) 中查看。"
      }
    }
  }
}