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

# 3D Models

> Generate, review, retrieve, optimize, retopologize, convert, and animate 3D Models.

Use the 3D Model API when you need one object or character with downloadable model files.

## Generate a 3D Model

Call `POST /v1/models:generate` with a `prompt`. Add `name` only when you want a specific title shown in Mint; Mint derives one when it is omitted. `generationMode` defaults to `auto`, and `generationPreset` defaults to `standard`. See [Presets](/developers/api-overview#presets) for the speed, quality, and cost tradeoffs.

```bash theme={null}
curl https://api.mint.gg/v1/models:generate \
  -X POST \
  -H "Authorization: Bearer $MINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A friendly stylized robot guide, full body",
    "name": "Robot guide",
    "riggingPose": "t_pose"
  }'
```

Use one `imageUrl` or 2–8 `sourceImages` for visual guidance, never both. `riggingPose` can be `t_pose` or `a_pose`; it prepares a full-body, front-facing, empty-handed humanoid Preview for later rigging but does not rig or animate it.

## Review and revise a Preview

The Preview is a fast visual proposal, not the final 3D Model. The recommended `auto` mode continues automatically; set `generationMode: "review"` only when your integration needs to inspect the Preview. Poll the operation until `preview_ready`, then:

* Approve with `POST /v1/models/{modelId}:approve`. Send no request body.
* Revise with `POST /v1/models/{modelId}:revise` and `feedback`. You can also set `name`, `revisionEditStrength`, `generationMode`, or `riggingPose`.

Use `generationMode: "review"` on a revision when you want another decision point. Omit it to continue automatically after the revised Preview.

## Retrieve the 3D Model and its files

When the operation succeeds, read `operation.resource.id`, then call `GET /v1/models/{modelId}`. The response includes available GLB, optimized GLB, preview, thumbnail, and converted-format URLs.

For a complete file inventory, use `GET /v1/assets/model/{modelId}/artifact-manifest`. Do not construct provider URLs.

## Retry a failed generation

Use `POST /v1/models/{modelId}:retry` for a terminal failed generation. The optional body can replace `prompt`, `name`, `generationMode`, or `generationPreset`.

## Optimize

Use `POST /v1/models/{modelId}:optimize` with `optimizationLevel` set to `light`, `moderate`, or `aggressive`. Optimization updates the model's optimized file rather than creating another 3D Model. Repeating the same level while it is active returns `409 model-optimization-in-progress`; repeating it after completion returns `409 model-already-optimized`. Neither conflict starts new work or creates another charge. The original `glbUrl` remains available; the optimized file appears as `assets.optimizedGlbUrl`.

## Smart topology

Use `POST /v1/models/{modelId}:retopologize` to create a topology-focused derivative. Set `faceLevel` to `low`, `medium`, or `high`, and optionally use `name` for the title shown in Mint. Each accepted request can create a new derivative; use a stable `Idempotency-Key` when retrying an uncertain request.

## Convert

Use `POST /v1/models/{modelId}:convert`. The model ID in the URL must belong to your Mint account. External source URLs are not accepted.

```json theme={null}
{
  "targetFormats": ["usdz", "fbx"]
}
```

Poll the operation, then read `operation.conversion.assets` for the requested `glb`, `obj`, `stl`, `usdz`, or `fbx` output.

## Animate

Animation has its own workflow and output resources. Continue to [Animation](/developers/animation).