> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gizmo.antimlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit an asset batch

> Personal and Team keys. Submit asset inputs with unique custom_id values and a required Idempotency-Key: up to 50 per Personal batch; Team keys accept larger batches. Returns 202 with a batch_id; acceptance does not mean generation has finished. Items queue automatically within the Team processing limit, or for Personal keys start as the account's 20 in-progress slots free up; each Personal item is billed like a single generation. Save the batch ID, poll its progress and paginate its items for results. Reuse the same key and body after a lost response to avoid duplicate work. [Batch workflow](https://docs.gizmo.antimlabs.com/api-batches).



## OpenAPI

````yaml /openapi.json post /v1/batches
openapi: 3.1.0
info:
  title: Gizmo API
  description: >-
    Generate simulation-ready 3D assets from text and reference images,
    individually or in batches, and export them as USD / USDZ (Isaac Sim), MJCF
    (MuJoCo), SDF (Gazebo) or a GLB bundle with colliders and physics. Start
    with the [API quickstart](https://docs.gizmo.antimlabs.com/api-access) for
    complete workflows, or [hand Gizmo to your coding
    agent](https://docs.gizmo.antimlabs.com/use-with-your-agent).


    ## Authentication


    All endpoints require an API key passed via the `Authorization` header:


    ```

    Authorization: Bearer gzm_k1_<your-key>

    ```


    Select Personal or your Team in Gizmo, then create a key in API Access. Both
    use https://api.gizmo.antimlabs.com; the key selects the library and billing
    account. A Team may be called workspace in response fields and error codes.


    ## Rate Limiting


    Rate limits are per-key. Rate-limited API-key responses include:

    - `X-RateLimit-Limit` — requests allowed per minute

    - `X-RateLimit-Remaining` — requests remaining in current window

    - `X-RateLimit-Reset` — Unix timestamp when the window resets


    ## Async Generation


    `POST /v1/assets` and `POST /v1/batches` return `202 Accepted` with a job or
    batch ID. Poll `GET /v1/jobs/{id}` or `GET /v1/batches/{id}` for progress;
    Personal keys can also stream `GET /v1/jobs/{id}/events` (SSE). Send an
    `Idempotency-Key` with every generation so a retried request never creates a
    duplicate job; Team keys must send one.


    ## Personal and Team keys


    One reference describes both key types; not every operation is available to
    both. Personal keys batch up to 50 items per batch. Team keys currently do
    not support SSE, GET /v1/usage or DELETE /v1/assets/{asset_id} (403
    workspace_route_unavailable; poll instead). Saved-file links, export-only
    retries, collision edits and scene reconstruction (POST /v1/scenes) are Team
    features when enabled for the Team.


    ## Errors


    Errors on public endpoints use `detail.error` with code, message, and
    status. Validation errors also include fields. Responses include
    X-Request-ID for support.

    ```json

    {"detail": {"error": {"code": "asset_not_found", "message": "Asset not
    found", "status": 404}}}

    ```
  version: 1.0.0
servers:
  - url: https://api.gizmo.antimlabs.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Assets
    description: Generate individual assets and browse your Personal or Team library.
  - name: Scenes
    description: >-
      **Team plan only.** Reconstruct complete scenes from text or inline
      reference images, track delivery, and download scene files. All scene
      routes require a Team API key; Personal keys are not supported.
  - name: Batches
    description: >-
      Generate many assets in one request, with partial results and automatic
      queueing.
  - name: Images
    description: Upload and retrieve private original reference images.
  - name: Jobs
    description: >-
      Track, cancel and recover generation jobs. Teams use polling; Personal
      keys also support SSE.
  - name: Exports
    description: >-
      Download simulator formats, visual GLBs and collision bundles. Saved-file
      routes require Team access.
  - name: Account
    description: >-
      Check your key's identity. Request usage statistics currently require
      Personal access.
paths:
  /v1/batches:
    post:
      tags:
        - Batches
      summary: Submit an asset batch
      description: >-
        Personal and Team keys. Submit asset inputs with unique custom_id values
        and a required Idempotency-Key: up to 50 per Personal batch; Team keys
        accept larger batches. Returns 202 with a batch_id; acceptance does not
        mean generation has finished. Items queue automatically within the Team
        processing limit, or for Personal keys start as the account's 20
        in-progress slots free up; each Personal item is billed like a single
        generation. Save the batch ID, poll its progress and paginate its items
        for results. Reuse the same key and body after a lost response to avoid
        duplicate work. [Batch
        workflow](https://docs.gizmo.antimlabs.com/api-batches).
      operationId: create_batch_v1_batches_post
      parameters:
        - name: idempotency-key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
            pattern: ^[A-Za-z0-9._:-]+$
            title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBatch'
            example:
              items:
                - custom_id: mug-001
                  input:
                    prompt: A white ceramic mug, 9 cm tall
                - custom_id: bowl-002
                  input:
                    prompt: A white ceramic bowl, 16 cm in diameter
      responses:
        '202':
          description: Batch accepted; save batch_id and poll for progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchAccepted'
              example:
                ok: true
                batch_id: BATCH_ID
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Too Many Requests
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Service Unavailable
components:
  schemas:
    CreateBatch:
      properties:
        items:
          items:
            $ref: '#/components/schemas/BatchItem'
          type: array
          maxItems: 1000
          minItems: 1
          title: Items
        max_cost_cents:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Cost Cents
          description: >-
            Optional ceiling for the sum of per-item generation safety limits;
            no credits are held at submission or admission
      additionalProperties: false
      type: object
      required:
        - items
      title: CreateBatch
      description: >-
        Items queue automatically within the Team processing limit, shared with
        its other batches and individual generations.
    BatchAccepted:
      properties:
        ok:
          type: boolean
          title: Ok
        batch_id:
          type: string
          title: Batch Id
      type: object
      required:
        - ok
        - batch_id
      title: BatchAccepted
    ApiErrorResponse:
      properties:
        detail:
          $ref: '#/components/schemas/ApiErrorPayload'
      type: object
      required:
        - detail
      title: ApiErrorResponse
    BatchItem:
      properties:
        custom_id:
          type: string
          maxLength: 128
          minLength: 1
          title: Custom Id
          description: Your unique identifier for this item, returned with its status
        input:
          $ref: '#/components/schemas/GenerateAssetBody'
      additionalProperties: false
      type: object
      required:
        - custom_id
        - input
      title: BatchItem
    ApiErrorPayload:
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorDetail'
      type: object
      required:
        - error
      title: ApiErrorPayload
    GenerateAssetBody:
      properties:
        composition:
          type: string
          enum:
            - single
            - assembly
          title: Composition
          description: >-
            Use assembly for one product containing separately built objects,
            such as a fitted tray with tools. Single keeps the ordinary asset
            pipeline.
          default: single
        appearance_variants:
          type: boolean
          title: Appearance Variants
          description: >-
            Keep the original and save additional variants as separate assets.
            Select count, mode and optional guidance.
          default: false
        variant_guidance:
          type: string
          maxLength: 2000
          title: Variant Guidance
          description: >-
            Optional guidance for the additional variants only. Requires
            appearance_variants=true; does not change the original prompt.
          default: ''
        variant_count:
          type: integer
          maximum: 10
          minimum: 1
          title: Variant Count
          description: >-
            Number of additional separately saved assets (1–10); original is not
            counted. Personal: each delivered variant costs a flat 100 credits
            ($1); the original bills at 1.5x measured cost.
          default: 2
        variant_mode:
          type: string
          enum:
            - appearance
            - geometry
            - both
          title: Variant Mode
          default: appearance
        interactions:
          items:
            type: string
            maxLength: 2000
            minLength: 1
          type: array
          maxItems: 32
          title: Interactions
          description: >-
            Optional intended interactions in plain language (each 1-2000
            characters). Omit to infer ordinary uses. The functional scenario
            allowance is max(2, unique supplied plus accepted inferred
            interaction count).
        prompt:
          type: string
          minLength: 1
          title: Prompt
          description: Natural language description of the asset
          examples:
            - A 6-DOF robotic arm with gripper end-effector
        reference_intent:
          anyOf:
            - $ref: '#/components/schemas/ReferenceIntent'
            - type: 'null'
        reference_image_urls:
          items:
            type: string
          type: array
          maxItems: 8
          title: Reference Image Urls
          description: Up to 8 http(s) image URLs grounding the asset's geometry/texture
        reference_images:
          items:
            $ref: '#/components/schemas/ImageReference'
          type: array
          maxItems: 8
          title: Reference Images
          description: >-
            Uploaded image IDs or HTTP(S) URLs, optionally labeled with a view.
            Combined maximum: 8 images.
        persist:
          type: boolean
          title: Persist
          description: >-
            Save the asset to your library for later retrieval and export
            (default true)
          default: true
      additionalProperties: false
      type: object
      required:
        - prompt
      title: GenerateAssetBody
      description: Request body for asset generation.
    ApiErrorDetail:
      properties:
        code:
          type: string
          title: Code
          description: Machine-readable error code
          examples:
            - asset_not_found
        message:
          type: string
          title: Message
          description: Human-readable description
          examples:
            - Asset ast_abc123 not found
        fields:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Fields
        status:
          type: integer
          title: Status
          description: HTTP status code
          examples:
            - 404
      type: object
      required:
        - code
        - message
        - status
      title: ApiErrorDetail
    ReferenceIntent:
      properties:
        mode:
          type: string
          enum:
            - auto
            - reconstruct
            - extract
            - modify
            - design
          title: Mode
          default: auto
        role:
          type: string
          enum:
            - subject
            - scene_context
            - style
          title: Role
          default: subject
        target:
          anyOf:
            - type: string
            - type: 'null'
          title: Target
        user_instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: User Instructions
        regions:
          items:
            $ref: '#/components/schemas/ReferenceRegion'
          type: array
          maxItems: 8
          title: Regions
        input_views:
          items:
            $ref: '#/components/schemas/InputView'
          type: array
          maxItems: 8
          title: Input Views
        requested_views:
          items:
            type: string
            enum:
              - front
              - back
              - left
              - right
              - top
          type: array
          maxItems: 5
          title: Requested Views
      additionalProperties: false
      type: object
      title: ReferenceIntent
    ImageReference:
      properties:
        image_id:
          anyOf:
            - type: string
              pattern: ^img_[0-9a-f]{64}$
            - type: 'null'
          title: Image Id
        url:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          title: Url
        view:
          anyOf:
            - type: string
              enum:
                - front
                - back
                - left
                - right
                - top
                - bottom
                - perspective
                - detail
            - type: 'null'
          title: View
      additionalProperties: false
      type: object
      title: ImageReference
    ReferenceRegion:
      properties:
        image_index:
          type: integer
          minimum: 0
          title: Image Index
        bounds:
          prefixItems:
            - type: number
            - type: number
            - type: number
            - type: number
          type: array
          maxItems: 4
          minItems: 4
          title: Bounds
      additionalProperties: false
      type: object
      required:
        - image_index
        - bounds
      title: ReferenceRegion
      description: >-
        A selector, not a measurement: coordinates in the displayed original.


        Plan indices name the plan's upload list; dispatch remaps them to the
        job's

        originals (direct images followed by scene images), before
        deduplication.
    InputView:
      properties:
        image_index:
          type: integer
          minimum: 0
          title: Image Index
        view:
          type: string
          enum:
            - front
            - back
            - left
            - right
            - top
            - bottom
            - perspective
            - detail
          title: View
      additionalProperties: false
      type: object
      required:
        - image_index
        - view
      title: InputView
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gzm_k1_<hex>
      description: >-
        Select Personal or your Team in Gizmo, then create a key in API Access.
        The key selects your library and billing account.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.