ViewMax Studio Account API

openapi: 3.2.0
info:
  title: ViewMax Studio Account 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: Account
  description: Credit balance for the authenticated key.
paths:
  /api/v1/credits:
    get:
      operationId: getCredits
      tags:
      - Account
      summary: Get remaining credits
      description: Return the credit balance of the account that owns the API key.
      responses:
        '200':
          description: Credit balance.
          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:
                    - remainingCredits
                    properties:
                      remainingCredits:
                        type: number
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: 'Missing or invalid API key (`code: -1001`).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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