Skip to main content
Some agent nodes accept images, audio, or videos as parameters. Use these endpoints to upload files and get UUIDs that you can pass to update_params when running agents.

​
Flow

POST /uploads/{type}/get_upload_url  →  POST file to upload_url  →  POST /uploads/{type}/finalize_upload
  1. Call get_upload_url to get a signed URL and the asset UUID
  2. POST your file to that URL (include upload_fields as form data)
  3. Call finalize_upload to confirm the upload
Use the returned UUID in update_params: 
{
  "update_params": {
    "NODE_ID": {
      "audio_id": "your-uploaded-uuid"
    }
  }
}

​
Full Example

Upload audio and use it in update_params: 
import requests

API_KEY = "mk_your_api_key"
BASE = "https://api.mosaic.so"

# 1. Get upload URL
data = requests.post(f"{BASE}/uploads/audio/get_upload_url",
    headers={"Authorization": f"Bearer {API_KEY}"}).json()

# 2. Upload file
with open("music.mp3", "rb") as f:
    requests.post(data["upload_url"], data=data["upload_fields"], files={"file": f})

# 3. Finalize
result = requests.post(f"{BASE}/uploads/audio/finalize_upload",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"audio_id": data["audio_id"]}).json()

# 4. Use in update_params
run = requests.post(f"{BASE}/agent/YOUR_AGENT_ID/run",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={
        "video_urls": ["https://youtube.com/watch?v=dQw4w9WgXcQ"],
        "update_params": {
            "AUDIO_NODE_ID": {"audio_id": result["audio_id"]}
        }
    }).json()

print(f"Run ID: {run['run_id']}")

​
Supported Formats

TypeFormatsMax SizeMax Duration
VideoMP4, MOV, AVI, WebM, MKV, M4V5 GB1 hour
AudioMP3, WAV, M4A, FLAC, OGG, AAC, Opus100 MB1 hour
ImagePNG, JPEG, GIF, WebP, SVG50 MB-

​
Errors

ErrorCause
404Upload ID not found or expired
400File not uploaded before finalize
413File exceeds size limit