---
title: "Prepare a media asset upload"
method: POST
path: "/marble/v1/media-assets:prepare_upload"
---

# Prepare a media asset upload

`POST /marble/v1/media-assets:prepare_upload`

## Request

- Base URL: `https://api.worldlabs.ai`
- URL: `https://api.worldlabs.ai/marble/v1/media-assets:prepare_upload`
- Auth: API key in header `WLT-Api-Key`
- TypeScript: <https://skmtc.dev/worldlabs/apis/marble-public-api-v1/docs/marble/v1/media-assets:prepare_upload/post.ts> (a function with typed inputs; its response is checked against the schema)

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:

```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>"
    }
  }
}
```

## Request body

- MediaAssetPrepareUploadRequest: Request to prepare a media asset upload.
  - `extension` string, nullable: File extension without dot
  - `file_name` string, required: File name
  - `kind` 'image' | 'video', required: High-level media asset type.
  - `metadata` object, nullable: Optional application-specific metadata

## Response `200`

Successful Response

- MediaAssetPrepareUploadResponse: Response from preparing a media asset upload.
  - `media_asset` MediaAsset, required: A user-uploaded media asset stored in managed storage. MediaAssets can be images, videos, or binary blobs that are used as input to world generation.
    - `created_at` string, date-time, required: Creation timestamp
    - `extension` string, nullable: File extension without dot
    - `file_name` string, required: File name
    - `kind` 'image' | 'video', required: High-level media asset type.
    - `media_asset_id` string, required: Server-generated media asset identifier
    - `metadata` object, nullable: Optional application-specific metadata
    - `updated_at` string, date-time, nullable: Last update timestamp
  - `upload_info` UploadUrlInfo, required: Information required to upload raw bytes directly to storage.
    - `curl_example` string, nullable: Optional curl example for convenience
    - `required_headers` object, nullable: Headers that MUST be included when uploading (e.g. Content-Type)
    - `upload_method` string, required: Upload method
    - `upload_url` string, required: Signed URL for uploading bytes via PUT

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-03** `4a3ed614672e`: 1 breaking, 3 info
  - added required request body
  - api operation id `prepare_media_asset_upload_marble_v1_media_assets_prepare_upload_post` was added
  - added the non-success response with the status `422`
  - added the success response with the status `200`

[Operation history](https://skmtc.dev/worldlabs/apis/marble-public-api-v1/changes/marble/v1/media-assets:prepare_upload/post.md)

---

[API](https://skmtc.dev/worldlabs/apis/marble-public-api-v1.md) - [All operations](https://skmtc.dev/worldlabs/apis/marble-public-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/worldlabs/apis/marble-public-api-v1/revisions/4a3ed614672e?raw)