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

  • Base URL
    https://api.worldlabs.ai
  • Auth
    API key in header WLT-Api-Key

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

responseunknown
updated_atstring date-time nullable

Last update timestamp

Changes

    • info

      added data_base64 media_asset uri discriminator mapping keys to the // request property

    • info

      added data_base64 media_asset uri discriminator mapping keys to the //// request property

    • info

      added data_base64 media_asset uri discriminator mapping keys to the // request property

    • info

      added image multi-image text video discriminator mapping keys to the request property