Start a world generation operation

POST

worlds:generate

curl --request POST \
  --url https://api.mint.gg/v1/worlds:generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "name": "<string>",
  "generationMode": "auto",
  "generationPreset": "standard",
  "imageUrl": "<string>",
  "sourceImages": [
    "<string>"
  ]
}
'

import requests

url = "https://api.mint.gg/v1/worlds:generate"

payload = {
    "prompt": "<string>",
    "name": "<string>",
    "generationMode": "auto",
    "generationPreset": "standard",
    "imageUrl": "<string>",
    "sourceImages": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    name: '<string>',
    generationMode: 'auto',
    generationPreset: 'standard',
    imageUrl: '<string>',
    sourceImages: ['<string>']
  })
};

fetch('https://api.mint.gg/v1/worlds:generate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mint.gg/v1/worlds:generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'name' => '<string>',
    'generationMode' => 'auto',
    'generationPreset' => 'standard',
    'imageUrl' => '<string>',
    'sourceImages' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mint.gg/v1/worlds:generate"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"name\": \"<string>\",\n  \"generationMode\": \"auto\",\n  \"generationPreset\": \"standard\",\n  \"imageUrl\": \"<string>\",\n  \"sourceImages\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.mint.gg/v1/worlds:generate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"name\": \"<string>\",\n  \"generationMode\": \"auto\",\n  \"generationPreset\": \"standard\",\n  \"imageUrl\": \"<string>\",\n  \"sourceImages\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mint.gg/v1/worlds:generate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"name\": \"<string>\",\n  \"generationMode\": \"auto\",\n  \"generationPreset\": \"standard\",\n  \"imageUrl\": \"<string>\",\n  \"sourceImages\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "object": "operation",
  "id": "op_01JEXAMPLE",
  "type": "world_generation",
  "generationMode": "auto",
  "status": "running",
  "resource": {
    "type": "world",
    "id": "world_01JEXAMPLE"
  },
  "createdAt": "2026-07-21T20:00:00.000Z",
  "updatedAt": "2026-07-21T20:00:01.000Z"
}

{
  "object": "operation",
  "id": "op_01JEXAMPLE",
  "type": "world_generation",
  "generationMode": "auto",
  "status": "running",
  "resource": {
    "type": "world",
    "id": "world_01JEXAMPLE"
  },
  "createdAt": "2026-07-21T20:00:00.000Z",
  "updatedAt": "2026-07-21T20:00:01.000Z"
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

Authorizations

Authorization

string

header

required

Mint API key sent as a Bearer token.

Headers

Idempotency-Key

string

Optional stable key for safely retrying an uncertain mutating request. Mint creates an internal key when this header is omitted. Reusing a supplied key with different parameters returns 409.

Required string length: 1 - 255

Body

application/json

Instructions for creating one World.

prompt

string

required

Describe the World Mint should create.

Required string length: 1 - 8000

name

string

Optional World title shown in Mint; Mint derives one from the prompt when omitted.

Required string length: 1 - 120

generationMode

enum<string>

default:auto

Workflow behavior. auto is the default and continues to the final asset; review pauses at Preview for approval or revision. See Preview-based generation.

Available options:

auto,

review

generationPreset

enum<string>

default:standard

Quality, speed, and cost tier; Mint selects the underlying generation model.

Available options:

fast,

standard,

production

imageUrl

string<uri>

One public HTTPS reference image for visual guidance; do not combine with sourceImages.

sourceImages

string<uri>[]

Two to eight public HTTPS reference images used together for visual guidance; do not combine with imageUrl.

Required array length: 2 - 8 elements

Response

An earlier request with the same retry key returned this operation.

A long-running operation acting on one Mint world.

object

string

required

Stable object discriminator.

Allowed value: "operation"

string

required

Mint operation ID used for polling.

type

enum<string>

required

The work this operation performs.

Available options:

world_generation

generationMode

enum<string>

required

Workflow mode for this operation.

Available options:

auto,

review

status

enum<string>

required

Current operation lifecycle status.

Available options:

queued,

running,

preview_ready,

billing_required,

succeeded,

partially_succeeded,

failed,

canceled

resource

object | null

required

The Mint asset created by this operation, or null before the asset exists.

Show child attributes

createdAt

string<date-time>

required

When the operation was created.

updatedAt

string<date-time>

required

When the operation last changed.

prompt

string

Developer-supplied generation brief or revision feedback.

generationPreset

enum<string>

Public generation preset selected for this operation.

Available options:

fast,

standard,

production

assets

object

Generated world files when available.

Show child attributes

billing

object

The billing action required before this operation can continue.

Show child attributes

credits

object

Credit estimate, active reservation, finalized charge, and post-reservation balance for this operation.

Show child attributes

error

object

Terminal failure details when the operation failed.

Show child attributes

completedAt

string<date-time>

When the operation completed.

canceledAt

string<date-time>

When the operation was canceled.

List worlds owned by the accountList worlds owned by the account.

Start a world generation operation

curl --request POST \
  --url https://api.mint.gg/v1/worlds:generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "name": "<string>",
  "generationMode": "auto",
  "generationPreset": "standard",
  "imageUrl": "<string>",
  "sourceImages": [
    "<string>"
  ]
}
'

import requests

url = "https://api.mint.gg/v1/worlds:generate"

payload = {
    "prompt": "<string>",
    "name": "<string>",
    "generationMode": "auto",
    "generationPreset": "standard",
    "imageUrl": "<string>",
    "sourceImages": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    name: '<string>',
    generationMode: 'auto',
    generationPreset: 'standard',
    imageUrl: '<string>',
    sourceImages: ['<string>']
  })
};

fetch('https://api.mint.gg/v1/worlds:generate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mint.gg/v1/worlds:generate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'name' => '<string>',
    'generationMode' => 'auto',
    'generationPreset' => 'standard',
    'imageUrl' => '<string>',
    'sourceImages' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mint.gg/v1/worlds:generate"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"name\": \"<string>\",\n  \"generationMode\": \"auto\",\n  \"generationPreset\": \"standard\",\n  \"imageUrl\": \"<string>\",\n  \"sourceImages\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.mint.gg/v1/worlds:generate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"name\": \"<string>\",\n  \"generationMode\": \"auto\",\n  \"generationPreset\": \"standard\",\n  \"imageUrl\": \"<string>\",\n  \"sourceImages\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mint.gg/v1/worlds:generate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"name\": \"<string>\",\n  \"generationMode\": \"auto\",\n  \"generationPreset\": \"standard\",\n  \"imageUrl\": \"<string>\",\n  \"sourceImages\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "object": "operation",
  "id": "op_01JEXAMPLE",
  "type": "world_generation",
  "generationMode": "auto",
  "status": "running",
  "resource": {
    "type": "world",
    "id": "world_01JEXAMPLE"
  },
  "createdAt": "2026-07-21T20:00:00.000Z",
  "updatedAt": "2026-07-21T20:00:01.000Z"
}

{
  "object": "operation",
  "id": "op_01JEXAMPLE",
  "type": "world_generation",
  "generationMode": "auto",
  "status": "running",
  "resource": {
    "type": "world",
    "id": "world_01JEXAMPLE"
  },
  "createdAt": "2026-07-21T20:00:00.000Z",
  "updatedAt": "2026-07-21T20:00:01.000Z"
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>",
  "errors": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ],
  "operationId": "<string>",
  "billing": {
    "requiredCredits": 1,
    "actionUrl": "<string>",
    "availableCredits": 1,
    "committedCredits": 1,
    "stageCredits": 1,
    "completionCredits": 1
  }
}

Get Started

API References

API Guides

MCP

Agent Tooling

Start a world generation operation

Authorizations

Headers

Body

Response