GenMagic Videos API

openapi: 3.2.0
info:
  title: GenMagic Videos API
  version: 1.0.0
  description: 'GenMagic is one studio for every generative AI model. Turn a single prompt into text, images, video, audio, music, or code, and route it to the best model automatically. New models the day they launch.


    OpenAI-compatible REST API plus a remote Model Context Protocol server at /api/mcp (Streamable HTTP, protocol 2025-06-18). Authenticate with an API key minted at https://genmagic.co/get-api-key; the model catalog (GET /api/v1/models) also answers without one. Billed pay-as-you-go against a prepaid USD balance; cost and remaining balance are returned in response headers.'
servers:
- url: https://genmagic.co
security:
- bearerAuth: []
tags:
- name: Videos
paths:
  /api/v1/videos:
    post:
      operationId: createVideo
      summary: Start an asynchronous video job
      description: 'Returns 202 immediately with { id, object: "video.generation", model, status: "queued", created (Unix seconds), status_url }; nothing is charged until the clip completes. Poll GET /api/v1/videos/{id} until status is completed or failed. Also OpenAI''s Videos API: a multipart request (what the OpenAI SDKs'' client.videos.create sends) or one with seconds, size or input_reference is answered with OpenAI''s Video object, an id starting video_, at HTTP 200, so code written for Sora 2''s Videos API runs unchanged with a GenMagic model id; a request that still names sora-2 runs on google/veo-3.1-fast and sora-2-pro on google/veo-3.1 (the answer''s model says which ran).'
      security:
      - bearerAuth: []
      responses:
        '202':
          description: 'Accepted: async job created.'
          headers:
            X-RateLimit-Limit:
              schema:
                type: string
              description: The key's request quota for the current rate-limit window.
            X-RateLimit-Remaining:
              schema:
                type: string
              description: Requests left for this key in the current rate-limit window.
            X-RateLimit-Reset:
              schema:
                type: string
              description: Seconds until the current rate-limit window resets.
            Location:
              schema:
                type: string
              description: The status URL to poll (GET) for the asynchronous job's result. Mirrors `status_url` in the body.
        '401':
          description: 'authentication_error: missing or invalid API key.'
        '402':
          description: 'insufficient_quota: credit balance would go negative.'
        '429':
          description: 'rate_limit_error: over 300 requests/minute for this key.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                prompt:
                  type: string
                  description: Description of the video.
                model:
                  type: string
                  description: Model id. Omit for the default. Must be a text-to-video model (capabilities.text_to_video in GET /api/v1/models?category=video); a model that edits, upscales or animates supplied media is refused with 400 model_not_supported.
                aspect_ratio:
                  type: string
                  enum:
                  - '16:9'
                  - '9:16'
                  - '1:1'
                  description: Defaults to the opening image's shape when `image` is portrait (9:16) or landscape (16:9), otherwise 16:9.
                duration:
                  type: integer
                  description: Clip length in seconds, one of the model's pricing.video.durations_seconds in GET /api/v1/models?category=video. Omit for the model's default (usually 5). The price scales with it.
                resolution:
                  type: string
                  description: 'One of the model''s pricing.video.resolutions, for example 720p. Omit for the model''s default. The price scales with it: pricing.video.usd_per_second lists the rate at each resolution.'
                generate_audio:
                  type: boolean
                  description: Whether to add sound, for a model whose pricing.video.audio_supported is true. Omit for the model's default; sound can roughly double the price (pricing.video.usd_per_second_with_audio). A model with pricing.video.audio_always true makes sound on every clip and has no switch.
                image:
                  type: string
                  description: 'Image-to-video: an https URL or data:image URL the clip opens on; the prompt then describes the motion. For a model whose capabilities.frame_images includes first_frame (400 model_not_supported otherwise, 400 invalid_image for an unusable image). Most models bill it like text-to-video; where one does not, its pricing.video carries image_to_video_usd_per_second (a rate of its own) or image_input_usd (a fee for each image supplied).'
                last_frame:
                  type: string
                  description: An https URL or data:image URL the clip ends on, for a model whose capabilities.frame_images includes last_frame.
                references:
                  type: array
                  items:
                    type: string
                  description: 'Reference-to-video: up to 9 https URLs or data:image URLs of characters, objects or a look the clip keeps consistent, none of them a frame of it. Name what each shows in the prompt ("the doctor from the first reference walks through the door from the second"). Not combined with image or last_frame (400 invalid_image). Models made for it have capabilities.references true; each image may carry the model''s image_input_usd.'
                seconds:
                  type: string
                  description: OpenAI Videos API form of duration ("8"). duration wins when both are sent; the model's own lengths apply as for duration.
                size:
                  type: string
                  description: OpenAI Videos API form of aspect_ratio and resolution, width x height ("1280x720" is 16:9 at 720p, "720x1280" 9:16, "1792x1024" 16:9 at 1080p). aspect_ratio and resolution win when sent.
                input_reference:
                  type: string
                  description: 'OpenAI Videos API form of image: an uploaded image file (multipart), an https or data:image URL, or { "image_url": "..." }. An OpenAI file_id cannot be read and is refused (400 invalid_image).'
      tags:
      - Videos
  /api/v1/videos/{id}:
    get:
      operationId: getVideo
      summary: Poll a video job
      description: 'Returns { id, object, model, status } with status queued or processing while the clip renders; when completed it adds the durable hosted url and cost_cents. A render failure is a terminal failed status at HTTP 200 with error, a plain-text message. Charged once, on completion. An id starting video_ (from an OpenAI-style create) is answered with OpenAI''s Video object instead: status queued, in_progress, completed or failed, progress, created_at, and error as { code, message }. This is a lookup and spends no credits.'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success.
          headers:
            X-RateLimit-Limit:
              schema:
                type: string
              description: The key's request quota for the current rate-limit window.
            X-RateLimit-Remaining:
              schema:
                type: string
              description: Requests left for this key in the current rate-limit window.
            X-RateLimit-Reset:
              schema:
                type: string
              description: Seconds until the current rate-limit window resets.
            X-Cost-Cents:
              schema:
                type: string
              description: What this call cost, in US cents (may be fractional). Provider-authoritative when the provider reports a cost, else the metered estimate. Omitted when the cost is unknown or deliberately not disclosed (the OpenAI-compatible chat passthrough hides it).
            X-Credits-Remaining:
              schema:
                type: string
              description: The key owner's prepaid balance in US cents remaining after this call. Omitted when the balance cannot be read.
        '401':
          description: 'authentication_error: missing or invalid API key.'
        '429':
          description: 'rate_limit_error: over 300 requests/minute for this key.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: The job id from POST /api/v1/videos.
        description: The job id from POST /api/v1/videos.
      tags:
      - Videos
  /api/v1/videos/{id}/content:
    get:
      operationId: downloadVideoContent
      summary: Download a finished clip
      description: 'OpenAI''s Videos API download (client.videos.download_content): redirects (302) to the finished clip''s durable file. 409 video_not_ready while it renders, 409 video_failed for a failed job. Only the clip exists: variant=thumbnail or spritesheet answers 404. Works with either id form. This is a lookup and spends no credits.'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success.
          headers:
            X-RateLimit-Limit:
              schema:
                type: string
              description: The key's request quota for the current rate-limit window.
            X-RateLimit-Remaining:
              schema:
                type: string
              description: Requests left for this key in the current rate-limit window.
            X-RateLimit-Reset:
              schema:
                type: string
              description: Seconds until the current rate-limit window resets.
            Location:
              schema:
                type: string
              description: The status URL to poll (GET) for the asynchronous job's result. Mirrors `status_url` in the body.
        '401':
          description: 'authentication_error: missing or invalid API key.'
        '429':
          description: 'rate_limit_error: over 300 requests/minute for this key.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: The job id from POST /api/v1/videos (with or without the video_ prefix).
        description: The job id from POST /api/v1/videos (with or without the video_ prefix).
      tags:
      - Videos
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'GenMagic API key in the form gm_live_..., sent as Authorization: Bearer <key>. Also accepted as x-api-key.'