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

# API overview

> Start Mint World and 3D Model generation from your app.

**Access:** beta

The Mint API lets your app start long-running World and 3D Model generation flows, optimize or convert generated 3D Models, check status, and fetch generated resources.

Use the production base URL:

```text theme={null}
https://api.mint.gg/v1
```

## Authentication

The Mint API is currently in beta. Email [hello@mint.gg](mailto:hello@mint.gg) for access.

After access is enabled, create an API key in Mint from **Developer**. Send it as a Bearer token:

```bash theme={null}
curl https://api.mint.gg/v1/me \
  -H "Authorization: Bearer your_api_key"
```

## Start a generation

Use action routes to start generation:

```bash theme={null}
curl https://api.mint.gg/v1/worlds:generate \
  -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: world-demo-001" \
  -d '{
    "prompt": "A quiet sci-fi greenhouse with glass walkways",
    "generationMode": "auto",
    "generationPreset": "standard"
  }'
```

`generationMode` can be:

* `auto`: continue without a manual approval pause when the generation can proceed.
* `review`: stop at Preview so your app can approve or revise before final generation.

`generationPreset` can be `fast`, `standard`, or `production`.

Every mutating request requires `Idempotency-Key`. Reusing a key with the same request safely returns the same operation. Reusing it with different input returns a conflict.

## Convert a 3D Model

Use `POST /v1/models:convert` to convert a finished 3D Model into additional file formats.

Supported target formats are:

* `glb`
* `obj`
* `stl`
* `usdz`
* `fbx`

`objUrl` and `fbxUrl` remain the primary download URLs. For new conversions
they may point to ZIP packages that include the converted model, material files,
and texture images. Read `conversion.assets.artifacts` when your app needs the
download filename, content type, package type, byte size, or primary file path
inside the package.

For a Mint-generated model, pass the model ID:

```bash theme={null}
curl https://api.mint.gg/v1/models:convert \
  -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: convert-demo-001" \
  -d '{
    "source": {
      "modelId": "model_..."
    },
    "targetFormats": ["fbx", "obj"]
  }'
```

You can also pass a direct HTTPS URL to a GLB source file:

```json theme={null}
{
  "source": {
    "url": "https://example.com/model.glb"
  },
  "targetFormats": ["usdz"]
}
```

Mint rejects unsafe source URLs, including non-HTTPS URLs, localhost or private
network hosts, redirects, oversized files, and responses that are not GLB
files.

## Track progress

Generation takes time. A start request returns an operation and a `Location` header:

```json theme={null}
{
  "object": "operation",
  "id": "op_...",
  "type": "world_generation",
  "generationMode": "auto",
  "status": "running",
  "prompt": "A quiet sci-fi greenhouse with glass walkways",
  "generationPreset": "standard",
  "generationModel": "marble-...",
  "resource": {
    "type": "world",
    "id": "world_..."
  },
  "mintUrl": "https://mint.gg/0x.../world_...",
  "assets": null
}
```

Poll `GET /v1/operations/{operationId}` until the status is `preview_ready`, `succeeded`, `failed`, or `canceled`.

When an operation has a generated resource, `mintUrl` links to the World or 3D Model on Mint. When an operation succeeds, `assets` includes the generated files your app needs. World assets include fields such as `panoUrl`, `colliderMeshUrl`, `spzUrls`, `thumbnailUrl`, and `caption`. 3D Model assets include fields such as `optimizedGlbUrl`, `glbUrl`, `thumbnailUrl`, and `previewImageUrl`.

## Optimize a 3D Model

Use `POST /v1/models/{modelId}:optimize` to prepare a smaller GLB for delivery:

```bash theme={null}
curl https://api.mint.gg/v1/models/model_123:optimize \
  -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: optimize-model-001" \
  -d '{
    "optimizationLevel": "moderate"
  }'
```

`optimizationLevel` can be:

* `light`: preserve more visual detail with less compression.
* `moderate`: balance visual quality and file-size reduction. This is the default.
* `aggressive`: reduce file size most, with more possible fidelity loss.

The model must belong to the Mint account that owns the API key. Each model optimization costs 20 Credits. The original `glbUrl` remains available, and the optimized file appears as `assets.optimizedGlbUrl` when the operation succeeds.

Conversion operations use the same polling endpoint. They return
`type: "model_conversion"`, `prompt: null`, and converted file URLs under
`conversion.assets`, such as `fbxUrl`, `objUrl`, `stlUrl`, `usdzUrl`, or
`glbUrl`. Packaged `OBJ` and `FBX` outputs still use `objUrl` and `fbxUrl` as
their primary URLs, while `conversion.assets.artifacts` describes whether each
output is a single file or a ZIP package.

## List generated resources

Use `GET /v1/worlds` and `GET /v1/models` to list resources generated through your API project:

```bash theme={null}
curl "https://api.mint.gg/v1/worlds?limit=20" \
  -H "Authorization: Bearer your_api_key"
```

Responses include `data` and `pagination.nextCursor`. Pass `cursor` to fetch the next page. These list endpoints only return resources created through the Mint API for the authenticated project.

## Check credits and usage

Use `GET /v1/usage` to check the authenticated Mint account's available Credits and aggregate API usage:

```bash theme={null}
curl https://api.mint.gg/v1/usage \
  -H "Authorization: Bearer your_api_key"
```

The response includes `credits`, `subscription`, and compact `apiUsage` totals.

## OpenAPI and SDKs

The OpenAPI contract is available at:

```text theme={null}
https://api.mint.gg/openapi.json
```

The reference pages in this documentation are generated from the same OpenAPI contract. TypeScript and Python SDKs are planned before broader API availability.