AI3D Studio Tools API

openapi: 3.2.0
info:
  title: AI3D Studio Tools 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: Tools
paths:
  /tools/convert:
    post:
      operationId: convertModel
      x-required-scope: generate
      summary: Convert, compress or repair a Library model on the server
      description: 'Convert one of your Library 3D models (a GLB) to GLB, STL, 3MF, OBJ or PLY, optionally simplifying it, compressing its geometry, scaling it to a real-world size (`resizeHeight` or `resizeLongestSide`, in metres), moving its origin (`origin`) or repairing it for printing (`repair`), and file the result in your Library as a new creation made from it. Repair runs the free repair tool’s steps on the server — weld, drop collapsed and duplicate faces and loose debris, make the faces point outward, fill holes — writes STL, 3MF, OBJ or PLY (not GLB: the textures would no longer fit), takes up to 200,000 triangles after any `simplify`, and reports the geometry before and after (`report.repair`: watertight, holes, non-manifold edges, shells, and what each step changed). Free (no credits) and answered in the same request. STL and 3MF are written in millimetres and Z-up, as slicers read them; OBJ and PLY carry geometry only, in metres; GLB keeps materials and textures and is meshopt-compressed unless `compression` is `none`. A model over 50 MB or 2,000,000 triangles, or Draco-compressed, is refused. The same model and options land on the same stored file, so a repeat returns the creation the first run made (`created: false`). Limited to 10 runs a minute and 300 a day per account. When every converter is at work the answer is 429 `busy`, and when the converter is down it is 503 `unavailable`; both carry `Retry-After`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - assetId
              additionalProperties: false
              properties:
                assetId:
                  type: string
                  description: 'A GLB file of one of your Library models: `assets[].id` of a finished 3D workflow.'
                format:
                  type: string
                  enum:
                  - glb
                  - stl
                  - 3mf
                  - obj
                  - ply
                  default: glb
                compression:
                  type: string
                  enum:
                  - meshopt
                  - none
                  default: meshopt
                  description: GLB only.
                simplify:
                  type: number
                  enum:
                  - 1
                  - 0.75
                  - 0.5
                  - 0.25
                  default: 1
                  description: Share of triangles to keep.
                resizeHeight:
                  type: number
                  exclusiveMinimum: 0
                  maximum: 1000
                  description: Scale the model to this height, in metres.
                resizeLongestSide:
                  type: number
                  exclusiveMinimum: 0
                  maximum: 1000
                  description: Scale the model so its longest side is this long, in metres. Not with `resizeHeight`.
                origin:
                  type: string
                  enum:
                  - bottom
                  - center
                  description: Move the origin to the bottom centre (the default when resizing) or the centre.
                repair:
                  type: boolean
                  description: 'Repair for printing before writing: STL, 3MF, OBJ or PLY only, up to 200,000 triangles after `simplify`.'
                name:
                  type: string
                  maxLength: 200
                  description: The new creation’s name.
                projectId:
                  type: string
                  description: A Library project to file it in.
      responses:
        '200':
          description: '`workflowId` and `assetId` of the creation, `created`, the file’s `url`, `format`, `contentType`, `bytes`, and a `report` with the triangles before and after (and, with `repair`, `report.repair` with the topology `before` and `after` and the `changes` each step made).'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid request (`invalid_request`)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: No such GLB model in your Library (`not_found`)
        '413':
          description: The model is too large (`too_large`)
        '422':
          description: '`too_dense`, `unreadable`, `unsupported_compression` (Draco), `no_mesh`, `timeout` or `out_of_memory`: the model, not the request, is past a bound. `too_dense_to_repair`: more than 200,000 triangles to repair — ask for `simplify` 0.5 or 0.25. `not_smaller`: a meshopt GLB at full detail came out no smaller than the source (it was already compressed); nothing is stored'
        '429':
          description: Rate limited, or every converter is busy (`busy`, with `Retry-After`)
        '503':
          description: The converter is unavailable (`unavailable`, with `Retry-After`); nothing was stored
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      - oauth2:
        - generate
      tags:
      - Tools
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.