---
title: "Create world generation task"
method: POST
path: "/v1/worlds/generations"
tags: ["Worlds"]
---

# Create world generation task

`POST /v1/worlds/generations`

## Request

- Base URL: `https://api.tokenlab.sh`
- URL: `https://api.tokenlab.sh/v1/worlds/generations`
- Auth: HTTP bearer

Creates a World Labs Marble world generation task for TokenLab-supported Marble models. Returns a task ID for polling. TokenLab supports native world_prompt media_asset references when the media asset was prepared through TokenLab.

## Headers

- `X-TokenLab-Delivery-Policy` 'auto' | 'verified' | 'official'

## Request body

- union
  - object
    - `model` 'marble-1.0' | 'marble-1.1' | 'marble-1.1-plus': Marble model to use. Defaults to marble-1.0 to match the current World Labs compatibility default when model is omitted.
    - `prompt` string: Text prompt used for text or guided image/video world generation.
    - `display_name` string: Optional display name for the generated world, up to 64 characters.
    - `world_prompt` object, required: Native World Labs world_prompt object for advanced callers. Supported prompt types are text, image, multi-image, and video. Content references may use source=media_asset with a media_asset_id prepared by /v1/worlds/media-assets/prepare-upload.
    - `image` string: Base64 or data URL image prompt.
    - `image_url` string, uri: Image URL prompt.
    - `images` union[]: Shortcut multi-image prompts. Provide up to 4 images. Use native world_prompt.reconstruct_images=true for up to 8 images.
      - union
        - string
        - object
          - `uri` string
          - `image_url` string
          - `url` string
          - `azimuth` number
    - `video_url` string, uri: Video URL prompt.
    - `is_pano` union: Whether an image prompt is an existing panorama. Use true for pano input, false for single-image input, or auto.
      - boolean
      - 'auto'
    - `seed` integer: Optional seed from 0 through 4294967295.
    - `tags` string[]: Optional World Labs tags. Provide up to 10 tags, each up to 32 characters.
    - `permission` object: Optional World Labs permission object.
    - `user` string: End-user identifier.
  - object
    - `model` 'marble-1.0' | 'marble-1.1' | 'marble-1.1-plus': Marble model to use. Defaults to marble-1.0 to match the current World Labs compatibility default when model is omitted.
    - `prompt` string, required: Text prompt used for text or guided image/video world generation.
    - `display_name` string: Optional display name for the generated world, up to 64 characters.
    - `world_prompt` object: Native World Labs world_prompt object for advanced callers. Supported prompt types are text, image, multi-image, and video. Content references may use source=media_asset with a media_asset_id prepared by /v1/worlds/media-assets/prepare-upload.
    - `image` string: Base64 or data URL image prompt.
    - `image_url` string, uri: Image URL prompt.
    - `images` union[]: Shortcut multi-image prompts. Provide up to 4 images. Use native world_prompt.reconstruct_images=true for up to 8 images.
      - union
        - string
        - object
          - `uri` string
          - `image_url` string
          - `url` string
          - `azimuth` number
    - `video_url` string, uri: Video URL prompt.
    - `is_pano` union: Whether an image prompt is an existing panorama. Use true for pano input, false for single-image input, or auto.
      - boolean
      - 'auto'
    - `seed` integer: Optional seed from 0 through 4294967295.
    - `tags` string[]: Optional World Labs tags. Provide up to 10 tags, each up to 32 characters.
    - `permission` object: Optional World Labs permission object.
    - `user` string: End-user identifier.
  - object
    - `model` 'marble-1.0' | 'marble-1.1' | 'marble-1.1-plus': Marble model to use. Defaults to marble-1.0 to match the current World Labs compatibility default when model is omitted.
    - `prompt` string: Text prompt used for text or guided image/video world generation.
    - `display_name` string: Optional display name for the generated world, up to 64 characters.
    - `world_prompt` object: Native World Labs world_prompt object for advanced callers. Supported prompt types are text, image, multi-image, and video. Content references may use source=media_asset with a media_asset_id prepared by /v1/worlds/media-assets/prepare-upload.
    - `image` string, required: Base64 or data URL image prompt.
    - `image_url` string, uri: Image URL prompt.
    - `images` union[]: Shortcut multi-image prompts. Provide up to 4 images. Use native world_prompt.reconstruct_images=true for up to 8 images.
      - union
        - string
        - object
          - `uri` string
          - `image_url` string
          - `url` string
          - `azimuth` number
    - `video_url` string, uri: Video URL prompt.
    - `is_pano` union: Whether an image prompt is an existing panorama. Use true for pano input, false for single-image input, or auto.
      - boolean
      - 'auto'
    - `seed` integer: Optional seed from 0 through 4294967295.
    - `tags` string[]: Optional World Labs tags. Provide up to 10 tags, each up to 32 characters.
    - `permission` object: Optional World Labs permission object.
    - `user` string: End-user identifier.
  - object
    - `model` 'marble-1.0' | 'marble-1.1' | 'marble-1.1-plus': Marble model to use. Defaults to marble-1.0 to match the current World Labs compatibility default when model is omitted.
    - `prompt` string: Text prompt used for text or guided image/video world generation.
    - `display_name` string: Optional display name for the generated world, up to 64 characters.
    - `world_prompt` object: Native World Labs world_prompt object for advanced callers. Supported prompt types are text, image, multi-image, and video. Content references may use source=media_asset with a media_asset_id prepared by /v1/worlds/media-assets/prepare-upload.
    - `image` string: Base64 or data URL image prompt.
    - `image_url` string, uri, required: Image URL prompt.
    - `images` union[]: Shortcut multi-image prompts. Provide up to 4 images. Use native world_prompt.reconstruct_images=true for up to 8 images.
      - union
        - string
        - object
          - `uri` string
          - `image_url` string
          - `url` string
          - `azimuth` number
    - `video_url` string, uri: Video URL prompt.
    - `is_pano` union: Whether an image prompt is an existing panorama. Use true for pano input, false for single-image input, or auto.
      - boolean
      - 'auto'
    - `seed` integer: Optional seed from 0 through 4294967295.
    - `tags` string[]: Optional World Labs tags. Provide up to 10 tags, each up to 32 characters.
    - `permission` object: Optional World Labs permission object.
    - `user` string: End-user identifier.
  - object
    - `model` 'marble-1.0' | 'marble-1.1' | 'marble-1.1-plus': Marble model to use. Defaults to marble-1.0 to match the current World Labs compatibility default when model is omitted.
    - `prompt` string: Text prompt used for text or guided image/video world generation.
    - `display_name` string: Optional display name for the generated world, up to 64 characters.
    - `world_prompt` object: Native World Labs world_prompt object for advanced callers. Supported prompt types are text, image, multi-image, and video. Content references may use source=media_asset with a media_asset_id prepared by /v1/worlds/media-assets/prepare-upload.
    - `image` string: Base64 or data URL image prompt.
    - `image_url` string, uri: Image URL prompt.
    - `images` union[], required: Shortcut multi-image prompts. Provide up to 4 images. Use native world_prompt.reconstruct_images=true for up to 8 images.
      - union
        - string
        - object
          - `uri` string
          - `image_url` string
          - `url` string
          - `azimuth` number
    - `video_url` string, uri: Video URL prompt.
    - `is_pano` union: Whether an image prompt is an existing panorama. Use true for pano input, false for single-image input, or auto.
      - boolean
      - 'auto'
    - `seed` integer: Optional seed from 0 through 4294967295.
    - `tags` string[]: Optional World Labs tags. Provide up to 10 tags, each up to 32 characters.
    - `permission` object: Optional World Labs permission object.
    - `user` string: End-user identifier.
  - object
    - `model` 'marble-1.0' | 'marble-1.1' | 'marble-1.1-plus': Marble model to use. Defaults to marble-1.0 to match the current World Labs compatibility default when model is omitted.
    - `prompt` string: Text prompt used for text or guided image/video world generation.
    - `display_name` string: Optional display name for the generated world, up to 64 characters.
    - `world_prompt` object: Native World Labs world_prompt object for advanced callers. Supported prompt types are text, image, multi-image, and video. Content references may use source=media_asset with a media_asset_id prepared by /v1/worlds/media-assets/prepare-upload.
    - `image` string: Base64 or data URL image prompt.
    - `image_url` string, uri: Image URL prompt.
    - `images` union[]: Shortcut multi-image prompts. Provide up to 4 images. Use native world_prompt.reconstruct_images=true for up to 8 images.
      - union
        - string
        - object
          - `uri` string
          - `image_url` string
          - `url` string
          - `azimuth` number
    - `video_url` string, uri, required: Video URL prompt.
    - `is_pano` union: Whether an image prompt is an existing panorama. Use true for pano input, false for single-image input, or auto.
      - boolean
      - 'auto'
    - `seed` integer: Optional seed from 0 through 4294967295.
    - `tags` string[]: Optional World Labs tags. Provide up to 10 tags, each up to 32 characters.
    - `permission` object: Optional World Labs permission object.
    - `user` string: End-user identifier.

## Response `200`

Task created

- object
  - `id` string
  - `task_id` string
  - `operation_id` string
  - `status` 'pending' | 'processing' | 'completed' | 'failed'
  - `poll_url` string
  - `world_id` string
  - `world_marble_url` string
  - `model_url` string
  - `glb_url` string
  - `pano_url` string
  - `thumbnail_url` string
  - `caption` string
  - `cost` object
  - `error` union: Why the task failed: a string, or an object with `message` and, when known, `type`, `code`, `param` and `retryable`.
    - string
    - object
      - `message` string, required
      - `type` string
      - `code` string
      - `param` string
      - `retryable` boolean
  - `error_details` AsyncTaskErrorDetails: Why a task failed. A status read returns HTTP 200 even for a failed task; `status` here is the status of the failure itself.
    - `projection_version` integer: `2` means `message` is the final reason for the failure.
    - `status` integer, required
    - `message` string, required
    - `type` string, required
    - `code` string, required
    - `param` string: The request field at fault, omitted when no specific field is known.
    - `retryable` boolean, required
    - `upstream` AsyncTaskUpstreamError: The upstream service's own error, present only for a task that ran on an Official route. Its `code` values are defined by the upstream service and may change; branch on `error_details.code` and `error_details.type`.
      - `source` string: Upstream service name, when known.
      - `code` string
      - `message` string, required
      - `param` string

## Other responses

- `401`: Unauthorized - Invalid or missing API key
- `503`: The requested Delivery tier is temporarily unavailable.

---

[API](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway.md) · [All operations](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/revisions/3208bfbcda22?raw)