Sign in

v1

latestOpenAPI 3.1.02026-07-26104450.2 KB

Generate World

Start world generation.

Creates a new world generation job and returns a long-running operation. Poll the /operations/{operation_id} endpoint to check generation status and retrieve the generated world when complete.

Args: request: The world generation request containing world_prompt, display_name, tags, model, seed, and permission settings.

Returns: GenerateWorldResponse with operation_id and timestamps. Use the operation_id to poll for completion.

Raises: HTTPException: 400 if invalid request or content violates policies HTTPException: 402 if insufficient credits HTTPException: 500 if generation could not be started

post/marble/v1/worlds:generate

Request body

display_namestring nullable

Optional human-readable title for the world (max 64 characters). Stored as world metadata and returned in world responses; does not affect generation. If omitted, World Labs may generate a title from the prompt.

seedinteger nullable

Random seed for generation

tagsstring[] nullable

Optional tags for the world (max 10 tags, each up to 32 characters)

Example request

{
  "display_name": "Coastal Castle",
  "model": "marble-1.0",
  "permission": {
    "public": false
  },
  "seed": 42,
  "tags": [
    "fantasy",
    "coastal"
  ],
  "world_prompt": {
    "text_prompt": "A grand, ivy-covered castle rises from the shoreline at sunset, its reflection shimmering in the tranquil ocean waves.",
    "type": "text"
  }
}

Response

Successful Response

created_atstring date-time nullable

Creation timestamp

doneboolean required

True if the operation is completed

expires_atstring date-time nullable

Expiration timestamp

metadataobject nullable

Service-specific metadata, such as progress percentage

operation_idstring required

Operation identifier

{"stackTrail":"components:schemas:GenerateWorldResponse:properties:response:anyOf","oasType":"schema","type":"unknown","title":"Response","description":"Result payload when done=true and no error. Structure depends on operation type.","nullable":true}
updated_atstring date-time nullable

Last update timestamp