How to Upload Files (API)
Upload images, videos, and audio files to WaveSpeedAI for use in generation tasks. Returns a URL that can be passed to models accepting media inputs.
Endpoint
POST https://api.wavespeed.ai/api/v3/media/upload/binaryRequest
curl --location --request POST 'https://api.wavespeed.ai/api/v3/media/upload/binary' \
--header 'Authorization: Bearer ${WAVESPEED_API_KEY}' \
--form 'file=@"/path/to/your/image.png"'Supported Formats
| Type | Formats |
|---|---|
| Images | JPG, JPEG, PNG, WebP, GIF, BMP, TIFF |
| Videos | MP4, AVI, MOV, WMV, FLV, WebM, MKV, 3GP, OGV |
| Audio | MP3, WAV, OGG, AAC, FLAC, WebM, M4A, Opus |
Note: For files larger than 300MB, we recommend using a URL input instead of uploading directly.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
file | file | Yes | Binary file to upload (image, video, or audio) |
Response
{
"code": 200,
"message": "success",
"data": {
"type": "image",
"download_url": "https://...",
"filename": "image.png",
"size": 1024000
}
}Response Fields
| Field | Type | Description |
|---|---|---|
code | integer | HTTP status code (200 for success) |
message | string | Status message |
data.type | string | File type (image, video, or audio) |
data.download_url | string | URL to use in generation requests |
data.filename | string | Original filename |
data.size | number | File size in bytes |
Python Example
import os
import requests
api_key = os.environ.get("WAVESPEED_API_KEY")
def upload_file(file_path):
with open(file_path, 'rb') as f:
response = requests.post(
"https://api.wavespeed.ai/api/v3/media/upload/binary",
headers={"Authorization": f"Bearer {api_key}"},
files={"file": f}
)
return response.json()["data"]
# Upload an image
result = upload_file("/path/to/image.png")
print(f"Type: {result['type']}")
print(f"URL: {result['download_url']}")
print(f"Size: {result['size']} bytes")
# Use the URL in a model request
image_url = result['download_url']JavaScript Example
async function uploadFile(file) {
const apiKey = process.env.WAVESPEED_API_KEY;
const formData = new FormData();
formData.append('file', file);
const response = await fetch('https://api.wavespeed.ai/api/v3/media/upload/binary', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`
},
body: formData
});
const data = await response.json();
return data.data;
}Error Responses
| Code | Description |
|---|---|
| 400 | Invalid file or format not supported |
| 401 | Invalid API key |
| 413 | File too large |
Retention
Uploaded files are stored for 7 days and then automatically deleted.
Related Pages
- How to Upload Files — General guide
- How to Submit Task