AI3D Studio Capabilities API

openapi: 3.2.0
info:
  title: AI3D Studio Capabilities API
  version: 1.0.0
  description: Public, API-key-authenticated endpoints for AI generation. Authenticate with your `sk-` key as a Bearer token (or `x-api-key`). Generation bills credits to the key’s account.
servers:
- url: https://ai3d.studio/v1
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Capabilities
paths:
  /capabilities:
    get:
      operationId: getCapabilities
      x-required-scope: read
      summary: List available models and tools
      description: 'The catalog of generation models/tools this key’s app exposes, with the form of each model scene (`form`: every field, its kind, limits, options and rules, labelled in the `Accept-Language` locale). The response carries an `ETag`: send it back as `If-None-Match` and an unchanged catalog answers `304`. A model that is one release of a product line (Meshy 7.1, Meshy 6) carries `family`, `version`, `latest` (false on an older release) and, when its provider has announced an end, `retiresAt`; every release is an ordinary model id. `generation.presets` lists the image presets (figurine, style, pose, convert) an app with Image Maker offers: each has an `id` to send as `options.preset`, the pictures it takes, its `addons`, whether the background is a choice, and the `models` it runs on. `generation.batches` lists the scenes the app runs as a batch (`POST /batches`): the `models` each may name, the option field a picture fills (`inputField`) and the most pictures any plan may batch. The form shape is versioned (`generation.version`): send `form-contract` with the versions your client reads (comma-separated, e.g. `4`) to be served the newest of them; without it you get the default version, which moves on only after its announced sunset. The response names the version it served in `form-contract`, and a version scheduled to go carries `Deprecation` (RFC 9745), `Sunset` (RFC 8594) and `Link rel="deprecation"`.'
      parameters:
      - name: form-contract
        in: header
        required: false
        description: Form contract versions this client reads, newest first.
        schema:
          type: string
          example: '4'
      responses:
        '200':
          description: Capability catalog
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 'None of the form contract versions named in `form-contract` is still served: `data.code = "client_upgrade_required"` and `data.servableContracts` lists the ones that are.'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      - oauth2:
        - read
      tags:
      - Capabilities
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
          example: -1
        message:
          type: string
      required:
      - code
      - message
  responses:
    Unauthorized:
      description: Missing, malformed, or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your `sk-` API key (`sk-[A-Za-z0-9]{38}`, checksummed) presented as a Bearer token. API access is a plan right (see pricing); a plan that does not include it answers 403 `plan_required`.
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Your `sk-` API key in the `x-api-key` header.
    oauth2:
      type: oauth2
      description: 'OAuth 2.1 for an agent acting for a signed-in account: the authorization code flow with PKCE (S256), or client credentials for a client registered from the dashboard. Send the RFC 8707 `resource` parameter `https://ai3d.studio/v1` on the authorization and token requests: a token minted for another resource, the MCP server included, is refused here. Authorization server metadata: `https://ai3d.studio/.well-known/oauth-authorization-server`.'
      flows:
        authorizationCode:
          authorizationUrl: https://ai3d.studio/api/auth/oauth2/authorize
          tokenUrl: https://ai3d.studio/api/auth/oauth2/token
          refreshUrl: https://ai3d.studio/api/auth/oauth2/token
          scopes:
            read: Read the account, models, quotes, runs, batches and the Library.
            generate: Start runs that spend credits, and file new creations in the Library.
        clientCredentials:
          tokenUrl: https://ai3d.studio/api/auth/oauth2/token
          scopes:
            read: Read the account, models, quotes, runs, batches and the Library.
            generate: Start runs that spend credits, and file new creations in the Library.