> ## 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. # OpenAPI spec > View the OpenAPI specification file We use an OpenAPI spec to generate endpoint documentation. You can consume the spec directly or browse API reference pages. ````yaml theme={null} components: schemas: Content: description: 'Represents content (media, text, images) that can be stored inline or via URL. Supports both direct data storage (up to 10MB) and URL references (up to 20MB).' properties: data_base64: anyOf: - type: string - type: 'null' title: Data Base64 extension: anyOf: - type: string - type: 'null' description: File extension without dot examples: - jpg - png - pdf - txt title: Extension uri: anyOf: - type: string - type: 'null' title: Uri title: Content type: object CreditsResponse: description: Remaining credits for the authenticated API user. properties: remaining_credits: description: Remaining API credits available to the authenticated user. minimum: 0.0 title: Remaining Credits type: number required: - remaining_credits title: CreditsResponse 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 DeleteWorldResponse: description: Response from world deletion endpoint. properties: deleted: description: Whether the world was successfully deleted title: Deleted type: boolean world_id: description: ID of the deleted world title: World Id type: string required: - world_id - deleted title: DeleteWorldResponse type: object DepthPanoPrompt: description: 'For models conditioned on a depth pano and text. When depth_pano_image is a log-encoded PNG, z_min and z_max are required to decode it correctly. When it is an EXR file containing raw float depth values, z_min and z_max will both be ignored. Please set z_min and z_max both to None when using an EXR file.' properties: depth_pano_image: $ref: '#/components/schemas/Content' text_prompt: anyOf: - type: string - type: 'null' title: Text Prompt type: const: depth-pano default: depth-pano title: Type type: string z_max: anyOf: - type: number - type: 'null' title: Z Max z_min: anyOf: - type: number - type: 'null' title: Z Min required: - depth_pano_image title: DepthPanoPrompt 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 GetOperationResponse_Union_World__PanoDepthToRgbResult__: 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: - $ref: '#/components/schemas/World' - $ref: '#/components/schemas/PanoDepthToRgbResult' - 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: GetOperationResponse[Union[World, PanoDepthToRgbResult]] type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError 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: '#/components/schemas/DataBase64Reference' media_asset: '#/components/schemas/MediaAssetReference' uri: '#/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 ImageryAssets: description: Imagery asset URLs. properties: pano_url: anyOf: - type: string - type: 'null' description: Panorama image URL title: Pano Url title: ImageryAssets type: object InpaintPanoPrompt: description: For models that inpaint the masked portion of a pano image. properties: pano_image: $ref: '#/components/schemas/Content' pano_mask: $ref: '#/components/schemas/Content' text_prompt: anyOf: - type: string - type: 'null' title: Text Prompt type: const: inpaint-pano default: inpaint-pano title: Type type: string required: - pano_image - pano_mask title: InpaintPanoPrompt type: object ListWorldsRequest: description: Request to list API-generated worlds with optional filters. examples: - model: marble-1.0 page_size: 20 sort_by: created_at status: SUCCEEDED - page_size: 50 sort_by: created_at status: SUCCEEDED tags: - fantasy - nature - created_after: '2024-01-01T00:00:00Z' created_before: '2024-12-31T23:59:59Z' page_size: 100 sort_by: created_at - model: marble-1.0-draft page_size: 30 tags: - landscape - page_size: 20 page_token: eyJzbmFwc2hvdF90aW1lIjoiMjAyNC0wMS0wMVQwMDowMDowMFoiLCJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI0LTAxLTAxVDAwOjAwOjAwWiIsImxhc3RfaWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ== sort_by: created_at properties: created_after: anyOf: - format: date-time type: string - type: 'null' description: Filter worlds created after this timestamp (inclusive) title: Created After created_before: anyOf: - format: date-time type: string - type: 'null' description: Filter worlds created before this timestamp (exclusive) title: Created Before is_public: anyOf: - type: boolean - type: 'null' description: Filter by visibility. true=public only, false=private only, null=all title: Is Public 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 - type: 'null' description: Filter by model used for generation. Legacy names are deprecated; use the new lowercase names. title: Model page_size: default: 20 description: Number of results per page (1-100) maximum: 100.0 minimum: 1.0 title: Page Size type: integer page_token: anyOf: - type: string - type: 'null' description: Cursor token for pagination (opaque base64 string from previous response). Use cursor from next_page_token in previous response for consistent pagination. title: Page Token sort_by: default: created_at description: Sort results by created_at or updated_at enum: - created_at - updated_at title: Sort By type: string status: anyOf: - enum: - SUCCEEDED - PENDING - FAILED - RUNNING type: string - type: 'null' description: Filter by world status title: Status tags: anyOf: - items: type: string type: array - type: 'null' description: Filter by tags (returns worlds with ANY of these tags) title: Tags title: ListWorldsRequest type: object ListWorldsResponse: description: Response containing a list of API-generated worlds. properties: next_page_token: anyOf: - type: string - type: 'null' description: Token for fetching the next page of results title: Next Page Token worlds: description: List of worlds items: $ref: '#/components/schemas/World' title: Worlds type: array required: - worlds title: ListWorldsResponse type: object MediaAsset: description: 'A user-uploaded media asset stored in managed storage. MediaAssets can be images, videos, or binary blobs that are used as input to world generation.' properties: created_at: description: Creation timestamp format: date-time title: Created At type: string extension: anyOf: - type: string - type: 'null' description: File extension without dot examples: - mp4 - png - jpg title: Extension file_name: description: File name title: File Name type: string kind: $ref: '#/components/schemas/MediaAssetKind' description: High-level media type examples: - image - video media_asset_id: description: Server-generated media asset identifier title: Media Asset Id type: string metadata: anyOf: - additionalProperties: true type: object - type: 'null' description: Optional application-specific metadata title: Metadata updated_at: anyOf: - format: date-time type: string - type: 'null' description: Last update timestamp title: Updated At required: - media_asset_id - file_name - kind - created_at title: MediaAsset type: object MediaAssetKind: description: High-level media asset type. enum: - image - video title: MediaAssetKind type: string MediaAssetPrepareUploadRequest: description: Request to prepare a media asset upload. properties: extension: anyOf: - type: string - type: 'null' description: File extension without dot examples: - mp4 - png - jpg title: Extension file_name: description: File name maxLength: 64 title: File Name type: string kind: $ref: '#/components/schemas/MediaAssetKind' description: High-level media type examples: - image - video metadata: anyOf: - additionalProperties: true type: object - type: 'null' description: Optional application-specific metadata title: Metadata required: - file_name - kind title: MediaAssetPrepareUploadRequest type: object MediaAssetPrepareUploadResponse: description: Response from preparing a media asset upload. properties: media_asset: $ref: '#/components/schemas/MediaAsset' description: The created media asset upload_info: $ref: '#/components/schemas/UploadUrlInfo' description: Upload URL information required: - media_asset - upload_info title: MediaAssetPrepareUploadResponse 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 MeshAssets: description: Mesh asset URLs. properties: collider_mesh_url: anyOf: - type: string - type: 'null' description: Collider mesh URL title: Collider Mesh Url title: MeshAssets 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 MultiImagePrompt-Output: description: For world models supporting multi-image (+ text) input. properties: multi_image_prompt: items: $ref: '#/components/schemas/SphericallyLocatedContent-Output' title: Multi Image Prompt type: array reconstruct_images: default: false title: Reconstruct Images type: boolean text_prompt: anyOf: - type: string - type: 'null' title: Text Prompt type: const: multi-image default: multi-image title: Type type: string required: - multi_image_prompt title: MultiImagePrompt 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 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 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 Operation_PanoDepthToRgbResult_: 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: - $ref: '#/components/schemas/PanoDepthToRgbResult' - type: 'null' description: Result payload when done=true and no error. Structure depends on operation type. updated_at: anyOf: - format: date-time type: string - type: 'null' description: Last update timestamp title: Updated At required: - operation_id - done title: Operation[PanoDepthToRgbResult] type: object PanoDepthToRgbRequest: description: "Request to generate an RGB panorama from a depth panorama.\n\n\ Provide a depth panorama and a text prompt describing\nthe desired appearance.\ \ The depth map supplies the\nscene geometry; the model synthesizes textures\ \ that\nloosely adhere to that geometry and returns a panoramic RGB image.\n\ \nAccepted depth inputs:\n\n* **EXR**: float depth values. Omit ``z_min``\n\ \ and ``z_max``.\n* **PNG**: depth values normalized to [0, 1].\n Provide\ \ both ``z_min`` and ``z_max`` so the service\n can decode the PNG correctly.\n\ \nFor a complete PNG-based workflow, see the\n`web-chisel-depth-png example\ \ `.\n\ \nThis endpoint returns a long-running ``Operation``.\nPoll ``GET /operations/{operation_id}``\ \ until\n``done`` is ``true``, then read the generated\npanorama URL from\ \ ``response.pano_url``." examples: - depth_pano_image: source: uri uri: https://example.com/depth.exr text_prompt: The scene is a warm, rustic cabin interior with a realistic style and a cozy winter atmosphere. Wooden walls and exposed beams frame the room, while a stone fireplace casts soft amber light across simple furnishings and natural textures. The 360 scene is faultless. - depth_pano_image: source: uri uri: https://example.com/greenhouse-depth.exr text_prompt: A peaceful greenhouse workshop filled with plants and glassware, with soft sunlight, weathered wood, and ivy creeping along the walls. - depth_pano_image: source: uri uri: https://example.com/depth.png text_prompt: The scene is a warm Mediterranean kitchen rendered in a realistic style with a bright, welcoming coastal atmosphere. The overall tone is relaxed and sunlit, combining natural materials with crisp handcrafted details. Blue ceramic tiles wrap the backsplash and continue across key architectural surfaces, giving the room a cool accent against creamy plaster walls. Wooden cabinetry lines the perimeter in a balanced arrangement, with paneled doors, open shelving, and brass hardware contributing to the room's refined but lived-in character. A broad countertop of pale stone runs between the cabinets, creating a continuous work surface that anchors the cooking area. A central table with a solid wood top occupies the middle of the room, surrounded by simple chairs and small ceramic vessels that reinforce the artisanal style. Arched openings connect the kitchen to adjacent areas, while French doors admit generous daylight and suggest an outdoor terrace nearby. Terracotta accents, woven textures, and neatly arranged cookware add visual richness without cluttering the space. The cabinetry, tiled surfaces, and stone counters form a coherent ring around the room, while the table remains the central focal element within the composition. The 360 scene is faultless. z_max: 100.0 z_min: 0.1 properties: depth_pano_image: description: Depth panorama image (EXR or PNG). Provide via URI, media_asset, or base64 (max 100 MB). discriminator: mapping: data_base64: '#/components/schemas/DataBase64Reference' media_asset: '#/components/schemas/MediaAssetReference' uri: '#/components/schemas/UriReference' propertyName: source oneOf: - $ref: '#/components/schemas/MediaAssetReference' - $ref: '#/components/schemas/UriReference' - $ref: '#/components/schemas/DataBase64Reference' title: Depth Pano Image seed: anyOf: - maximum: 4294967295.0 minimum: 0.0 type: integer - type: 'null' description: Random seed for reproducible generation. title: Seed text_prompt: description: Text description of the desired appearance. title: Text Prompt type: string z_max: anyOf: - exclusiveMinimum: 0.0 type: number - type: 'null' description: Maximum depth. Required for PNG depth maps (normalized to [0, 1]). Must be provided together with z_min and must be greater than z_min. Omit for EXR depth maps. title: Z Max z_min: anyOf: - exclusiveMinimum: 0.0 type: number - type: 'null' description: Minimum depth. Required for PNG depth maps (normalized to [0, 1]). Must be provided together with z_max. Omit for EXR depth maps. title: Z Min required: - depth_pano_image - text_prompt title: PanoDepthToRgbRequest type: object PanoDepthToRgbResult: description: 'Result from depth-to-RGB panorama generation. Returned inside ``Operation.response`` when the operation completes successfully (``done=true``).' properties: pano_url: anyOf: - type: string - type: 'null' description: URL of the generated RGB panorama image. Available when the operation succeeds. title: Pano Url title: PanoDepthToRgbResult type: object PanoDetectionMode: enum: - auto - true - false 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 Prompt: description: 'For world models generating a world from a single image (+ text). Images can be generated using the :image-generation method. If no text prompt is provided, it will be generated via recaption.' properties: image_prompt: $ref: '#/components/schemas/Content' is_pano: default: false title: Is Pano type: boolean text_prompt: anyOf: - type: string - type: 'null' title: Text Prompt type: const: image default: image title: Type type: string required: - image_prompt title: Prompt type: object 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: '#/components/schemas/DataBase64Reference' media_asset: '#/components/schemas/MediaAssetReference' uri: '#/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 SphericallyLocatedContent-Output: description: Content with a preferred location on the sphere. properties: azimuth: anyOf: - type: number - type: 'null' title: Azimuth data_base64: anyOf: - type: string - type: 'null' title: Data Base64 extension: anyOf: - type: string - type: 'null' description: File extension without dot examples: - jpg - png - pdf - txt title: Extension uri: anyOf: - type: string - type: 'null' title: Uri title: SphericallyLocatedContent type: object SplatAssets: description: Gaussian splat asset URLs. properties: semantics_metadata: anyOf: - $ref: '#/components/schemas/WorldSemanticsMetadata' - type: 'null' description: Semantic metadata for the world spz_urls: anyOf: - additionalProperties: type: string type: object - type: 'null' description: URLs for SPZ format Gaussian splat files title: Spz Urls title: SplatAssets type: object UploadUrlInfo: description: Information required to upload raw bytes directly to storage. properties: curl_example: anyOf: - type: string - type: 'null' description: Optional curl example for convenience title: Curl Example required_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' description: Headers that MUST be included when uploading (e.g. Content-Type) title: Required Headers upload_method: description: Upload method title: Upload Method type: string upload_url: description: Signed URL for uploading bytes via PUT title: Upload Url type: string required: - upload_url - upload_method title: UploadUrlInfo 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 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 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: '#/components/schemas/DataBase64Reference' media_asset: '#/components/schemas/MediaAssetReference' uri: '#/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 VideoPrompt-Output: description: For world models supporting video (+ text) input. properties: text_prompt: anyOf: - type: string - type: 'null' title: Text Prompt type: const: video default: video title: Type type: string video_prompt: $ref: '#/components/schemas/Content' required: - video_prompt title: VideoPrompt type: object World: description: A generated world, including asset URLs. properties: assets: anyOf: - $ref: '#/components/schemas/WorldAssets' - type: 'null' description: Generated world assets created_at: anyOf: - format: date-time type: string - type: 'null' description: Creation timestamp title: Created At display_name: description: Display name title: Display Name type: string model: anyOf: - type: string - type: 'null' description: Model used for generation title: Model permission: anyOf: - $ref: '#/components/schemas/Permission' - type: 'null' description: Access control permissions for the world tags: anyOf: - items: type: string type: array - type: 'null' description: Tags associated with the world title: Tags updated_at: anyOf: - format: date-time type: string - type: 'null' description: Last update timestamp title: Updated At world_id: description: World identifier title: World Id type: string world_marble_url: description: World Marble URL title: World Marble Url type: string world_prompt: anyOf: - discriminator: mapping: depth-pano: '#/components/schemas/DepthPanoPrompt' image: '#/components/schemas/Prompt' inpaint-pano: '#/components/schemas/InpaintPanoPrompt' multi-image: '#/components/schemas/MultiImagePrompt-Output' text: '#/components/schemas/WorldTextPrompt-Output' video: '#/components/schemas/VideoPrompt-Output' propertyName: type oneOf: - $ref: '#/components/schemas/WorldTextPrompt-Output' - $ref: '#/components/schemas/Prompt' - $ref: '#/components/schemas/MultiImagePrompt-Output' - $ref: '#/components/schemas/VideoPrompt-Output' - $ref: '#/components/schemas/DepthPanoPrompt' - $ref: '#/components/schemas/InpaintPanoPrompt' - type: 'null' description: World prompt title: World Prompt required: - world_id - display_name - world_marble_url title: World type: object WorldAssets: description: Downloadable outputs of world generation. properties: caption: anyOf: - type: string - type: 'null' description: AI-generated description of the world title: Caption imagery: anyOf: - $ref: '#/components/schemas/ImageryAssets' - type: 'null' description: Imagery assets mesh: anyOf: - $ref: '#/components/schemas/MeshAssets' - type: 'null' description: Mesh assets splats: anyOf: - $ref: '#/components/schemas/SplatAssets' - type: 'null' description: Gaussian splat assets thumbnail_url: anyOf: - type: string - type: 'null' description: Thumbnail URL for the world title: Thumbnail Url title: WorldAssets type: object WorldSemanticsMetadata: description: "Semantic metadata describing how to interpret the generated splat\n\ asset in real-world units.\n\nThe exported asset is in arbitrary model units.\ \ Apply the transform\nbelow to convert to a metric, ground-aligned frame:\n\ \n metric_xyz = raw_xyz * metric_scale_factor\n aligned_xyz = metric_xyz\ \ - (0, ground_plane_offset, 0)\n\nBoth fields are populated on every world\ \ generated by the current\npipeline. They remain Optional only for backwards\ \ compatibility with\nworlds generated before December 2025, which predate\ \ metric-scale\nestimation.\n\nTODO: once pre-December-2025 worlds are migrated\ \ or aged out, tighten\nthese fields to non-Optional and drop the `| None`\ \ from the type." properties: ground_plane_offset: anyOf: - type: number - type: 'null' description: Vertical (Y-axis) offset, in meters, of the detected ground plane in the metric-scaled frame. Subtract from Y after applying `metric_scale_factor` to place the ground at y=0. title: Ground Plane Offset metric_scale_factor: anyOf: - type: number - type: 'null' description: Multiplicative factor that converts raw asset coordinates to meters. Multiply all XYZ positions (and isotropic scales) by this value. A value of 1.0 means scale could not be inferred and the asset was left in model units. title: Metric Scale Factor title: WorldSemanticsMetadata 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 WorldTextPrompt-Output: description: Input prompt class for text-conditioned world generation. properties: text_prompt: anyOf: - type: string - type: 'null' title: Text Prompt type: const: text default: text title: Type type: string title: WorldTextPrompt type: object 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.0 minimum: 0.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: '#/components/schemas/ImagePrompt' multi-image: '#/components/schemas/MultiImagePrompt-Input' text: '#/components/schemas/WorldTextPrompt-Input' video: '#/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 securitySchemes: ApiKeyAuth: description: API key for authentication. Get your key from the developer portal. in: header name: WLT-Api-Key type: apiKey info: description: Public-facing API for the Marble platform summary: Marble Public API v1 title: Marble Public API v1 version: 1.0.0 openapi: 3.1.0 paths: /marble/v1/credits: get: description: "Get remaining API credits for the authenticated user.\n\nReturns:\n\ \ CreditsResponse with the current aggregate API credit balance.\n\nRaises:\n\ \ HTTPException: 404 if the caller is not an API-enabled user\n HTTPException:\ \ 503 if the billing backend is unavailable" operationId: get_credits_marble_v1_credits_get responses: '200': content: application/json: schema: $ref: '#/components/schemas/CreditsResponse' description: Successful Response summary: Get Credits tags: - credits /marble/v1/media-assets/{media_asset_id}: get: description: "Get a media asset by ID.\n\nRetrieves metadata for a previously\ \ created media asset.\n\nArgs:\n media_asset_id: The media asset identifier.\n\ \nReturns:\n MediaAsset object with media_asset_id, file_name, extension,\ \ kind,\n metadata, created_at, and updated_at.\n\nRaises:\n HTTPException:\ \ 404 if not found" operationId: get_media_asset_marble_v1_media_assets__media_asset_id__get parameters: - in: path name: media_asset_id required: true schema: title: Media Asset Id type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/MediaAsset' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error summary: Get Media Asset /marble/v1/media-assets:prepare_upload: post: description: "Prepare a media asset upload for use in world generation.\n\n\ This API endpoint creates a media asset record and returns a signed upload\ \ URL.\nUse this workflow to upload images or videos that you want to reference\ \ in world\ngeneration requests.\n\n## Workflow\n\n1. **Prepare Upload** (this\ \ endpoint): Get a `media_asset_id` and `upload_url`\n2. **Upload File**:\ \ Use the signed URL to upload your file\n3. **Generate World**: Reference\ \ the `media_asset_id` in `/worlds:generate` with\n source type \"media_asset\"\ \n\n## Request Parameters\n\n- `file_name`: Your file's name (e.g., \"landscape.jpg\"\ )\n- `extension`: File extension without dot (e.g., \"jpg\", \"png\", \"mp4\"\ )\n- `kind`: Either \"image\" or \"video\"\n- `metadata`: Optional custom\ \ metadata object\n\n## Response\n\nReturns a `MediaAssetPrepareUploadResponse`\ \ containing:\n\n- `media_asset`: Object with `media_asset_id` (use this in\ \ world generation)\n- `upload_info`: Object with `upload_url`, `required_headers`,\ \ and `curl_example`\n\n## Uploading Your File\n\nUse the returned `upload_url`\ \ and `required_headers` to upload your file:\n\n```bash\ncurl --request PUT\ \ \\\n --url \\\n --header \"Content-Type: \"\ \ \\\n --header \": \" \\\n --upload-file /path/to/your/file\n\ ```\n\nReplace:\n- ``: The `upload_url` from the response\n- ``:\ \ MIME type (e.g., `image/png`, `image/jpeg`, `video/mp4`)\n- `:\ \ `: Each header from `required_headers`\n- `/path/to/your/file`:\ \ Path to your local file\n\n## Example Usage in World Generation\n\nAfter\ \ uploading, use the `media_asset_id` in a world generation request:\n\n```json\n\ {\n \"world_prompt\": {\n \"type\": \"image\",\n \"image_prompt\":\ \ {\n \"source\": \"media_asset\",\n \"media_asset_id\": \"\"\ \n }\n }\n}\n```" operationId: prepare_media_asset_upload_marble_v1_media_assets_prepare_upload_post requestBody: content: application/json: schema: $ref: '#/components/schemas/MediaAssetPrepareUploadRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/MediaAssetPrepareUploadResponse' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error summary: Prepare a media asset upload /marble/v1/operations/{operation_id}: get: description: "Get an operation by ID.\n\nPoll this endpoint to check the status\ \ of a long-running operation.\nWhen done=true, the response field contains\ \ the generated world.\n\nArgs:\n operation_id: The operation identifier\ \ from /worlds:generate.\n\nReturns:\n GetOperationResponse[World] with:\n\ \ - operation_id: Operation identifier\n - created_at: Creation\ \ timestamp\n - updated_at: Last update timestamp\n - expires_at:\ \ Expiration timestamp\n - done: true when complete, false while in\ \ progress\n - error: Error details if failed, null otherwise\n \ \ - metadata: Progress information and world_id\n - response: Generated\ \ World if done=true, null otherwise\n - cost: Settled credit cost\ \ breakdown; populated only when the\n operation completed successfully\ \ (done=true with no error)\n and a public price is known for its\ \ operation type. Failed\n or in-progress operations return null.\n\ \nRaises:\n HTTPException: 401 if unauthorized\n HTTPException: 404\ \ if operation not found\n HTTPException: 500 if request fails" operationId: get_operation_marble_v1_operations__operation_id__get parameters: - in: path name: operation_id required: true schema: title: Operation Id type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetOperationResponse_Union_World__PanoDepthToRgbResult__' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error summary: Get Operation /marble/v1/pano:depth_to_rgb: post: description: "Generate an RGB panorama from a depth panorama.\n\nProvide a depth\ \ panorama and a text prompt\ndescribing the desired appearance. The depth\ \ map\nsupplies the scene geometry; the model synthesizes\ntextures that match\ \ that geometry and returns a\npanoramic RGB image.\n\nAccepted depth inputs:\n\ \n* **EXR**: float depth values. Omit\n ``z_min`` and ``z_max``.\n* **PNG**:\ \ depth values normalized to [0, 1].\n Provide both ``z_min`` and ``z_max``\ \ so the\n service can decode the PNG correctly.\n\nFor a complete PNG-based\ \ workflow, see the\n[web-chisel-depth-png example](https://github.com/worldlabsai/worldlabs-api-examples/tree/main/web-chisel-depth-png).\n\ \nReturns a long-running ``Operation``. Poll\n``GET /operations/{operation_id}``\ \ until\n``done`` is ``true``, then read the generated\npanorama URL from\ \ ``response.pano_url``.\n\nRaises:\n HTTPException: 400 if invalid request\n\ \ HTTPException: 402 if insufficient credits\n HTTPException: 500 if\ \ generation could not start" operationId: pano_depth_to_rgb_marble_v1_pano_depth_to_rgb_post requestBody: content: application/json: schema: $ref: '#/components/schemas/PanoDepthToRgbRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Operation_PanoDepthToRgbResult_' 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 summary: Pano Depth To Rgb /marble/v1/worlds/{world_id}: delete: description: "Delete a world by ID.\n\nPermanently deletes a world and its associated\ \ assets.\nOnly the world owner can delete a world.\n\nArgs:\n world_id:\ \ The unique identifier of the world to delete.\n\nReturns:\n DeleteWorldResponse\ \ confirming the deletion.\n\nRaises:\n HTTPException: 403 if user is not\ \ the world owner\n HTTPException: 404 if world not found\n HTTPException:\ \ 500 if deletion fails" operationId: delete_world_marble_v1_worlds__world_id__delete parameters: - in: path name: world_id required: true schema: title: World Id type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/DeleteWorldResponse' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error summary: Delete World get: description: "Get a world by ID.\n\nRetrieves a world's details including generated\ \ assets if available.\nOnly the world owner or users with access to public\ \ worlds can retrieve them.\n\nArgs:\n world_id: The unique identifier\ \ of the world.\n\nReturns:\n World object with world_id, display_name,\ \ tags, assets, created_at,\n updated_at, permission, model, world_prompt,\ \ and world_marble_url.\n\nRaises:\n HTTPException: 404 if world not found\ \ or access denied" operationId: get_world_marble_v1_worlds__world_id__get parameters: - in: path name: world_id required: true schema: title: World Id type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/World' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error summary: Get World /marble/v1/worlds:generate: post: description: "Start world generation.\n\nCreates a new world generation job\ \ and returns a long-running operation.\nPoll the /operations/{operation_id}\ \ endpoint to check generation status\nand retrieve the generated world when\ \ complete.\n\nArgs:\n request: The world generation request containing\ \ world_prompt, display_name,\n tags, model, seed, and permission settings.\n\ \nReturns:\n GenerateWorldResponse with operation_id and timestamps. Use\ \ the operation_id\n to poll for completion.\n\nRaises:\n HTTPException:\ \ 400 if invalid request or content violates policies\n HTTPException:\ \ 402 if insufficient credits\n 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 summary: Generate World /marble/v1/worlds:list: post: description: "List worlds with optional filters.\n\nReturns worlds created through\ \ the API with optional filtering and pagination.\n\nArgs:\n request: List\ \ request with optional filters:\n - page_size: Number of results per\ \ page (default: 10)\n - page_token: Pagination token from previous\ \ response\n - status: Filter by status (e.g., \"COMPLETED\")\n \ \ - model: Filter by model name (e.g., \"marble-1.0-plus\")\n -\ \ tags: Filter by tags (matches worlds with any tag)\n - is_public:\ \ Filter by visibility (true=public, false=private, null=all)\n - created_after:\ \ Filter by creation time (after timestamp)\n - created_before: Filter\ \ by creation time (before timestamp)\n - sort_by: Sort order (\"created_at\"\ \ or \"updated_at\")\n\nReturns:\n ListWorldsResponse with worlds list\ \ and next_page_token for pagination.\n\nRaises:\n HTTPException: 400 if\ \ invalid parameters\n HTTPException: 500 if request fails" operationId: list_worlds_marble_v1_worlds_list_post requestBody: content: application/json: schema: $ref: '#/components/schemas/ListWorldsRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListWorldsResponse' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error summary: List Worlds security: - ApiKeyAuth: [] servers: - description: World API url: https://api.worldlabs.ai ````