World Labs Pano Video

Equirectangular Format

┌─────────────────────────────────────────────┐
│                                             │
│  ← 360° horizontal field of view →          │
│                                             │
│  ← Left        Center        Right →        │
│                                             │
│  ↑ 180° vertical (zenith to nadir)          │
│                                             │
└─────────────────────────────────────────────┘
         Aspect ratio: 2:1

Creating Panoramas

From Phone:

• iPhone: Panorama mode (stitch 360° or use apps like Street View)
• Android: Photo Sphere, Google Camera

From Camera:

• Shoot overlapping photos, stitch with PTGui, Hugin, or Lightroom

From 360° Camera:

• Insta360, GoPro Max, Ricoh Theta

API Usage (Panorama)

Panoramas use the image type with the 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,
    "text_prompt": "Add dramatic sunset lighting"
  }
}

Using Public URL (Panorama)

{
  "model": "Marble 0.1-plus",
  "world_prompt": {
    "type": "image",
    "image_prompt": {
      "source": "uri",
      "uri": "https://example.com/360-panorama.jpg"
    },
    "is_pano": true,
    "text_prompt": "Transform into a mystical forest"
  }
}

Best Practices for Panoramas

✅ Level horizon: Keep camera level during capture ✅ Consistent exposure: Use manual settings or HDR ✅ No moving objects: Static scenes work best ✅ Clean nadir: Bottom of image should be clean ✅ Full 360°: Complete coverage essential ✅ Exact 2:1 aspect ratio: Required for recognition

❌ Tripod visible: Remove or patch the tripod ❌ People in frame: Causes artifacts ❌ Heavy stitching seams: Fix edges before uploading ❌ Phone panoramas: Often lack full 180° vertical coverage

Video Input

Requirements

Recording Guidelines

Camera Movement:

         Start
           ↓
    ┌──────○──────┐
    │      │      │
    │   Rotate    │
    │   180-360°  │
    │      │      │
    └──────○──────┘
           ↓
          End

DO:

• Rotate camera smoothly in one direction
• Keep camera height constant
• Use gimbal or tripod for stability
• Maintain consistent speed
• Cover at least 180° of the space

DON'T:

• Pan back and forth
• Change height during recording
• Zoom in/out
• Record moving objects
• Exceed 30 seconds

API Usage (Video)

{
  "model": "Marble 0.1-plus",
  "world_prompt": {
    "type": "video",
    "video_prompt": {
      "source": "media_asset",
      "media_asset_id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "text_prompt": "Transform into a mystical nighttime scene"
  }
}

Using Public URL (Video)

{
  "model": "Marble 0.1-plus",
  "world_prompt": {
    "type": "video",
    "video_prompt": {
      "source": "uri",
      "uri": "https://example.com/room-rotation.mp4"
    },
    "text_prompt": "A scenic mountain landscape"
  }
}

Python Example

import requests

def generate_from_pano_or_video(
    api_key: str,
    file_path: str,
    input_type: str,  # "panorama" or "video"
    prompt: str = None
):
    base_url = "https://api.worldlabs.ai/marble/v1"
    headers = {"WLT-Api-Key": api_key, "Content-Type": "application/json"}

    # Determine kind and extension
    ext = file_path.lower().split('.')[-1]
    if ext == "jpeg":
        ext = "jpg"

    # Set kind based on input type
    kind = "video" if input_type == "video" else "image"

    # Prepare upload
    prep = requests.post(
        f"{base_url}/media-assets:prepare_upload",
        headers=headers,
        json={"file_name": file_path.split('/')[-1], "kind": kind, "extension": ext}
    ).json()

    media_asset_id = prep["media_asset"]["media_asset_id"]
    upload_url = prep["upload_info"]["upload_url"]

    # Determine content type for upload
    content_types = {
        "jpg": "image/jpeg", "jpeg": "image/jpeg", "png": "image/png", "webp": "image/webp",
        "mp4": "video/mp4", "mov": "video/quicktime", "webm": "video/webm"
    }
    content_type = content_types.get(ext, "application/octet-stream")

    # Upload file
    with open(file_path, 'rb') as f:
        requests.put(upload_url, headers={"Content-Type": content_type}, data=f.read())

    # Build world_prompt based on type
    if input_type == "video":
        world_prompt = {
            "type": "video",
            "video_prompt": {
                "source": "media_asset",
                "media_asset_id": media_asset_id
            }
        }
    else:  # panorama
        world_prompt = {
            "type": "image",
            "image_prompt": {
                "source": "media_asset",
                "media_asset_id": media_asset_id
            },
            "is_pano": True
        }

    if prompt:
        world_prompt["text_prompt"] = prompt

    # Generate
    response = requests.post(
        f"{base_url}/worlds:generate",
        headers=headers,
        json={"model": "Marble 0.1-plus", "world_prompt": world_prompt}
    )

    return response.json()["operation_id"]

# Panorama example
pano_op = generate_from_pano_or_video(
    "your_api_key",
    "360_office.jpg",
    "panorama",
    "Add warm afternoon sunlight"
)

# Video example
video_op = generate_from_pano_or_video(
    "your_api_key",
    "room_rotation.mp4",
    "video",
    "Make it look abandoned and overgrown"
)

Comparison: Panorama vs Video vs Images

Troubleshooting

Panorama Issues

Video Issues

Related Skills

• world-labs-api - API integration details
• world-labs-image-prompt - Single image input
• world-labs-multi-image - Multi-image with direction control
• world-labs-studio - Compose and animate generated worlds