> ## 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.

# Upload reference images

> Multipart files: 1–8 PNG/JPEG/WebP images. Up to 20 MiB and 40 megapixels per image, 80 MiB total. Original bytes are preserved. Identical uploads reuse the same private image ID.



## OpenAPI

````yaml /openapi.json post /v1/images
openapi: 3.1.0
info:
  title: Gizmo Asset API
  description: >-
    Generate and export individual 3D assets from text and reference images.


    Export to USD / USDZ (Isaac Sim), MJCF (MuJoCo), and SDF (Gazebo). GLB is
    only available via the editor UI.


    ## Authentication


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


    ```

    Authorization: Bearer gzm_k1_<your-key>

    ```


    Create API keys in the [Gizmo
    Settings](https://gizmo.antimlabs.com/settings#api-keys) page.


    ## 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


    Asset generation is asynchronous. `POST /v1/assets` returns `202 Accepted`
    with a `job_id`. Use `GET /v1/jobs/{id}` to poll or `GET
    /v1/jobs/{id}/events` for real-time SSE streaming.


    ## 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: Images
    description: Upload and retrieve private original reference images.
  - name: Assets
    description: >-
      Manage individual 3D assets (articulated objects, furniture, equipment).
      Generate from a prompt and optional reference images, then retrieve or
      export the result.
  - name: Jobs
    description: >-
      Monitor and control async generation jobs. Poll with `GET /v1/jobs/{id}`,
      stream real-time progress via `GET /v1/jobs/{id}/events` (SSE), or cancel
      with `POST /v1/jobs/{id}/cancel`.
  - name: Catalog
    description: >-
      Browse the premade asset library — thousands of physics-ready 3D objects
      organized by category. Download GLB/USDZ directly.
  - name: Account
    description: View your identity and API usage statistics.
paths:
  /v1/images:
    post:
      tags:
        - Images
      summary: Upload reference images
      description: >-
        Multipart files: 1–8 PNG/JPEG/WebP images. Up to 20 MiB and 40
        megapixels per image, 80 MiB total. Original bytes are preserved.
        Identical uploads reuse the same private image ID.
      operationId: upload_images_v1_images_post
      parameters: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_images_v1_images_post'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageUploadResponse'
        '401':
          description: Missing, invalid, or revoked API key
          content:
            application/json:
              example:
                detail:
                  error:
                    code: invalid_api_key
                    message: Invalid or revoked API key
                    status: 401
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '409':
          description: Conflicting request or idempotency key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '413':
          description: Upload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '415':
          description: Unsupported or invalid image
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Invalid request; see detail.error.fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              example:
                detail:
                  error:
                    code: rate_limit_exceeded
                    message: 'Rate limit exceeded: 60 requests per minute'
                    status: 429
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
components:
  schemas:
    Body_upload_images_v1_images_post:
      properties:
        files:
          items:
            type: string
            contentMediaType: application/octet-stream
          type: array
          title: Files
      type: object
      required:
        - files
      title: Body_upload_images_v1_images_post
    ImageUploadResponse:
      properties:
        images:
          items:
            $ref: '#/components/schemas/ImageResource'
          type: array
          title: Images
      type: object
      required:
        - images
      title: ImageUploadResponse
    ApiErrorResponse:
      properties:
        detail:
          $ref: '#/components/schemas/ApiErrorPayload'
      type: object
      required:
        - detail
      title: ApiErrorResponse
    ImageResource:
      properties:
        id:
          type: string
          title: Id
        content_type:
          type: string
          title: Content Type
        size_bytes:
          type: integer
          title: Size Bytes
        width:
          type: integer
          title: Width
        height:
          type: integer
          title: Height
        sha256:
          type: string
          title: Sha256
      type: object
      required:
        - id
        - content_type
        - size_bytes
        - width
        - height
        - sha256
      title: ImageResource
    ApiErrorPayload:
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorDetail'
      type: object
      required:
        - error
      title: ApiErrorPayload
    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
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gzm_k1_<hex>
      description: API key created in Gizmo Settings → API Keys

````