AI3D Studio Batches API

openapi: 3.2.0
info:
  title: AI3D Studio Batches 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: Batches
paths:
  /batches:
    post:
      operationId: createBatch
      x-required-scope: generate
      summary: 'Start a batch: one run per Library picture'
      description: 'Queue one run of the same model, scene and options for each picture, started in the background as your plan’s concurrency allows. The scenes and models an app batches are `generation.batches` in `/capabilities`; your plan sets how many pictures one batch may hold (`allowance` on `GET /batches`). A picture is the `assetId` of one of your own Library images — the `assets[].id` of a finished image run from `/workflows/{id}` — never a URL or bytes. Nothing is charged on submit: each run is charged as it starts and refunded if it fails; the whole quote (`quotedCredits`) must be covered by your balance now. For an API key or connection with a monthly credit limit the whole quote is held against it when the batch is accepted, and a batch that would pass it answers 429; each picture then counts its real cost, and nothing once it fails and is refunded, is cancelled or is refused. The `Idempotency-Key` header is REQUIRED: a retry with the same key and body returns the original batch (200) instead of a second one (202).'
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9._:-]{8,128}$
        description: Unique per batch (a UUID works). Reuse it on a retry; reusing it with a different body answers 409 `idempotency_conflict`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - model
              - scene
              - items
              additionalProperties: false
              properties:
                model:
                  type: string
                scene:
                  type: string
                  description: A scene from `generation.batches`.
                options:
                  type: object
                  additionalProperties: true
                  description: Options every run shares, as for `/generate`; the picture field is filled per item.
                prompt:
                  type: string
                items:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      assetId:
                        type: string
                        description: One of your Library images.
                      name:
                        type: string
                        maxLength: 400
                        description: What the run is filed as.
                    required:
                    - assetId
                projectId:
                  type: string
                  description: A Library project to file the runs in.
                notifyByEmail:
                  type: boolean
                  description: Email the account once the batch settles.
                expectedCredits:
                  type: integer
                  description: The quote you showed; a different current price answers 409 `price_changed` and queues nothing.
      responses:
        '200':
          description: A replay of an accepted batch.
        '202':
          description: 'Batch accepted: the batch with its items, `quotedCredits` and your `balance`. Poll `GET /batches/{id}`.'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Missing or malformed `Idempotency-Key` (`idempotency_key_required`) or body (`invalid_request`)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: The balance does not cover the quote
        '403':
          description: The plan includes no batches (`plan_required`) or not this model (`model_unavailable`)
        '404':
          description: The app batches no such scene or model (`batches_unavailable`)
        '409':
          description: '`idempotency_conflict` or `price_changed` (with `expectedCredits` and `actualCredits`)'
        '422':
          description: '`too_many_items` (with `limit`), `invalid_inputs` (with `inputErrors`: picture index → `unavailable` or `duplicate`), `invalid_options` or `project_unavailable`'
        '429':
          description: Rate limited, five batches already running (`too_many_active_batches`), or the key’s or connection’s monthly credit limit would be passed (with `needed` and `resetsAt`)
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      - oauth2:
        - generate
      tags:
      - Batches
    get:
      operationId: listBatches
      x-required-scope: read
      summary: List your recent batches of a scene
      description: Your batches of one scene from the last 24 hours, newest first.
      parameters:
      - name: scene
        in: query
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 10
          default: 3
      responses:
        '200':
          description: 'Newest first: `batches`, and `allowance` — how many pictures your plan lets one batch hold (0: none).'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      - oauth2:
        - read
      tags:
      - Batches
  /batches/{id}:
    get:
      operationId: getBatch
      x-required-scope: read
      summary: Poll a batch
      description: 'The batch’s `status` (`running`, `done`, `cancelled`), its `counts` and each item: `state` (`queued`, `running`, `done`, `failed`, `cancelled`), the `workflowId` of its run once it has started (poll `/workflows/{id}` for the files), `credits`, `errorCode` and whether it is `retryable`.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The batch
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown batch (`not_found`)
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      - oauth2:
        - read
      tags:
      - Batches
  /batches/{id}/retry:
    post:
      operationId: retryBatch
      x-required-scope: generate
      summary: Run the failed pictures again
      description: Each failed picture (or one stopped for want of credits) is queued again as a new run; send `itemIds` to retry only some. Charged and capped like a new batch of that many pictures.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                itemIds:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: '`requeued` (how many) and the batch'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: The balance does not cover the retry
        '404':
          description: Unknown batch (`not_found`)
        '409':
          description: Nothing to retry (`nothing_to_retry`)
        '429':
          description: Rate limited, or the monthly credit limit would be passed
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      - oauth2:
        - generate
      tags:
      - Batches
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.