AI3D Studio Quote API

openapi: 3.2.0
info:
  title: AI3D Studio Quote 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: Quote
paths:
  /quote:
    post:
      operationId: quote
      x-required-scope: read
      summary: Price a generation without starting it
      description: What `POST /generate` would charge for the same body, from the same validation and price calculation. Nothing is charged and nothing is started. Send the answer’s `credits` back to `/generate` as `expectedCredits`. A body generate would refuse is refused here with the same `data.code`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerationRequest'
      responses:
        '200':
          description: The price
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      credits:
                        type: number
                        description: 'What generate charges: per output × outputs.'
                      creditsPerOutput:
                        type: number
                      outputs:
                        type: integer
                    required:
                    - credits
                    - creditsPerOutput
                    - outputs
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: A body generate would refuse, with the same `data.code`.
        '429':
          description: Rate limited
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      - oauth2:
        - read
      tags:
      - Quote
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
          example: -1
        message:
          type: string
      required:
      - code
      - message
    GenerationRequest:
      type: object
      required:
      - mediaType
      - model
      additionalProperties: true
      properties:
        mediaType:
          type: string
          description: Generation family, e.g. 'image' | 'video' | 'music' (see /capabilities for the exact values your app exposes).
        model:
          type: string
        prompt:
          type: string
          description: 'The prompt. With `options.preset` it is only your additional instructions (at most 500 characters): the server composes the preset’s own text.'
        options:
          type: object
          additionalProperties: true
          description: 'Model-specific options; derive them from /capabilities (`form` per model: each scene''s fields with their kind, value type, limits, options and rules). To run an image preset send mediaType `image`, scene `image-to-image`, `image` (the subject, then an optional reference), `preset` (an id from `generation.presets`), and optionally `preset_addons` (addon ids) and `preset_background` (`plain` or `keep`). A preset adds no cost: it is priced as the model it runs on.'
        scene:
          type: string
        workflowType:
          type: string
        expectedCredits:
          type: integer
          minimum: 0
          description: 'Generate only: the `credits` POST /quote answered for this body. If the price has moved since, the run is refused with 409 `price_changed` and the new `data.credits`, and nothing is charged.'
  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.