Media assets - World Labs

Media asset endpoints let you upload images or videos to managed storage before using them as world-generation inputs.

Prepare media asset upload

POST /marble/v1/media-assets:prepare_uploadCreate a media asset record and receive the signed upload URL and required headers.

Get media asset

GET /marble/v1/media-assets/{media_asset_id}Retrieve metadata for an uploaded media asset.

Upload flow

1

Prepare the upload

Call Prepare media asset upload with the file name, extension, and media kind.

2

Upload bytes

Send the file to the returned signed URL with the required headers from the response.

3

Reference the asset

Use the returned media_asset_id in Generate a world.

Prepare media asset uploadPrepare a media asset upload for use in world generation. This API endpoint creates a media asset record and returns a signed upload URL. Use this workflow to upload images or videos that you want to reference in world generation requests. ## Workflow 1. **Prepare Upload** (this endpoint): Get a `media_asset_id` and `upload_url` 2. **Upload File**: Use the signed URL to upload your file 3. **Generate World**: Reference the `media_asset_id` in `/worlds:generate` with source type "media_asset" ## Request Parameters - `file_name`: Your file's name (e.g., "landscape.jpg") - `extension`: File extension without dot (e.g., "jpg", "png", "mp4") - `kind`: Either "image" or "video" - `metadata`: Optional custom metadata object ## Response Returns a `MediaAssetPrepareUploadResponse` containing: - `media_asset`: Object with `media_asset_id` (use this in world generation) - `upload_info`: Object with `upload_url`, `required_headers`, and `curl_example` ## Uploading Your File Use the returned `upload_url` and `required_headers` to upload your file: ```bash curl --request PUT \ --url <upload_url> \ --header "Content-Type: <content-type>" \ --header "<header-name>: <header-value>" \ --upload-file /path/to/your/file ``` Replace: - `<upload_url>`: The `upload_url` from the response - `<content-type>`: MIME type (e.g., `image/png`, `image/jpeg`, `video/mp4`) - `<header-name>: <header-value>`: Each header from `required_headers` - `/path/to/your/file`: Path to your local file ## Example Usage in World Generation After uploading, use the `media_asset_id` in a world generation request: ```json { "world_prompt": { "type": "image", "image_prompt": { "source": "media_asset", "media_asset_id": "<your-media-asset-id>" } } } ```

⌘I