VidPlate Account API

openapi: 3.2.0
info:
  title: VidPlate Account API
  version: v1
  summary: Render video and images from your own templates, on your own machines.
  description: 'Server-to-server only: send your secret key as "Authorization: Bearer vpk_live_...". Requests from a browser are refused, and a secret key must never be put in a web page or an app.


    Every response carries X-Request-Id. Errors use one shape (see the Error schema) with stable codes. Lists use cursor pagination: pass next_cursor as starting_after.


    Rate limits are per key and per workspace, with RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers, and Retry-After on 429.


    Renders run on your workspace''s own Browser Nodes (the render-nodes endpoints) and are not charged per render; paid API plans have a daily render limit and a monthly video-minutes allowance (429 quota_exceeded and 429 video_minutes_exceeded); Studio Pro has 10,000 static outputs and 2,000 video minutes a calendar month (429 static_outputs_exceeded and 429 video_minutes_exceeded) plus a daily safety limit (429 quota_exceeded); the Sandbox has one-off totals for its whole trial (402 sandbox_allowance_used). Webhooks are signed (VidPlate-Signature: t=..., v1=HMAC-SHA256 of "t.body") and carry IDs and statuses only.'
servers:
- url: https://api.vidplate.app/v1
  description: VidPlate API
- url: https://vidplate.app/api/v1
  description: Legacy base URL. It keeps working for existing integrations.
security:
- apiKey: []
tags:
- name: Account
  description: Health and the key in use.
paths:
  /health:
    get:
      operationId: getHealth
      tags:
      - Account
      summary: Check the API is up
      security: []
      responses:
        '200':
          description: The API is up.
          content:
            application/json:
              schema:
                type: object
              example:
                status: ok
                api_version: v1
                time: '2026-11-02T09:00:00.000Z'
                request_id: req_...
  /openapi.json:
    get:
      operationId: getOpenApiSpec
      tags:
      - Account
      summary: This OpenAPI 3.1 document
      security: []
      responses:
        '200':
          description: The OpenAPI document.
          content:
            application/json:
              schema:
                type: object
  /me:
    get:
      operationId: getKeyContext
      tags:
      - Account
      summary: The key's workspace, scopes, restrictions and quotas
      description: 'quotas.renders_per_day is today''s render count (UTC day); its limit is null when there is no daily cap (the Sandbox), and on Studio Pro it is a safety limit, not the allowance. quotas.video_minutes_per_month is this calendar month''s video minutes (UTC): limit, used (delivered), reserved (renders still running), remaining and resets_at (period ''trial'' and resets_at null for the Sandbox''s one-off total). quotas.static_outputs_per_month (Studio Pro only, otherwise null) is the same for static outputs: each format x variant counts 1. quotas.sandbox_allowance (Sandbox only, otherwise null) holds the one-off renders and video minutes for the whole trial, never reset. Test keys report their own meter (in the Sandbox they share the one-off totals).'
      security:
      - apiKey: []
      x-required-scopes: []
      responses:
        '200':
          description: The key in use.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: 'Error. Codes: invalid_api_key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: authentication_failed
                  code: invalid_api_key
                  message: '...'
                  request_id: req_0123456789abcdef01234567
        '403':
          description: 'Error. Codes: missing_scope, plan_not_eligible.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: permission_denied
                  code: missing_scope
                  message: '...'
                  request_id: req_0123456789abcdef01234567
        '429':
          description: 'Error. Codes: too_many_requests.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: rate_limited
                  code: too_many_requests
                  message: '...'
                  request_id: req_0123456789abcdef01234567
        '500':
          description: 'Error. Codes: internal_error.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  type: api_error
                  code: internal_error
                  message: '...'
                  request_id: req_0123456789abcdef01234567
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - type
          - code
          - message
          - request_id
          properties:
            type:
              enum:
              - invalid_request
              - payment_required
              - authentication_failed
              - permission_denied
              - not_found
              - conflict
              - unprocessable
              - rate_limited
              - api_error
              - service_unavailable
            code:
              type: string
              description: Stable, documented code.
            message:
              type: string
            param:
              type: string
              description: The request field the error is about, when there is one.
            errors:
              type: array
              description: Every problem found (schema_validation_failed).
              items:
                type: object
                properties:
                  param:
                    type: string
                  code:
                    type: string
                  message:
                    type: string
            request_id:
              type: string
              description: Quote this when asking for help.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: vpk_live_...
      description: 'Workspace keys, created by workspace admins in VidPlate under Admin, then API. Scopes: templates:read (List templates, versions and their input schemas.); uploads:write (Upload images and video to use in renders.); renders:write (Create, cancel and retry renders.); renders:read (Check render status and download outputs.); webhooks:manage (Register and change webhook endpoints.); assets:read (Use Asset Library files as render inputs.); ai:spend (Allow renders that use AI voiceover or AI Recipes. These spend your AI credits.); render_nodes:read (See whether your render nodes are online, busy or offline, and what they can render.); storage_destinations:manage (Add, change, test and delete your own buckets that outputs are delivered to (Growth and above).)'