ViewMax Studio Catalog API

openapi: 3.2.0
info:
  title: ViewMax Studio Catalog API
  summary: Public REST API for ViewMax Studio media generation.
  description: 'Create video, image, music, speech, and sound-effect tasks with a ViewMax API key, then poll GET /api/v1/tasks/{taskId} every 5–10 seconds until `success`, `failed`, or `canceled`.


    GET /api/v1/models and GET /api/v1/voices are public. Every other endpoint needs `Authorization: Bearer sk-...`; keys have full access to the account and REST does not check scopes. OAuth applies to the MCP server only.


    Credits are deducted when a task is created; `failed` and `canceled` tasks are refunded automatically. Send an `Idempotency-Key` header so a retried POST returns the original task instead of charging again.


    `/api/v1` sends no CORS headers: call it from a server.'
  version: 1.1.0
  contact:
    name: ViewMax Studio
    email: support@viewmax.studio
    url: https://viewmax.studio/developers
  license:
    name: ViewMax API terms
    url: https://viewmax.studio/terms-of-service
servers:
- url: https://viewmax.studio
  description: ViewMax Studio production
security:
- bearerAuth: []
tags:
- name: Catalog
  description: Public model and voice discovery.
paths:
  /api/v1/models:
    get:
      operationId: listModels
      tags:
      - Catalog
      summary: List generation models
      description: Public catalog of video, image, or music models with modes, accepted option values, defaults, and credit pricing. No API key required. Cached for up to an hour.
      security: []
      parameters:
      - name: type
        in: query
        required: false
        description: Catalog to return. Defaults to `video`; unknown values return the video catalog.
        schema:
          type: string
          enum:
          - video
          - image
          - music
          default: video
      responses:
        '200':
          description: 'Model catalog. The item shape depends on `type`: VideoModel, ImageModel, or MusicModel.'
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                - data
                properties:
                  code:
                    type: integer
                    enum:
                    - 0
                  message:
                    type: string
                    enum:
                    - ok
                  data:
                    type: object
                    required:
                    - models
                    properties:
                      models:
                        type: array
                        items:
                          oneOf:
                          - $ref: '#/components/schemas/VideoModel'
                          - $ref: '#/components/schemas/ImageModel'
                          - $ref: '#/components/schemas/MusicModel'
  /api/v1/voices:
    get:
      operationId: listVoices
      tags:
      - Catalog
      summary: List text-to-speech voices
      description: Public catalog of voices for POST /api/v1/speech, with the speech pricing rule. No API key required. Cached for up to an hour.
      security: []
      responses:
        '200':
          description: Voice catalog.
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                - message
                - data
                properties:
                  code:
                    type: integer
                    enum:
                    - 0
                  message:
                    type: string
                    enum:
                    - ok
                  data:
                    $ref: '#/components/schemas/VoiceCatalog'
components:
  schemas:
    VoiceCatalog:
      type: object
      required:
      - default_model
      - characters_per_credit
      - minimum_credits
      - voices
      properties:
        default_model:
          type: string
        characters_per_credit:
          type: integer
          description: Speech costs `max(minimum_credits, ceil(text characters / characters_per_credit))`.
        minimum_credits:
          type: integer
        voices:
          type: array
          items:
            $ref: '#/components/schemas/Voice'
    ImageModel:
      type: object
      required:
      - id
      - label
      - vendor
      - description
      - modes
      - credits_label
      properties:
        id:
          type: string
          description: Send as `model`.
        label:
          type: string
        vendor:
          type: string
        description:
          type: string
        modes:
          type: object
          description: 'Keyed by scene: `text-to-image`, `image-to-image`.'
          additionalProperties:
            $ref: '#/components/schemas/ImageModelMode'
        credits_label:
          type: string
    MusicModel:
      type: object
      required:
      - id
      - label
      - vendor
      - description
      - controls
      - credits
      properties:
        id:
          type: string
        label:
          type: string
        vendor:
          type: string
        description:
          type: string
        controls:
          type: object
          description: Accepted `options` for POST /api/v1/music.
        credits:
          type: integer
          description: 'Price for tracks up to 60 s. Longer tracks cost 1 credit per second: `max(60, ceil(duration_seconds))`.'
    Voice:
      type: object
      required:
      - id
      - name
      - language
      properties:
        id:
          type: string
          description: Send as `voice_id`.
        name:
          type: string
        gender:
          type: string
        language:
          type: string
        languages:
          type: array
          items:
            type: string
        accent:
          type: string
        use_case:
          type: string
        description:
          type: string
        preview_url:
          type: string
          format: uri
        recommended_model:
          type: string
          description: Default `options.model_id` for this voice.
    VideoModel:
      type: object
      required:
      - id
      - label
      - vendor
      - description
      - modes
      - credits_label
      - coming_soon
      properties:
        id:
          type: string
          description: Send as `model`.
        label:
          type: string
        vendor:
          type: string
        description:
          type: string
        modes:
          type: object
          description: Keyed by mode id; only supported modes are present.
          additionalProperties:
            $ref: '#/components/schemas/VideoModelMode'
        credits_label:
          type: string
        coming_soon:
          type: boolean
        max_prompt_length:
          type: integer
          description: Longest accepted prompt in characters, after trimming. Absent when the model sets none.
    VideoModelMode:
      type: object
      required:
      - durations
      - resolutions
      - aspect_ratios
      - audio_toggle
      - defaults
      properties:
        durations:
          type: array
          items:
            type: string
          description: 'Accepted `options.duration` values. Empty: omit it.'
        resolutions:
          type: array
          items:
            type: string
          description: 'Accepted `options.resolution` values. Empty: omit it.'
        aspect_ratios:
          type: array
          items:
            type: string
          description: 'Accepted `options.aspect_ratio` values (exact case). Empty: omit it.'
        audio_toggle:
          type: boolean
          description: '`options.audio: true` is accepted only when this is true.'
        defaults:
          type: object
          description: Values filled in, priced and submitted when the request omits them. Only keys the mode supports are present.
          properties:
            duration:
              type: string
            resolution:
              type: string
            aspect_ratio:
              type: string
        credits:
          type: object
          description: 'Fixed prices: `credits[resolution][duration]`, `credits[resolution].per_generation`, `credits[duration]["with-audio"|"without-audio"]`, or `credits[quality][duration]`.'
          additionalProperties:
            type: object
            additionalProperties:
              type: number
        credits_per_second:
          type: object
          additionalProperties:
            type: number
          description: 'Per-second price by resolution: `ceil(rate × duration seconds)`.'
        credits_per_second_with_video_input:
          type: object
          additionalProperties:
            type: number
          description: Per-second price by resolution when `video_urls` is sent. Seedance 2.x bills output plus source seconds (source capped at 15 s).
        pricing_note:
          type: string
    ImageModelMode:
      type: object
      required:
      - aspect_ratios
      - qualities
      properties:
        aspect_ratios:
          type: array
          items:
            type: string
          description: Suggested `options.aspect_ratio` values. An unknown value is replaced by the default (or passed through when the model validates none).
        qualities:
          type: array
          items:
            type: string
          description: Accepted `options.quality` values (case-insensitive). An unknown value becomes the first entry and is billed at that price, except GPT Image 2.5, which returns 400.
        resolutions:
          type: array
          items:
            type: string
          description: GPT Image 2.5 `options.resolution` values.
        credits:
          type: object
          additionalProperties:
            type: number
          description: Price by quality.
        credits_per_generation:
          type: number
        credits_by_resolution_and_aspect_ratio:
          type: object
          description: 'GPT Image 2.5: `credits[resolution][aspect_ratio][quality]`.'
          additionalProperties:
            type: object
            additionalProperties:
              type: object
              additionalProperties:
                type: number
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'ViewMax API key from Settings → API Keys (`sk-` followed by 32 letters and digits). Send `Authorization: Bearer sk-...`. Every key has full access to its account; REST does not check scopes and has no per-key rate limit.'
    oauth2:
      type: oauth2
      description: 'OAuth 2.0 for the ViewMax MCP server (`/api/mcp`) only. REST endpoints accept API keys, not OAuth tokens. Discovery: `/.well-known/oauth-protected-resource/api/mcp` and `/.well-known/oauth-authorization-server/api/auth`.'
      flows:
        authorizationCode:
          authorizationUrl: https://viewmax.studio/api/auth/oauth2/authorize
          tokenUrl: https://viewmax.studio/api/auth/oauth2/token
          refreshUrl: https://viewmax.studio/api/auth/oauth2/token
          scopes:
            models:read: Read the public model and voice catalogs without creating generation tasks.
            tasks:read: Read generation task status and output URLs for the authenticated account.
            tasks:write: Create credit-consuming video, image, music, speech, and sound-effect tasks.
            credits:read: Read the remaining credit balance for the authenticated account.
externalDocs:
  description: ViewMax API documentation
  url: https://viewmax.studio/docs/api
x-viewmax-mcp:
  url: https://viewmax.studio/api/mcp
  transport: streamable-http
  serverCard: https://viewmax.studio/server-card