ViewMax Studio Advanced API

openapi: 3.2.0
info:
  title: ViewMax Studio Advanced 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: Advanced
  description: Workflows whose inputs are created in the ViewMax web app.
paths:
  /api/v1/shorts-studio:
    post:
      operationId: createShortsStudioTask
      tags:
      - Advanced
      summary: Compose a segmented video into a styled Short
      description: Advanced. `segmentationTaskId` and `transcriptTaskId` come from person-segmentation and Auto Captions tasks created in the ViewMax web app; the REST API cannot create them. Applies a fixed preset and returns an asynchronous task (202) or the existing task for a repeated `requestId` (200). Costs 1 credit. Poll with GET on this path.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShortsStudioRequest'
      responses:
        '200':
          description: Existing task for this `requestId`.
          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/ShortsStudioTask'
        '202':
          description: Task accepted; poll it.
          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/ShortsStudioTask'
        '400':
          description: '`invalid_request`: body is not valid JSON or does not match the schema.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortsStudioError'
        '401':
          description: '`unauthorized`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortsStudioError'
        '402':
          description: '`insufficient_credits`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortsStudioError'
        '404':
          description: '`task_not_found`: segmentation or transcript task is not visible to this account.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortsStudioError'
        '409':
          description: '`request_conflict`: `requestId` was already used with a different body.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortsStudioError'
        '413':
          description: '`invalid_request`: body over 750,000 characters.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortsStudioError'
        '422':
          description: '`segmentation_not_ready`, `transcript_not_ready`, `transcript_mismatch`, `words_or_transcript_required`, or `credit_limit_exceeded`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortsStudioError'
        '500':
          description: '`processing_failed`, including word timings that do not fit the source video.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortsStudioError'
    get:
      operationId: getShortsStudioTask
      tags:
      - Advanced
      summary: Poll a Shorts Studio task
      description: Send exactly one of `taskId` or `requestId`.
      parameters:
      - name: taskId
        in: query
        schema:
          type: string
      - name: requestId
        in: query
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Task status and artifacts.
          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/ShortsStudioTask'
        '400':
          description: '`invalid_request`: neither or both query parameters were sent.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortsStudioError'
        '401':
          description: '`unauthorized`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortsStudioError'
        '404':
          description: '`task_not_found`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortsStudioError'
        '500':
          description: '`processing_failed`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShortsStudioError'
components:
  schemas:
    ShortsStudioError:
      type: object
      required:
      - code
      - message
      description: Shorts Studio errors carry a machine-readable `message` and no `error` object.
      properties:
        code:
          type: integer
          description: '`-1`, `-1001` unauthorized, or `-1002` insufficient credits.'
        message:
          type: string
          enum:
          - unauthorized
          - invalid_request
          - insufficient_credits
          - task_not_found
          - request_conflict
          - segmentation_not_ready
          - transcript_not_ready
          - transcript_mismatch
          - words_or_transcript_required
          - credit_limit_exceeded
          - processing_failed
    ShortsStudioRequest:
      type: object
      additionalProperties: false
      required:
      - requestId
      - segmentationTaskId
      - creditLimit
      properties:
        requestId:
          type: string
          format: uuid
          description: Client-generated idempotency id. The same id with the same body returns the existing task; with a different body it returns 409 `request_conflict`.
        segmentationTaskId:
          type: string
          minLength: 1
          maxLength: 100
          description: Successful person-segmentation task created in the ViewMax web app.
        transcriptTaskId:
          type: string
          minLength: 1
          maxLength: 100
          description: Successful Auto Captions task created in the ViewMax web app for the same source video. Required when `words` is omitted.
        words:
          type: array
          minItems: 1
          maxItems: 4000
          description: Word-level captions. Required when `transcriptTaskId` is omitted.
          items:
            type: object
            additionalProperties: false
            required:
            - text
            - startMs
            - endMs
            properties:
              text:
                type: string
                minLength: 1
                maxLength: 100
              startMs:
                type: integer
                minimum: 0
              endMs:
                type: integer
                minimum: 1
              speakerId:
                type: string
                maxLength: 80
        preset:
          type: string
          enum:
          - comic_energy
          - paper_collage
          - product_clean
          default: comic_energy
        outputRatio:
          type: string
          enum:
          - '9:16'
          - '16:9'
          default: '9:16'
        backgroundColor:
          type: string
          pattern: ^#[a-fA-F0-9]{6}$
          default: '#15202b'
        includeSrt:
          type: boolean
          default: true
        includeAss:
          type: boolean
          default: false
        creditLimit:
          type: integer
          minimum: 1
          maximum: 100
          description: Most credits this request may spend. The task costs 1 credit.
    ShortsStudioTask:
      type: object
      required:
      - id
      - status
      - phase
      - costCredits
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - pending
          - processing
          - success
          - failed
          - canceled
        phase:
          type: string
          enum:
          - queued
          - rendering
          - completed
          - failed
        costCredits:
          type: integer
        preset:
          type: string
          enum:
          - comic_energy
          - paper_collage
          - product_clean
        outputRatio:
          type: string
          enum:
          - '9:16'
          - '16:9'
        videoUrl:
          type: string
          format: uri
          description: Preview MP4, present on success.
        artifacts:
          type: array
          description: Present on success.
          items:
            type: object
            required:
            - kind
            - role
            - url
            - contentType
            properties:
              kind:
                type: string
                enum:
                - video
                - text
              role:
                type: string
                enum:
                - preview
                - srt
                - ass
              url:
                type: string
                format: uri
              contentType:
                type: string
                enum:
                - video/mp4
                - application/x-subrip
                - text/x-ass
        error:
          type: string
          enum:
          - processing_failed
          description: Present when the task failed.
  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