> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate a 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



## OpenAPI

````yaml POST /marble/v1/worlds:generate
openapi: 3.1.0
info:
  description: Public-facing API for the Marble platform
  summary: Marble Public API v1
  title: Marble Public API v1
  version: 1.0.0
servers:
  - description: World API
    url: https://api.worldlabs.ai
security:
  - ApiKeyAuth: []
paths:
  /marble/v1/worlds:generate:
    post:
      summary: Generate World
      description: |-
        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
      operationId: generate_world_marble_v1_worlds_generate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorldsGenerateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateWorldResponse'
          description: Successful Response
        '402':
          content:
            application/json:
              example:
                detail: >-
                  Insufficient API credits to start this request. Add credits or
                  enable auto-refill at https://platform.worldlabs.ai/billing.
          description: The account has insufficient API credits for this request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
components:
  schemas:
    WorldsGenerateRequest:
      description: >-
        Request to generate a world from text, image, multi-image, or video
        input.
      examples:
        - 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
        - display_name: Greenhouse Workshop
          model: marble-1.0-draft
          world_prompt:
            image_prompt:
              source: uri
              uri: https://example.com/my-image.jpg
            text_prompt: >-
              A peaceful, sunlit greenhouse workshop filled with plants and
              glassware, where soft light filters through cracked windows and
              ivy creeps along the walls.
            type: image
        - display_name: World from an Existing Pano
          model: marble-1.1
          world_prompt:
            image_prompt:
              source: uri
              uri: https://example.com/my-equirect-pano.jpg
            is_pano: auto
            type: image
        - permission:
            public: true
          world_prompt:
            type: video
            video_prompt:
              media_asset_id: 550e8400e29b41d4a716446655440000
              source: media_asset
        - display_name: World from Multiple Images
          model: marble-1.1
          world_prompt:
            multi_image_prompt:
              - azimuth: 0
                content:
                  source: uri
                  uri: https://example.com/image1.jpg
              - azimuth: 180
                content:
                  source: uri
                  uri: https://example.com/image2.jpg
            type: multi-image
      properties:
        display_name:
          anyOf:
            - maxLength: 64
              type: string
            - type: 'null'
          description: >-
            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.
          title: Display Name
        model:
          anyOf:
            - enum:
                - marble-1.0-draft
                - marble-1.0
                - marble-1.1
                - marble-1.1-plus
              type: string
            - enum:
                - Marble 0.1-mini
                - Marble 0.1-plus
                - Marble 1.1-plus
              type: string
          default: marble-1.1
          description: >-
            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.
          title: Model
        permission:
          $ref: '#/components/schemas/Permission'
          default:
            allow_id_access: false
            allowed_readers: []
            allowed_writers: []
            public: false
          description: The permission for the world
        seed:
          anyOf:
            - maximum: 4294967295
              minimum: 0
              type: integer
            - type: 'null'
          description: Random seed for generation
          title: Seed
        tags:
          anyOf:
            - items:
                type: string
              maxItems: 10
              type: array
            - type: 'null'
          description: Optional tags for the world (max 10 tags, each up to 32 characters)
          title: Tags
        world_prompt:
          description: The prompt specifying how to generate the world
          discriminator:
            mapping:
              image:
                $ref: '#/components/schemas/ImagePrompt'
              multi-image:
                $ref: '#/components/schemas/MultiImagePrompt-Input'
              text:
                $ref: '#/components/schemas/WorldTextPrompt-Input'
              video:
                $ref: '#/components/schemas/VideoPrompt-Input'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/WorldTextPrompt-Input'
            - $ref: '#/components/schemas/ImagePrompt'
            - $ref: '#/components/schemas/MultiImagePrompt-Input'
            - $ref: '#/components/schemas/VideoPrompt-Input'
          title: World Prompt
      required:
        - world_prompt
      title: WorldsGenerateRequest
      type: object
    GenerateWorldResponse:
      description: Response from world generation endpoint.
      properties:
        cost:
          anyOf:
            - $ref: '#/components/schemas/OperationCost'
            - type: 'null'
          description: >-
            Settled credit cost for the operation. Populated only on successful
            completion.
        created_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Creation timestamp
          title: Created At
        done:
          description: True if the operation is completed
          title: Done
          type: boolean
        error:
          anyOf:
            - $ref: '#/components/schemas/OperationError'
            - type: 'null'
          description: Error information if the operation failed
        expires_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Expiration timestamp
          title: Expires At
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Service-specific metadata, such as progress percentage
          title: Metadata
        operation_id:
          description: Operation identifier
          title: Operation Id
          type: string
        response:
          anyOf:
            - {}
            - type: 'null'
          description: >-
            Result payload when done=true and no error. Structure depends on
            operation type.
          title: Response
        updated_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Last update timestamp
          title: Updated At
      required:
        - operation_id
        - done
      title: GenerateWorldResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    Permission:
      description: Access control permissions for a resource.
      properties:
        allow_id_access:
          default: false
          title: Allow Id Access
          type: boolean
        allowed_readers:
          items:
            type: string
          title: Allowed Readers
          type: array
        allowed_writers:
          items:
            type: string
          title: Allowed Writers
          type: array
        public:
          default: false
          title: Public
          type: boolean
      title: Permission
      type: object
    ImagePrompt:
      description: >-
        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.
      properties:
        disable_recaption:
          anyOf:
            - type: boolean
            - type: 'null'
          description: If True, use text_prompt as-is without recaptioning
          title: Disable Recaption
        image_prompt:
          description: Image content for world generation
          discriminator:
            mapping:
              data_base64:
                $ref: '#/components/schemas/DataBase64Reference'
              media_asset:
                $ref: '#/components/schemas/MediaAssetReference'
              uri:
                $ref: '#/components/schemas/UriReference'
            propertyName: source
          oneOf:
            - $ref: '#/components/schemas/MediaAssetReference'
            - $ref: '#/components/schemas/UriReference'
            - $ref: '#/components/schemas/DataBase64Reference'
          title: Image Prompt
        is_pano:
          $ref: '#/components/schemas/PanoDetectionMode'
          default: auto
          description: >-
            How to treat the image input as a panorama. `auto` detects valid
            equirectangular panoramas, `true` always uses the image as a
            panorama, and `false` treats it as a standard image.
        text_prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional text guidance (auto-generated if not provided)
          title: Text Prompt
        type:
          const: image
          default: image
          title: Type
          type: string
      required:
        - image_prompt
      title: ImagePrompt
      type: object
    MultiImagePrompt-Input:
      description: |-
        Multi-image-to-world generation.

        Generates a world from multiple images. text_prompt is optional.

        Recommended image formats: jpg, jpeg, png, webp.
      properties:
        disable_recaption:
          anyOf:
            - type: boolean
            - type: 'null'
          description: If True, use text_prompt as-is without recaptioning
          title: Disable Recaption
        multi_image_prompt:
          description: List of images with optional spherical locations
          items:
            $ref: '#/components/schemas/SphericallyLocatedContent-Input'
          title: Multi Image Prompt
          type: array
        reconstruct_images:
          default: false
          description: >-
            Whether to use reconstruction mode (allows up to 8 images, otherwise
            4)
          title: Reconstruct Images
          type: boolean
        text_prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional text guidance (auto-generated if not provided)
          title: Text Prompt
        type:
          const: multi-image
          default: multi-image
          title: Type
          type: string
      required:
        - multi_image_prompt
      title: MultiImagePrompt
      type: object
    WorldTextPrompt-Input:
      description: |-
        Text-to-world generation.

        Generates a world from a text description. text_prompt is REQUIRED.
      properties:
        disable_recaption:
          anyOf:
            - type: boolean
            - type: 'null'
          description: If True, use text_prompt as-is without recaptioning
          title: Disable Recaption
        text_prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional text guidance (auto-generated if not provided)
          title: Text Prompt
        type:
          const: text
          default: text
          title: Type
          type: string
      title: WorldTextPrompt
      type: object
    VideoPrompt-Input:
      description: |-
        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.
      properties:
        disable_recaption:
          anyOf:
            - type: boolean
            - type: 'null'
          description: If True, use text_prompt as-is without recaptioning
          title: Disable Recaption
        text_prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional text guidance (auto-generated if not provided)
          title: Text Prompt
        type:
          const: video
          default: video
          title: Type
          type: string
        video_prompt:
          description: Video content for world generation
          discriminator:
            mapping:
              data_base64:
                $ref: '#/components/schemas/DataBase64Reference'
              media_asset:
                $ref: '#/components/schemas/MediaAssetReference'
              uri:
                $ref: '#/components/schemas/UriReference'
            propertyName: source
          oneOf:
            - $ref: '#/components/schemas/MediaAssetReference'
            - $ref: '#/components/schemas/UriReference'
            - $ref: '#/components/schemas/DataBase64Reference'
          title: Video Prompt
      required:
        - video_prompt
      title: VideoPrompt
      type: object
    OperationCost:
      description: Settled credit cost for a successful operation.
      properties:
        line_items:
          description: Usage events that make up the operation's total credits
          items:
            $ref: '#/components/schemas/OperationCostLineItem'
          title: Line Items
          type: array
        total_credits:
          description: Total credits charged for the operation
          title: Total Credits
          type: integer
      required:
        - total_credits
      title: OperationCost
      type: object
    OperationError:
      description: Error information for a failed operation.
      properties:
        code:
          anyOf:
            - type: integer
            - type: 'null'
          description: Error code
          title: Code
        message:
          anyOf:
            - type: string
            - type: 'null'
          description: Error message
          title: Message
      title: OperationError
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    DataBase64Reference:
      description: Reference to content via base64-encoded data.
      properties:
        data_base64:
          description: Base64-encoded content data
          title: Data Base64
          type: string
        extension:
          anyOf:
            - type: string
            - type: 'null'
          description: File extension without dot (e.g., 'jpg', 'png')
          title: Extension
        source:
          const: data_base64
          default: data_base64
          title: Source
          type: string
      required:
        - data_base64
      title: DataBase64Reference
      type: object
    MediaAssetReference:
      description: Reference to a previously uploaded MediaAsset.
      properties:
        media_asset_id:
          description: ID of a MediaAsset resource previously created and marked READY
          title: Media Asset Id
          type: string
        source:
          const: media_asset
          default: media_asset
          title: Source
          type: string
      required:
        - media_asset_id
      title: MediaAssetReference
      type: object
    UriReference:
      description: Reference to content via a publicly accessible URL.
      properties:
        source:
          const: uri
          default: uri
          title: Source
          type: string
        uri:
          description: Publicly accessible URL pointing to the media
          title: Uri
          type: string
      required:
        - uri
      title: UriReference
      type: object
    PanoDetectionMode:
      enum:
        - auto
        - true
        - false
    SphericallyLocatedContent-Input:
      description: Content with a preferred location on the sphere.
      properties:
        azimuth:
          anyOf:
            - type: number
            - type: 'null'
          description: Azimuth angle in degrees
          title: Azimuth
        content:
          description: The content at this location
          discriminator:
            mapping:
              data_base64:
                $ref: '#/components/schemas/DataBase64Reference'
              media_asset:
                $ref: '#/components/schemas/MediaAssetReference'
              uri:
                $ref: '#/components/schemas/UriReference'
            propertyName: source
          oneOf:
            - $ref: '#/components/schemas/MediaAssetReference'
            - $ref: '#/components/schemas/UriReference'
            - $ref: '#/components/schemas/DataBase64Reference'
          title: Content
      required:
        - content
      title: SphericallyLocatedContent
      type: object
    OperationCostLineItem:
      description: A single usage event contributing to an operation's total credits.
      properties:
        credits:
          description: Credits charged for this usage event
          title: Credits
          type: integer
        name:
          description: Human-readable usage event name
          title: Name
          type: string
      required:
        - name
        - credits
      title: OperationCostLineItem
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: API key for authentication. Get your key from the developer portal.
      in: header
      name: WLT-Api-Key
      type: apiKey

````