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

# Generate an asset

> Generate a single 3D asset from a text prompt. The asset includes geometry, joints, materials, physics properties, and affordances.

The build method is chosen automatically per request: structured or jointed objects (furniture, appliances, racks) build as prim-based articulated assets (~15-20 min); organic objects (food, plants, fabric) build as mesh scans (~2-4 min). Optional `reference_image_urls` ground the geometry/texture in your photos.

Returns a `job_id` — poll or stream for progress.



## OpenAPI

````yaml /openapi.json post /v1/assets
openapi: 3.1.0
info:
  title: Gizmo API
  version: 1.0.0
  description: >-
    Programmatic API for AI-powered 3D simulation authoring.


    Generate physics-ready 3D scenes and articulated assets from natural
    language prompts. Export to USD / USDZ (Isaac Sim), MJCF (MuJoCo), and SDF
    (Gazebo). GLB is only available via the editor UI.
servers:
  - url: https://api.gizmo.antimlabs.com
    description: Production
security: []
tags:
  - name: Scenes
    description: >-
      Create, retrieve, update, and delete 3D simulation scenes. Generation is
      async — `POST /v1/scenes` returns a `job_id` for polling.
  - name: Assets
    description: >-
      Manage individual 3D assets (articulated objects, furniture, equipment).
      Each asset belongs to a scene and contains geometry, joints, materials,
      and physics data.
  - 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/assets:
    post:
      tags:
        - Assets
      summary: Generate an asset
      description: >-
        Generate a single 3D asset from a text prompt. The asset includes
        geometry, joints, materials, physics properties, and affordances.


        The build method is chosen automatically per request: structured or
        jointed objects (furniture, appliances, racks) build as prim-based
        articulated assets (~15-20 min); organic objects (food, plants, fabric)
        build as mesh scans (~2-4 min). Optional `reference_image_urls` ground
        the geometry/texture in your photos.


        Returns a `job_id` — poll or stream for progress.
      operationId: generate_asset_v1_assets_post
      parameters:
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
        - name: x-gizmo-service-token
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Gizmo-Service-Token
        - name: x-gizmo-user-id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Gizmo-User-Id
        - name: x-gizmo-convex-user-id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Gizmo-Convex-User-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateAssetBody'
      responses:
        '202':
          description: Job created
          content:
            application/json:
              schema: {}
              example:
                ok: true
                scene_id: jh72k3m4n5p6q7r8
                job_id: job_x9y8z7w6
                status: queued
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
components:
  schemas:
    GenerateAssetBody:
      properties:
        prompt:
          type: string
          minLength: 1
          title: Prompt
          description: Natural language description of the asset
          examples:
            - A 6-DOF robotic arm with gripper end-effector
        scene_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Scene Id
          description: Target scene ID. If omitted, a default scene is created.
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: Override the default LLM model
        asset_pipeline:
          type: string
          enum:
            - auto
            - gizmo
            - cad
          title: Asset Pipeline
          description: Geometry pipeline
          default: auto
        reference_image_urls:
          items:
            type: string
          type: array
          maxItems: 3
          title: Reference Image Urls
          description: Up to 3 http(s) image URLs grounding the asset's geometry/texture
        persist:
          type: boolean
          title: Persist
          description: Whether to persist to S3
          default: true
      type: object
      required:
        - prompt
      title: GenerateAssetBody
      description: Request body for asset generation.
    ApiErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorDetail'
      type: object
      required:
        - error
      title: ApiErrorResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ApiErrorDetail:
      properties:
        code:
          type: string
          title: Code
          description: Machine-readable error code
          examples:
            - scene_not_found
        message:
          type: string
          title: Message
          description: Human-readable description
          examples:
            - Scene sc_abc123 not found
        status:
          type: integer
          title: Status
          description: HTTP status code
          examples:
            - 404
      type: object
      required:
        - code
        - message
        - status
      title: ApiErrorDetail
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````