Skip to main content
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: 
https://api.mint.gg/v1

​
Authentication

The Mint API is currently in beta. Email hello@mint.gg for access. After access is enabled, create an API key in Mint from Developer. Send it as a Bearer token: 
curl https://api.mint.gg/v1/me \
  -H "Authorization: Bearer your_api_key"

​
Start a generation

Use action routes to start generation: 
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: 
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: 
{
  "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: 
{
  "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: 
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: 
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: 
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: 
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.