World Labs Panorama & Video Input Skill

World Labs Panorama & Video Input

Panoramas and videos provide the most control over world layout by capturing complete scene coverage.

Quick Reference

Credits

| Input Type | Marble 0.1-plus | Marble 0.1-mini | | ---------- | --------------- | --------------- | | Panorama | 1,500 | 150 | | Video | 1,600 | 250 |

Panoramas skip the pano generation step, saving 80 credits compared to regular images.

Panorama Input

Requirements

| Requirement | Specification | | ------------ | ------------------------------- | | Format | 360° equirectangular projection | | Aspect ratio | 2:1 (width:height) exactly | | Recommended | 2560 pixels wide | | File size | Max 20 MB | | Formats | PNG (recommended), JPG, WebP |

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

| Requirement | Specification | | ------------ | -------------------------------- | | File size | Max 100 MB | | Duration | Max 30 seconds | | Rotation | Camera should cover 180-360° | | Focal length | Fixed (no zoom during recording) | | Exposure | Fixed (manual mode) | | Movement | Slow, smooth rotation | | Formats | mp4, mov, webm |

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

| Feature | Panorama | Video | Multi-Image | | ---------------- | ------------------------ | ------------ | --------------- | | Layout control | ★★★★★ | ★★★★☆ | ★★★☆☆ | | Ease of capture | ★★★☆☆ | ★★★★☆ | ★★★★★ | | Coverage | Full 360° | 180-360° | Selected angles | | Equipment needed | 360° camera or stitching | Phone/camera | Any camera | | Best for | Complete environments | Room capture | Specific views | | Credits (plus) | 1,500 | 1,600 | 1,600 | | Credits (mini) | 150 | 250 | 250 |

Troubleshooting

Panorama Issues

| Problem | Solution | | -------------------------- | -------------------------------------- | | Not recognized as panorama | Verify exactly 2:1 aspect ratio | | Warped horizon | Re-level panorama in editing software | | Stitching seams | Use better overlap or manual alignment | | Tripod in nadir | Clone-stamp or use nadir patch | | Overexposed sky | Use HDR or graduated filters |

Video Issues

| Problem | Solution | | --------------------- | -------------------------------- | | Shaky footage | Use gimbal or stabilize in post | | Inconsistent exposure | Lock exposure in manual mode | | Too fast rotation | Slow down, stay under 30 seconds | | Insufficient coverage | Ensure at least 180° rotation |

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

Agent Skills: World Labs Panorama & Video Input

Install this agent skill to your local

Skill Files