openapi: 3.1.0
info:
  title: MiniMax H3 Video Service
  version: 1.0.0
  description: |
    Self-hosted MiniMax H3 multimodal video service. It exposes a native API,
    an OpenAI Videos-compatible API, and a MiniMax Video Generation-compatible API.
servers:
  - url: /
security:
  - bearerAuth: []
tags:
  - name: Native
  - name: OpenAI compatible
  - name: MiniMax compatible
paths:
  /api/v1/capabilities:
    get:
      tags: [Native]
      summary: Get supported resolutions, durations, modes, and current GPU hourly rate
      responses:
        '200':
          description: Platform capabilities
          content:
            application/json:
              schema: {type: object, additionalProperties: true}
  /api/v1/videos/generations:
    post:
      tags: [Native]
      summary: Create a MiniMax H3 video job
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/NativeVideoCreate'}
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema: {$ref: '#/components/schemas/NativeVideo'}
        '400': {$ref: '#/components/responses/NativeError'}
  /api/v1/videos/{video_id}:
    get:
      tags: [Native]
      summary: Get a native video job
      parameters:
        - $ref: '#/components/parameters/VideoID'
      responses:
        '200':
          description: Video job
          content:
            application/json:
              schema: {$ref: '#/components/schemas/NativeVideo'}
        '404': {$ref: '#/components/responses/NativeError'}
  /api/v1/videos/{video_id}/cancel:
    post:
      tags: [Native]
      summary: Cancel a native video job
      parameters:
        - $ref: '#/components/parameters/VideoID'
      responses:
        '200':
          description: Canceled video job
          content:
            application/json:
              schema: {$ref: '#/components/schemas/NativeVideo'}
  /v1/videos:
    post:
      tags: [OpenAI compatible]
      summary: Create an OpenAI Videos-compatible job
      description: Accepts JSON or multipart/form-data. input_reference enables first-frame I2V; extension fields support H3 omni reference images, videos, and audio.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/OpenAIVideoCreate'}
          multipart/form-data:
            schema: {$ref: '#/components/schemas/OpenAIVideoCreate'}
      responses:
        '200':
          description: Created video job
          content:
            application/json:
              schema: {$ref: '#/components/schemas/OpenAIVideo'}
        '400': {$ref: '#/components/responses/OpenAIError'}
    get:
      tags: [OpenAI compatible]
      summary: List video jobs belonging to the API key
      parameters:
        - name: limit
          in: query
          schema: {type: integer, minimum: 1, maximum: 100, default: 20}
      responses:
        '200':
          description: Video list
          content:
            application/json:
              schema:
                type: object
                properties:
                  object: {const: list}
                  data: {type: array, items: {$ref: '#/components/schemas/OpenAIVideo'}}
                  has_more: {type: boolean}
  /v1/videos/{video_id}:
    get:
      tags: [OpenAI compatible]
      summary: Get an OpenAI Videos-compatible job
      parameters:
        - $ref: '#/components/parameters/VideoID'
      responses:
        '200':
          description: Video job
          content:
            application/json:
              schema: {$ref: '#/components/schemas/OpenAIVideo'}
        '404': {$ref: '#/components/responses/OpenAIError'}
    delete:
      tags: [OpenAI compatible]
      summary: Delete a video result or cancel an unfinished job
      parameters:
        - $ref: '#/components/parameters/VideoID'
      responses:
        '200':
          description: Deletion result
          content:
            application/json:
              schema:
                type: object
                required: [id, object, deleted]
                properties:
                  id: {type: string}
                  object: {const: video.deleted}
                  deleted: {type: boolean}
  /v1/videos/{video_id}/content:
    get:
      tags: [OpenAI compatible]
      summary: Download the completed MP4
      parameters:
        - $ref: '#/components/parameters/VideoID'
      responses:
        '200':
          description: MP4 content
          content:
            video/mp4:
              schema: {type: string, contentMediaType: video/mp4, contentEncoding: binary}
        '409': {$ref: '#/components/responses/OpenAIError'}
  /v1/video_generation:
    post:
      tags: [MiniMax compatible]
      summary: Create a MiniMax-compatible video generation task
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/MiniMaxVideoCreate'}
      responses:
        '200':
          description: Task created
          content:
            application/json:
              schema:
                type: object
                required: [task_id, base_resp]
                properties:
                  task_id: {type: string}
                  base_resp: {$ref: '#/components/schemas/MiniMaxBaseResponse'}
  /v1/query/video_generation:
    get:
      tags: [MiniMax compatible]
      summary: Query a MiniMax-compatible task
      parameters:
        - name: task_id
          in: query
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Task state
          content:
            application/json:
              schema:
                type: object
                required: [task_id, status, base_resp]
                properties:
                  task_id: {type: string}
                  status: {type: string, enum: [Preparing, Processing, Success, Fail]}
                  file_id: {type: string}
                  video_width: {type: integer}
                  video_height: {type: integer}
                  error_message: {type: string}
                  base_resp: {$ref: '#/components/schemas/MiniMaxBaseResponse'}
  /v1/files/retrieve:
    get:
      tags: [MiniMax compatible]
      summary: Retrieve the signed download URL for a successful MiniMax task
      parameters:
        - name: file_id
          in: query
          required: true
          schema: {type: string}
      responses:
        '200':
          description: File metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  file:
                    type: object
                    properties:
                      file_id: {type: string}
                      bytes: {type: integer, format: int64}
                      purpose: {const: video_generation}
                      download_url: {type: string, format: uri}
                  base_resp: {$ref: '#/components/schemas/MiniMaxBaseResponse'}
  /v2/video_generation:
    post:
      tags: [MiniMax compatible]
      summary: Create an official MiniMax H3 V2 multimodal video task
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/MiniMaxV2VideoCreate'}
      responses:
        '200':
          description: Task created
          content:
            application/json:
              schema:
                type: object
                required: [task_id]
                properties: {task_id: {type: string}}
        '400': {$ref: '#/components/responses/MiniMaxV2Error'}
  /v2/query/video_generation:
    get:
      tags: [MiniMax compatible]
      summary: List MiniMax H3 V2 tasks
      responses:
        '200':
          description: Task list
          content:
            application/json:
              schema:
                type: object
                properties:
                  items: {type: array, items: {$ref: '#/components/schemas/MiniMaxV2Task'}}
                  total: {type: integer}
  /v2/query/video_generation/{task_id}:
    get:
      tags: [MiniMax compatible]
      summary: Query a MiniMax H3 V2 task
      parameters:
        - name: task_id
          in: path
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Task state
          content:
            application/json:
              schema:
                type: object
                properties: {task: {$ref: '#/components/schemas/MiniMaxV2Task'}}
  /v2/video_generation/{task_id}:
    delete:
      tags: [MiniMax compatible]
      summary: Cancel or delete a MiniMax H3 V2 task
      parameters:
        - name: task_id
          in: path
          required: true
          schema: {type: string}
      responses:
        '200':
          description: Cancellation or deletion result
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id: {type: string}
                  action: {type: string, enum: [cancelled, deleted]}
                  status: {type: string, enum: [cancelled, deleted]}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
  parameters:
    VideoID:
      name: video_id
      in: path
      required: true
      schema: {type: string}
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema: {type: string, maxLength: 255}
  responses:
    NativeError:
      description: Native API error
      content:
        application/json:
          schema: {$ref: '#/components/schemas/NativeError'}
    OpenAIError:
      description: OpenAI-compatible error
      content:
        application/json:
          schema: {$ref: '#/components/schemas/OpenAIError'}
    MiniMaxV2Error:
      description: MiniMax H3 V2 error
      content:
        application/json:
          schema:
            type: object
            properties:
              type: {const: error}
              error:
                type: object
                properties:
                  type: {type: string}
                  message: {type: string}
                  http_code: {type: string}
  schemas:
    NativeVideoCreate:
      type: object
      required: [prompt]
      properties:
        model: {type: string, default: minimax-h3}
        prompt: {type: string, minLength: 1, maxLength: 7000}
        resolution: {type: string, enum: [480P, 768P, 1080P], default: 768P}
        duration: {type: number, minimum: 0.1, maximum: 15, default: 5}
        mode: {type: string, enum: [native, sage, te-speed], default: native}
        seed: {type: integer, format: int64, default: 556589502035082}
        steps: {type: integer, minimum: 1, maximum: 50, default: 20}
        first_frame_image: {type: string, description: Public URL, mm_file URI, or data URI.}
        last_frame_image: {type: string, description: Public URL, mm_file URI, or data URI.}
        reference_images: {type: array, maxItems: 9, items: {type: string}}
        reference_videos: {type: array, maxItems: 3, items: {type: string}}
        reference_audios: {type: array, maxItems: 3, items: {type: string}}
        reference_image_size: {type: string, enum: [match, max], default: match}
    OpenAIVideoCreate:
      type: object
      required: [prompt]
      properties:
        model:
          type: string
          enum: [minimax-h3, minimax-h3-sage, minimax-h3-te-speed]
          default: minimax-h3
        prompt: {type: string, minLength: 1, maxLength: 7000}
        size:
          type: string
          enum: [864x480, 480x864, 1344x768, 768x1344, 1920x1080, 1080x1920]
          default: 1344x768
        seconds:
          oneOf: [{type: string}, {type: number}]
          default: '5'
        mode: {type: string, enum: [native, sage, te-speed]}
        seed: {type: integer, format: int64}
        steps: {type: integer, minimum: 1, maximum: 50}
        input_reference:
          oneOf: [{type: string}, {type: string, contentEncoding: binary}]
          description: First-frame reference image. JSON accepts URL/data URI; multipart accepts a file.
        reference_images: {type: array, maxItems: 9, items: {type: string}}
        reference_videos: {type: array, maxItems: 3, items: {type: string}}
        reference_audios: {type: array, maxItems: 3, items: {type: string}}
        reference_image_size: {type: string, enum: [match, max], default: match}
    MiniMaxVideoCreate:
      type: object
      required: [model, prompt]
      properties:
        model: {type: string, example: MiniMax-H3}
        prompt: {type: string, minLength: 1, maxLength: 7000}
        duration: {type: number, minimum: 0.1, maximum: 15, default: 5}
        resolution: {type: string, enum: [480P, 768P, 1080P], default: 768P}
        mode: {type: string, enum: [native, sage, te-speed]}
        seed: {type: integer, format: int64}
        steps: {type: integer, minimum: 1, maximum: 50}
        prompt_optimizer: {type: boolean}
        first_frame_image: {type: string, description: Public URL, mm_file URI, or data URI.}
        last_frame_image: {type: string, description: Public URL, mm_file URI, or data URI.}
        reference_images: {type: array, maxItems: 9, items: {type: string}}
        reference_videos: {type: array, maxItems: 3, items: {type: string}}
        reference_audios: {type: array, maxItems: 3, items: {type: string}}
        reference_image_size: {type: string, enum: [match, max], default: match}
    MiniMaxV2VideoCreate:
      type: object
      required: [model, content, resolution, duration]
      properties:
        model: {type: string, const: MiniMax-H3}
        content:
          type: array
          minItems: 1
          maxItems: 13
          items: {$ref: '#/components/schemas/MiniMaxV2ContentItem'}
        resolution: {type: string, enum: [768P], description: Local profile currently exposes 768P; 2K is not enabled.}
        duration: {type: integer, minimum: 4, maximum: 15}
        ratio: {type: string, enum: [adaptive, '21:9', '16:9', '4:3', '1:1', '3:4', '9:16']}
        mode: {type: string, enum: [native, sage, te-speed], description: Self-hosted extension.}
        seed: {type: integer, format: int64}
        steps: {type: integer, minimum: 1, maximum: 50}
        reference_image_size: {type: string, enum: [match, max], default: match}
    MiniMaxV2ContentItem:
      type: object
      required: [type]
      properties:
        type: {type: string, enum: [text, image_url, video_url, audio_url]}
        text: {type: string, maxLength: 7000}
        role: {type: string, enum: [first_frame, last_frame, reference_image, reference_video, reference_audio]}
        image_url: {$ref: '#/components/schemas/MediaURL'}
        video_url: {$ref: '#/components/schemas/MediaURL'}
        audio_url: {$ref: '#/components/schemas/MediaURL'}
    MediaURL:
      type: object
      required: [url]
      properties:
        url: {type: string, description: "Public URL, mm_file:// file ID, or Base64 data URI."}
    MiniMaxV2Task:
      type: object
      properties:
        id: {type: string}
        model: {const: MiniMax-H3}
        status: {type: string, enum: [queued, running, succeeded, failed, cancelled]}
        created_at: {type: integer, format: int64}
        updated_at: {type: integer, format: int64}
        content:
          type: object
          properties: {url: {type: string, format: uri}}
        resolution: {type: string}
        duration: {type: integer}
        ratio: {type: string}
        task_type: {const: generation}
        modality: {const: video}
        usage: {type: object, additionalProperties: true}
        error: {$ref: '#/components/schemas/JobError'}
    OpenAIVideo:
      type: object
      required: [id, object, created_at, status, model, progress, seconds, size]
      properties:
        id: {type: string}
        object: {const: video}
        created_at: {type: integer, format: int64}
        status: {type: string, enum: [queued, in_progress, completed, failed]}
        model: {type: string}
        progress: {type: integer, minimum: 0, maximum: 100}
        seconds: {type: string}
        size: {type: string}
        quality: {type: string, enum: [native, sage, te-speed]}
        error: {$ref: '#/components/schemas/JobError'}
    NativeVideo:
      type: object
      required: [id, object, status, mode, width, height, requested_seconds, frames, fps, actual_seconds]
      properties:
        id: {type: string}
        object: {const: minimax_h3.video}
        status: {type: string, enum: [queued, in_progress, completed, failed]}
        prompt: {type: string}
        mode: {type: string, enum: [native, sage, te-speed]}
        width: {type: integer}
        height: {type: integer}
        requested_seconds: {type: number}
        frames: {type: integer}
        fps: {type: integer}
        actual_seconds: {type: number}
        seed: {type: integer, format: int64}
        steps: {type: integer}
        processing_seconds: {type: number}
        gpu_hours: {type: number}
        gpu_hourly_rate_rmb: {type: number}
        peak_vram_mib: {type: integer}
        peak_ram_mib: {type: integer}
        cost_rmb: {type: number}
        cost_per_output_second_rmb: {type: number}
        download_url: {type: string, format: uri}
        created_at: {type: string, format: date-time}
        updated_at: {type: string, format: date-time}
        error: {$ref: '#/components/schemas/JobError'}
    JobError:
      type: object
      properties:
        code: {type: string}
        message: {type: string}
    NativeError:
      type: object
      properties:
        error:
          type: object
          properties:
            code: {type: string}
            message: {type: string}
    OpenAIError:
      type: object
      properties:
        error:
          type: object
          properties:
            message: {type: string}
            type: {type: string}
            param: {type: [string, 'null']}
            code: {type: [string, 'null']}
    MiniMaxBaseResponse:
      type: object
      required: [status_code, status_msg]
      properties:
        status_code: {type: integer}
        status_msg: {type: string}
