Documentation Index
Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt
Use this file to discover all available pages before exploring further.
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
- Call
get_upload_url to get a signed URL and the asset UUID
- POST your file to that URL (include
upload_fields as form data)
- 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']}")
| Type | Formats | Max Size | Max Duration |
|---|
| Video | MP4, MOV, AVI, WebM, MKV, M4V | 5 GB | Plan-based: 2 hours on Standard, 5 hours on Professional/Enterprise |
| Audio | MP3, WAV, M4A, FLAC, OGG, AAC, Opus | 500 MB | 5 hours |
| Image | PNG, JPEG, GIF, WebP, SVG | 50 MB | - |
Errors
| Error | Cause |
|---|
| 404 | Upload ID not found or expired |
| 400 | File not uploaded before finalize |
| 413 | File exceeds size limit |
