---
title: "Generate World"
method: POST
path: "/marble/v1/worlds:generate"
---

# Generate World

`POST /marble/v1/worlds:generate`

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

## Request body

- WorldsGenerateRequest — Request to generate a world from text, image, multi-image, or video input.
  - `display_name` string, 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.
  - `model` union — The model to use for generation. marble-1.1-plus includes dynamic world sizing. Legacy names ('Marble 0.1-plus', etc.) still work but are deprecated and will be removed in a future release.
    - 'marble-1.0-draft' | 'marble-1.0' | 'marble-1.1' | 'marble-1.1-plus'
    - 'Marble 0.1-mini' | 'Marble 0.1-plus' | 'Marble 1.1-plus'
  - `permission` Permission — Access control permissions for a resource.
    - `allow_id_access` boolean
    - `allowed_readers` string[]
    - `allowed_writers` string[]
    - `public` boolean
  - `seed` integer, nullable — Random seed for generation
  - `tags` string[], nullable — Optional tags for the world (max 10 tags, each up to 32 characters)
  - `world_prompt` union, required — The prompt specifying how to generate the world
    - WorldTextPromptInput — Text-to-world generation. Generates a world from a text description. text_prompt is REQUIRED.
      - `disable_recaption` boolean, nullable — If True, use text_prompt as-is without recaptioning
      - `text_prompt` string, nullable — Optional text guidance (auto-generated if not provided)
      - `type` 'text'
    - ImagePrompt — Image-to-world generation. Generates a world from an image. text_prompt is optional - if not provided, it will be generated via recaptioning. Recommended image formats: jpg, jpeg, png, webp.
      - `disable_recaption` boolean, nullable — If True, use text_prompt as-is without recaptioning
      - `image_prompt` union, required — Image content for world generation
        - MediaAssetReference — Reference to a previously uploaded MediaAsset.
          - `media_asset_id` string, required — ID of a MediaAsset resource previously created and marked READY
          - `source` 'media_asset'
        - UriReference — Reference to content via a publicly accessible URL.
          - `source` 'uri'
          - `uri` string, required — Publicly accessible URL pointing to the media
        - DataBase64Reference — Reference to content via base64-encoded data.
          - `data_base64` string, required — Base64-encoded content data
          - `extension` string, nullable — File extension without dot (e.g., 'jpg', 'png')
          - `source` 'data_base64'
      - `is_pano` unknown
      - `text_prompt` string, nullable — Optional text guidance (auto-generated if not provided)
      - `type` 'image'
    - MultiImagePromptInput — Multi-image-to-world generation. Generates a world from multiple images. text_prompt is optional. Recommended image formats: jpg, jpeg, png, webp.
      - `disable_recaption` boolean, nullable — If True, use text_prompt as-is without recaptioning
      - `multi_image_prompt` SphericallyLocatedContentInput[], required — List of images with optional spherical locations
        - `azimuth` number, nullable — Azimuth angle in degrees
        - `content` union, required — The content at this location
          - MediaAssetReference — Reference to a previously uploaded MediaAsset.
            - `media_asset_id` string, required — ID of a MediaAsset resource previously created and marked READY
            - `source` 'media_asset'
          - UriReference — Reference to content via a publicly accessible URL.
            - `source` 'uri'
            - `uri` string, required — Publicly accessible URL pointing to the media
          - DataBase64Reference — Reference to content via base64-encoded data.
            - `data_base64` string, required — Base64-encoded content data
            - `extension` string, nullable — File extension without dot (e.g., 'jpg', 'png')
            - `source` 'data_base64'
      - `reconstruct_images` boolean — Whether to use reconstruction mode (allows up to 8 images, otherwise 4)
      - `text_prompt` string, nullable — Optional text guidance (auto-generated if not provided)
      - `type` 'multi-image'
    - VideoPromptInput — Video-to-world generation. Generates a world from a video. text_prompt is optional. Recommended video formats: mp4, webm, mov, avi. Maximum video size: 100MB.
      - `disable_recaption` boolean, nullable — If True, use text_prompt as-is without recaptioning
      - `text_prompt` string, nullable — Optional text guidance (auto-generated if not provided)
      - `type` 'video'
      - `video_prompt` union, required — Video content for world generation
        - MediaAssetReference — Reference to a previously uploaded MediaAsset.
          - `media_asset_id` string, required — ID of a MediaAsset resource previously created and marked READY
          - `source` 'media_asset'
        - UriReference — Reference to content via a publicly accessible URL.
          - `source` 'uri'
          - `uri` string, required — Publicly accessible URL pointing to the media
        - DataBase64Reference — Reference to content via base64-encoded data.
          - `data_base64` string, required — Base64-encoded content data
          - `extension` string, nullable — File extension without dot (e.g., 'jpg', 'png')
          - `source` 'data_base64'

## Response `200`

Successful Response

- GenerateWorldResponse — Response from world generation endpoint.
  - `cost` OperationCost — Settled credit cost for a successful operation.
    - `line_items` OperationCostLineItem[] — Usage events that make up the operation's total credits
      - `credits` integer, required — Credits charged for this usage event
      - `name` string, required — Human-readable usage event name
    - `total_credits` integer, required — Total credits charged for the operation
  - `created_at` string, date-time, nullable — Creation timestamp
  - `done` boolean, required — True if the operation is completed
  - `error` OperationError — Error information for a failed operation.
    - `code` integer, nullable — Error code
    - `message` string, nullable — Error message
  - `expires_at` string, date-time, nullable — Expiration timestamp
  - `metadata` object, nullable — Service-specific metadata, such as progress percentage
  - `operation_id` string, required — Operation identifier
  - `response` unknown
  - `updated_at` string, date-time, nullable — Last update timestamp

## Other responses

- `402` — The account has insufficient API credits for this request.
- `422` — Validation Error

---

[API](https://skmtc.dev/worldlabs/apis/marble-public-api-v1.md) · [All operations](https://skmtc.dev/worldlabs/apis/marble-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/worldlabs/apis/marble-public-api-v1/revisions/731ef579549c?raw)