Prepare media asset upload

Prepare 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:

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:

{
  "world_prompt": {
    "type": "image",
    "image_prompt": {
      "source": "media_asset",
      "media_asset_id": "<your-media-asset-id>"
    }
  }
}