Menu
World Labs Marble API integration - authentication, endpoints, models, and media uploads
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/CloudAI-X/world-labs-skills --skill world-labs-apiThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
Based on SOC occupation classification
| name | world-labs-api |
| description | World Labs Marble API integration - authentication, endpoints, models, and media uploads |
| allowed-tools | ["Bash","WebFetch"] |
All API requests require the WLT-Api-Key header:
curl -X POST "https://api.worldlabs.ai/marble/v1/worlds:generate" \
-H "WLT-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
Get your API key from: https://platform.worldlabs.ai
Note: API credits purchased at platform.worldlabs.ai are separate from Marble app (marble.worldlabs.ai) credits.
https://api.worldlabs.ai/marble/v1
| Model | ID | Best For |
|---|---|---|
| Marble 0.1-plus | Marble 0.1-plus | High-quality production (~5 min) |
| Marble 0.1-mini | Marble 0.1-mini | Quick drafts/iteration (~30-45 sec) |
| Input Type | Marble 0.1-plus | Marble 0.1-mini |
|---|---|---|
| Panorama image | 1,500 | 150 |
| Text | 1,580 | 230 |
| Image (non-pano) | 1,580 | 230 |
| Multi-image | 1,600 | 250 |
| Video | 1,600 | 250 |
Pricing: $1 = 1,250 credits (minimum purchase: $5 / 6,250 credits)
POST /marble/v1/worlds:generate
Request Body (Text Prompt):
{
"display_name": "My World",
"model": "Marble 0.1-plus",
"world_prompt": {
"type": "text",
"text_prompt": "A cozy cabin in snowy mountains at sunset",
"disable_recaption": false
},
"seed": 42,
"tags": ["landscape", "winter"],
"permission": {
"public": false
}
}
Response:
{
"done": false,
"operation_id": "op_abc123",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z",
"metadata": {}
}
GET /marble/v1/operations/{operation_id}
Response (in progress):
{
"done": false,
"operation_id": "op_abc123",
"metadata": {
"world_id": "world_xyz789"
}
}
Response (complete):
{
"done": true,
"operation_id": "op_abc123",
"response": {
"world_id": "world_xyz789",
"display_name": "My World",
"world_marble_url": "https://marble.worldlabs.ai/world/...",
"assets": {
"thumbnail_url": "...",
"imagery": { "pano_url": "..." },
"mesh": { "collider_mesh_url": "..." },
"splats": { "spz_urls": {} }
}
}
}
GET /marble/v1/worlds/{world_id}
Returns full world object with assets.
POST /marble/v1/worlds:list
{
"page_size": 20,
"status": "SUCCEEDED",
"model": "Marble 0.1-plus",
"sort_by": "created_at"
}
POST /marble/v1/media-assets:prepare_upload
{
"file_name": "landscape.jpg",
"kind": "image",
"extension": "jpg"
}
Response:
{
"media_asset": {
"media_asset_id": "550e8400-e29b-41d4-a716-446655440000",
"file_name": "landscape.jpg",
"kind": "image",
"extension": "jpg"
},
"upload_info": {
"upload_url": "https://storage.googleapis.com/...",
"upload_method": "PUT",
"required_headers": {
"x-goog-content-length-range": "0,1048576000"
}
}
}
curl -X PUT "UPLOAD_URL" \
-H "Content-Type: image/jpeg" \
-H "x-goog-content-length-range: 0,1048576000" \
--data-binary @landscape.jpg
Single Image:
{
"model": "Marble 0.1-plus",
"world_prompt": {
"type": "image",
"image_prompt": {
"source": "media_asset",
"media_asset_id": "550e8400-e29b-41d4-a716-446655440000"
},
"text_prompt": "Enhance with dramatic lighting"
}
}
Panorama Image (use is_pano flag):
{
"model": "Marble 0.1-plus",
"world_prompt": {
"type": "image",
"image_prompt": {
"source": "media_asset",
"media_asset_id": "550e8400-e29b-41d4-a716-446655440000",
"is_pano": true
}
}
}
Multi-Image with Azimuth:
{
"model": "Marble 0.1-plus",
"world_prompt": {
"type": "multi-image",
"multi_image_prompt": [
{
"azimuth": 0,
"content": {
"source": "media_asset",
"media_asset_id": "front_image_id"
}
},
{
"azimuth": 180,
"content": {
"source": "media_asset",
"media_asset_id": "back_image_id"
}
}
],
"text_prompt": "A cozy living room"
}
}
Video:
{
"model": "Marble 0.1-plus",
"world_prompt": {
"type": "video",
"video_prompt": {
"source": "media_asset",
"media_asset_id": "video_asset_id"
},
"text_prompt": "A scenic mountain landscape"
}
}
| Type | Formats | Max Size | Notes |
|---|---|---|---|
| Image | png, jpg, jpeg, webp | 20 MB | 1024px on long side recommended |
| Panorama | png, jpg, jpeg, webp | 20 MB | 2:1 aspect, 2560px wide recommended |
| Video | mp4, mov, webm | 100 MB | Max 30 seconds |
import requests
import time
API_KEY = "your_api_key"
BASE_URL = "https://api.worldlabs.ai/marble/v1"
def generate_world(prompt: str, model: str = "Marble 0.1-plus") -> dict:
"""Generate a world and return the world data."""
headers = {"WLT-Api-Key": API_KEY, "Content-Type": "application/json"}
# Start generation
response = requests.post(
f"{BASE_URL}/worlds:generate",
headers=headers,
json={
"model": model,
"world_prompt": {
"type": "text",
"text_prompt": prompt
}
}
)
response.raise_for_status()
operation_id = response.json()["operation_id"]
# Poll until complete
while True:
status_response = requests.get(
f"{BASE_URL}/operations/{operation_id}",
headers={"WLT-Api-Key": API_KEY}
)
status_response.raise_for_status()
result = status_response.json()
if result.get("done"):
if "error" in result and result["error"]:
raise Exception(f"Generation failed: {result['error']}")
return result["response"]
time.sleep(5)
# Usage
world = generate_world("A mystical forest with glowing mushrooms")
print(f"World created: {world['world_id']}")
print(f"View at: {world['world_marble_url']}")
| Status Code | Meaning |
|---|---|
| 400 | Invalid request parameters |
| 401 | Invalid or missing API key |
| 402 | Insufficient credits |
| 429 | Rate limit exceeded |
| 500 | Server error |
world-labs-text-prompt - Text prompting best practicesworld-labs-image-prompt - Single image inputworld-labs-multi-image - Multi-image direction controlworld-labs-pano-video - Panorama and video inputworld-labs-export - Export formats and integrationsChisel 3D blocking tool for world generation - geometry, walls, and reference models
World Labs export formats - Gaussian splats, meshes, images, and engine integrations
Single image input for world generation - requirements, best practices, and examples