ViewMax Studio Tasks API

openapi: 3.2.0
info:
  title: ViewMax Studio Tasks 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: Tasks
  description: Poll generation tasks.
paths:
  /api/v1/tasks/{taskId}:
    get:
      operationId: getTask
      tags:
      - Tasks
      summary: Get a generation task
      description: 'Read status and result URLs. Each call checks the provider live; poll every 5–10 seconds while `pending` or `processing`. There is no server-side timeout, so set your own deadline. A 500 while polling is transient: keep polling. Any key of the account can read every task of the account.'
      parameters:
      - name: taskId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: Transient status check failure. Keep polling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  responses:
    Task:
      description: Task created, or the existing task for a repeated `Idempotency-Key`.
      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/Task'
    NotFound:
      description: Task does not exist or belongs to another account (`task not found`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: 'Missing or invalid API key (`code: -1001`).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Task:
      type: object
      description: Generation task. Returned by every create endpoint and by GET /api/v1/tasks/{taskId}.
      required:
      - id
      - status
      - mediaType
      - costCredits
      - taskUrls
      properties:
        id:
          type: string
          description: Task id. Poll GET /api/v1/tasks/{taskId} with it.
        status:
          type: string
          enum:
          - pending
          - processing
          - success
          - failed
          - canceled
          description: '`pending`/`processing`: keep polling. `success`: read `taskUrls`. `failed`/`canceled`: terminal, credits refunded.'
        mediaType:
          type: string
          enum:
          - video
          - image
          - music
          - audio
        scene:
          type: string
          description: Mode or scene, e.g. `text-to-video`, `text-to-image`, `text-to-music`, `text-to-speech`, `text-to-sound-effects`.
        model:
          type: string
          description: Model identifier used for the job. May differ from the catalog id sent in the request.
        prompt:
          type: string
        options:
          type:
          - string
          - 'null'
          description: JSON-encoded options as priced and submitted, including filled-in defaults and `mode` for video.
        taskUrls:
          type: array
          items:
            type: string
            format: uri
          description: Result URLs. Empty until the task succeeds.
        costCredits:
          type: integer
          description: Credits charged. `0` when a plan allowance covered it.
        waivedCredits:
          type: integer
          description: Normal price waived by a plan allowance; otherwise `0`.
        fairUseKey:
          type:
          - string
          - 'null'
          description: Plan allowance slot used by this task, or `null`.
        taskInfo:
          type:
          - string
          - 'null'
          description: JSON string. While pending/processing/success it holds job diagnostics whose shape is not stable. On `failed`/`canceled` it is `{"errorCode","error","errorMessage"}`; `errorCode` is one of `insufficient_credits`, `auth_required`, `rate_limited`, `request_cancelled`, `provider_unavailable`, `invalid_input`, `content_rejected`, `busy`, `duplicate_request`, `generic`. `errorMessage` carries the provider's reason only for `invalid_input`.
        taskResult:
          type:
          - string
          - 'null'
          description: JSON string. Same failure payload as `taskInfo` on `failed`/`canceled`; otherwise job diagnostics with no stable shape.
        taskId:
          type:
          - string
          - 'null'
          description: Upstream job id (diagnostic only).
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        userId:
          type: string
        creditId:
          type:
          - string
          - 'null'
        visibility:
          type: string
        deletedAt:
          type:
          - string
          - 'null'
          format: date-time
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
      - code
      - message
      - error
      properties:
        code:
          type: integer
          description: '`-1` for most errors, `-1001` unauthorized, `-1002` insufficient credits.'
        message:
          type: string
        error:
          type: object
          additionalProperties: false
          required:
          - type
          - hint
          - docs
          properties:
            type:
              type: string
              enum:
              - unauthorized
              - invalid_request
              - insufficient_credits
              - not_found
              - content_rejected
              - internal_error
            hint:
              type: string
              description: What to do next, including whether retrying the same request can help.
            docs:
              type: string
              format: uri
            task_id:
              type: string
              description: Present when the request created a task before failing. The task is `failed` and refunded, or still `pending` when the provider outcome is unknown (poll it instead of retrying).
  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