world-labs-pano-video（世界实验室全景视频）

World Labs Panorama & Video Input

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

Quick Reference

Credits

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

Panorama Input

Requirements

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