convert_model

Convert one of the account’s Library 3D models (a GLB) to GLB, STL, 3MF, OBJ or PLY on the server, optionally simplifying it, compressing its geometry, scaling it to a real-world size, moving its origin or repairing it for printing (holes, flipped faces, debris; STL, 3MF, OBJ or PLY), and file the result in the Library as a new creation made from it. Free (no credits) and answered at once. STL and 3MF are millimetres and Z-up for slicers; OBJ and PLY are geometry only, in metres; GLB keeps materials and textures and can be meshopt-compressed. Take asset_id from get_job or search_library (a file of a finished 3D job). Models over 50 MB or 2,000,000 triangles, and Draco-compressed GLBs, are refused. The same conversion run twice returns the same creation.

Argument	Type	Description
name	string
format	string	The file to make; glb when omitted.
origin	string	Move the origin to the bottom centre (default when resizing) or the centre.
repair	boolean	Repair for printing first: weld, drop broken and duplicate faces and loose debris, fix flipped faces, fill holes. stl, 3mf, obj, ply only; up to 200,000 triangles (simplify first for more).
asset_id*	string	A GLB file of one of your Library models.
simplify	any	Share of triangles to keep: 1 (default), 0.75, 0.5 or 0.25.
project_id	string
compression	string	GLB only: meshopt (default, smallest) or none.
resize_height	number	Scale the model to this height, in metres.
resize_longest_side	number	Scale the model so its longest side is this long, in metres. Not with resize_height.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "asset_id"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1
    },
    "format": {
      "enum": [
        "glb",
        "stl",
        "3mf",
        "obj",
        "ply"
      ],
      "type": "string",
      "description": "The file to make; glb when omitted."
    },
    "origin": {
      "enum": [
        "bottom",
        "center"
      ],
      "type": "string",
      "description": "Move the origin to the bottom centre (default when resizing) or the centre."
    },
    "repair": {
      "type": "boolean",
      "description": "Repair for printing first: weld, drop broken and duplicate faces and loose debris, fix flipped faces, fill holes. stl, 3mf, obj, ply only; up to 200,000 triangles (simplify first for more)."
    },
    "asset_id": {
      "type": "string",
      "maxLength": 191,
      "minLength": 1,
      "description": "A GLB file of one of your Library models."
    },
    "simplify": {
      "anyOf": [
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 0.75
        },
        {
          "type": "number",
          "const": 0.5
        },
        {
          "type": "number",
          "const": 0.25
        }
      ],
      "description": "Share of triangles to keep: 1 (default), 0.75, 0.5 or 0.25."
    },
    "project_id": {
      "type": "string",
      "maxLength": 191,
      "minLength": 1
    },
    "compression": {
      "enum": [
        "meshopt",
        "none"
      ],
      "type": "string",
      "description": "GLB only: meshopt (default, smallest) or none."
    },
    "resize_height": {
      "type": "number",
      "maximum": 1000,
      "description": "Scale the model to this height, in metres.",
      "exclusiveMinimum": 0
    },
    "resize_longest_side": {
      "type": "number",
      "maximum": 1000,
      "description": "Scale the model so its longest side is this long, in metres. Not with resize_height.",
      "exclusiveMinimum": 0
    }
  }
}

estimate_cost

Price a generation before starting it: the credits this model would charge for these options, and whether the current balance covers it. Uses the same validation and price calculation as generate_3d and generate, so for a valid request the figure is exactly what is charged. Omit scene to price every scene of the model. Nothing is charged and nothing is started.

read-only

Argument	Type	Description
model*	string	A model id from list_models.
scene	string	A scene id from list_models, e.g. 'image-to-3d'.
prompt	string
options	object	The options you intend to pass; they change the price.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "model"
  ],
  "properties": {
    "model": {
      "type": "string",
      "minLength": 1,
      "description": "A model id from list_models."
    },
    "scene": {
      "type": "string",
      "description": "A scene id from list_models, e.g. 'image-to-3d'."
    },
    "prompt": {
      "type": "string"
    },
    "options": {
      "type": "object",
      "description": "The options you intend to pass; they change the price.",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": true
    }
  }
}

generate

Start an async AI generation of any media type and return its job id. The input shape depends on the model (see list_models); for 3D prefer generate_3d. To run an image preset (list_models returns them: figurine, style, pose, convert), send mediaType "image", scene "image-to-image", options.image (the picture, or the subject then a reference), options.preset (its id) and optionally options.preset_addons and options.preset_background; the server composes the prompt, and prompt is then only your extra instructions. Bills credits: check the price with estimate_cost first. Pass a stable idempotencyKey when retrying — a retry with the same key replays the original job instead of billing twice. Then call get_job.

Argument	Type	Description
model*	string
scene	string
prompt	string	The prompt; with options.preset, only your additional instructions.
options	object	Model-specific options; derive from list_models (include_inputs). For an image preset: preset (its id), preset_addons, preset_background.
mediaType*	string	Generation family, e.g. 'image' \| 'video' \| '3d' \| 'music' — see list_models.
workflowType	string
idempotencyKey	string

generate_3d

Start a 3D generation and return its job id at once. mode picks the input: text (prompt), image (options with the image URL), multiview (several view images), sketch, or model (edit an existing 3D model). Take the model id and its option names from list_models, and check the price with estimate_cost first: this spends credits. Pass a stable idempotency_key when retrying so a retry replays the same job instead of billing twice. Then call get_job to follow it.

Argument	Type	Description
mode*	string	Which input the model is given.
model*	string	A 3D model id from list_models.
prompt	string
options	object	Model-specific options; take the field names from list_models with include_inputs, and price them with estimate_cost first.
idempotency_key	string	Reuse the same value when retrying this exact request.
expected_credits	integer	The credits estimate_cost answered for this request. If the price has moved since, nothing is started or charged and the error (price_changed) gives the new price.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "mode",
    "model"
  ],
  "properties": {
    "mode": {
      "enum": [
        "image",
        "text",
        "multiview",
        "sketch",
        "model"
      ],
      "type": "string",
      "description": "Which input the model is given."
    },
    "model": {
      "type": "string",
      "minLength": 1,
      "description": "A 3D model id from list_models."
    },
    "prompt": {
      "type": "string"
    },
    "options": {
      "type": "object",
      "description": "Model-specific options; take the field names from list_models with include_inputs, and price them with estimate_cost first.",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": true
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 191,
      "description": "Reuse the same value when retrying this exact request."
    },
    "expected_credits": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "The credits estimate_cost answered for this request. If the price has moved since, nothing is started or charged and the error (price_changed) gives the new price."
    }
  }
}

get_balance

Get the credits this account can spend now (and how many of them come from the subscription or are permanent), the plan name when there is one, and — when you are connected with an API key that has a monthly credit limit — that limit, what the key has used this month, and when it resets. Read-only.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

get_batch

The state of a batch and of each picture in it: queued, running, done, failed or cancelled, the job_id of its run once started (get_job gives the files), credits charged, and whether retry_batch can run it again.

read-only

Argument	Type	Description
batch_id*	string	The batch id start_batch returned.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "batch_id"
  ],
  "properties": {
    "batch_id": {
      "type": "string",
      "maxLength": 191,
      "minLength": 1,
      "description": "The batch id start_batch returned."
    }
  }
}

get_job

Get a job started by generate_3d or generate: its status, progress, credits charged and refunded, and — when it has finished — the result files with their public download URLs, including other formats where the model returned them. Poll about every 5–10 seconds while status is pending or processing; stop when is_terminal is true.

read-only

Argument	Type	Description
job_id*	string	The job id returned by generate_3d or generate.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "job_id"
  ],
  "properties": {
    "job_id": {
      "type": "string",
      "maxLength": 191,
      "minLength": 1,
      "description": "The job id returned by generate_3d or generate."
    }
  }
}

list_batches

The account’s batches of one scene from the last 24 hours, newest first, with each picture’s progress — and how many pictures its plan lets one batch hold (allowance; 0 means the plan includes no batches).

read-only

Argument	Type	Description
limit	integer
scene*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "scene"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 10,
      "minimum": 1
    },
    "scene": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1
    }
  }
}

list_job_files

List the files a finished job already has, one per format: the main result plus any alternate formats the model returned (for 3D models, for example glb with fbx or usdz), each with a public download URL. Pass format to find one format. This does not convert: if the format asked for is not there, available_formats says what is, and a model can be exported to other formats from the web app model viewer.

read-only

Argument	Type	Description
format	string	A file format to look for, e.g. 'glb' or 'stl'.
job_id*	string	The job id returned by generate_3d or generate.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "job_id"
  ],
  "properties": {
    "format": {
      "type": "string",
      "maxLength": 16,
      "description": "A file format to look for, e.g. 'glb' or 'stl'."
    },
    "job_id": {
      "type": "string",
      "maxLength": 191,
      "minLength": 1,
      "description": "The job id returned by generate_3d or generate."
    }
  }
}

list_models

List the models this account can generate with, grouped by what they make (3D, image, …): each with its id, the scenes (input modes such as text-to-3d or image-to-3d) it supports, and the credits it costs at default options. Call this first to choose a model id, then estimate_cost for an exact price. Set include_inputs to also get the option fields of each scene (names, allowed values, ranges). An account whose app has Image Maker also gets presets: ready-made picture conversions (figurine, style, pose, …) to run with generate by passing options.preset. batches lists the scenes start_batch can run over several Library pictures at once, with the models each may use.

read-only

Argument	Type	Description
media_type	string	Only models of this kind, e.g. '3d' or 'image'.
available_only	boolean	Leave out models that are listed but cannot be started.
include_inputs	boolean	Include the option fields of every scene (larger result).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "media_type": {
      "enum": [
        "music",
        "image",
        "video",
        "text",
        "speech",
        "3d"
      ],
      "type": "string",
      "description": "Only models of this kind, e.g. '3d' or 'image'."
    },
    "available_only": {
      "type": "boolean",
      "default": true,
      "description": "Leave out models that are listed but cannot be started."
    },
    "include_inputs": {
      "type": "boolean",
      "default": false,
      "description": "Include the option fields of every scene (larger result)."
    }
  }
}

retry_batch

Queue the batch’s failed pictures (and any stopped for want of credits) again as new runs, or only the item_ids given. Charged as each starts, like a new batch of that many pictures: the balance must cover them and they count against a monthly limit.

Argument	Type	Description
batch_id*	string	The batch id start_batch returned.
item_ids	array

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "batch_id"
  ],
  "properties": {
    "batch_id": {
      "type": "string",
      "maxLength": 191,
      "minLength": 1,
      "description": "The batch id start_batch returned."
    },
    "item_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 191,
        "minLength": 1
      },
      "maxItems": 100
    }
  }
}

search_library

Search the Library of past generations kept by this account, newest first: filter by words in the prompt or title and by kind (3d, image, …). Returns the job id, model, status and result file URLs of each run. Use next_cursor to page. Only runs of this account are ever searched. For the full detail of one run call get_job.

read-only

Argument	Type	Description
limit	integer	How many to return, 1 to 50.
query	string	Words to look for in the prompt or title.
cursor	string	The next_cursor of the previous result.
media_type	string	Only runs of this kind, e.g. '3d' or 'image'.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "description": "How many to return, 1 to 50."
    },
    "query": {
      "type": "string",
      "maxLength": 200,
      "description": "Words to look for in the prompt or title."
    },
    "cursor": {
      "type": "string",
      "maxLength": 8,
      "description": "The next_cursor of the previous result."
    },
    "media_type": {
      "enum": [
        "music",
        "image",
        "video",
        "text",
        "speech",
        "3d"
      ],
      "type": "string",
      "description": "Only runs of this kind, e.g. '3d' or 'image'."
    }
  }
}

start_batch

Run the same model, scene and options once for each of several pictures in the account’s Library — for example image to 3D for twelve product photos. Take the scenes and models from list_models (`batches`), and each picture’s asset_id from get_job or search_library on a finished image job. Nothing is charged now: each run is charged as it starts and refunded if it fails, but the balance must cover the whole quote, and for a key or connection with a monthly limit the whole quote is held against it until each picture runs (then its real cost counts) or is cancelled, refused or refunded (then nothing does). Returns a batch id at once; follow it with get_batch. Pass idempotency_key on retries so a repeat returns the same batch instead of queueing another.

Argument	Type	Description
items*	array	One entry per picture: a Library image’s asset_id.
model*	string
scene*	string
prompt	string
options	object	Options every run shares, as for generate; the picture field is filled per item.
project_id	string
idempotency_key	string
notify_by_email

viewer_job_state

Used by the interactive 3D viewer shown next to a generation result, not for direct use: the state of one job and, once it has finished, the URL of the model file the viewer can draw plus the download links. Read-only; the conversation never needs to call it, get_job gives the same facts as text.

read-only

Argument	Type	Description
job_id*	string	The job id returned by generate_3d.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "job_id"
  ],
  "properties": {
    "job_id": {
      "type": "string",
      "maxLength": 191,
      "minLength": 1,
      "description": "The job id returned by generate_3d."
    }
  }
}

AI3D Studio

Try it

convert_model

AI3D Studio

Try it

convert_model

Tools (14)