AI3D Studio Generate API

openapi: 3.2.0
info:
  title: AI3D Studio Generate 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: Generate
paths:
  /generate:
    post:
      operationId: generate
      x-required-scope: generate
      summary: Start a generation
      description: 'Start an async generation. The body shape depends on the chosen model — see `/capabilities`. Returns a workflow id to poll. The `Idempotency-Key` header is REQUIRED: reuse the same key on a retry to replay the original workflow instead of billing twice.'
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          maxLength: 191
        description: Unique per generation gesture (a UUID works). A retry with the same key and body returns the original workflow.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerationRequest'
      responses:
        '200':
          description: Generation accepted; poll the returned workflow.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Missing or invalid Idempotency-Key header
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Insufficient credits
        '409':
          description: 'The price moved since the quote sent as `expectedCredits`: `data.code = "price_changed"` and the current `data.credits`. Nothing is charged.'
        '422':
          description: Invalid generation request (unknown model/mediaType, failed input validation). A refused image preset answers `data.code = "request_invalid"` and names the reason in `data.presetError` (`unknown_preset`, `preset_unavailable`, `preset_scene_unsupported`, `preset_model_unsupported`, `preset_images_invalid`, `unknown_addon`, `addons_unsupported`, `invalid_background`, `background_fixed`, `instructions_required`, `instructions_too_long`, `preset_required`).
        '429':
          description: Rate limited
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      - oauth2:
        - generate
      tags:
      - Generate
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.