Upload a single image or video that can be referenced from a later search. Processing is asynchronous; the response is 202 and the asset's lifecycle (pending → processing → processed, or a terminal failure) is then driven by Soundstripe.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Upload a single image or video as a multipart request. The endpoint returns an asset ID that you can reference from a search request to ground results in the visuals you are actually scoring against.
The asset is processed asynchronously: the response is 202 Accepted and the asset's lifecycle (pending → processing → processed, or a terminal failure) is then driven by Soundstripe. A search may reference an asset before its processing finishes; the search waits internally and is delivered via webhook once the asset is ready.
Image and video search are enabled per account. Contact your account manager if you need access.
Request
POST /v1/supe/assets
Authorization: Token YOUR_API_KEY
Content-Type: multipart/form-dataForm fields
| Field | Type | Required | Description |
|---|---|---|---|
| file | binary | Yes | The image or video bytes. |
| content_type | string | No | Overrides the multipart-declared MIME type. Defaults to the part's declared content type. |
Supported formats
- Images:
image/jpeg,image/png,image/webp - Videos:
video/mp4,video/quicktime,video/webm
Per-asset limits
- Image: up to 20 MB and 4,096 pixels on each axis.
- Video: up to 500 MB and 10 minutes.
Example request
curl -X POST https://api.soundstripe.com/v1/supe/assets \
-H "Authorization: Token YOUR_API_KEY" \
-F "[email protected];type=image/jpeg"Response
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "supe_assets",
"attributes": {
"status": "pending",
"media_kind": "image",
"submitted_at": "2026-05-04T00:00:00Z",
"original_retained": true
},
"links": {
"self": "https://api.soundstripe.com/v1/supe/assets/550e8400-e29b-41d4-a716-446655440000"
}
},
"links": {
"self": "https://api.soundstripe.com/v1/supe/assets"
}
}The returned data.id is the value you pass in data.attributes.asset_ids when creating a search.
Quotas and pricing
- Image upload quota: 17,000 per API key per rolling 24 hours.
- Video upload quota: 200 per API key per rolling 24 hours.
- A search that references any video asset is billed at the video tier. Mixed image + video searches require both image and video access on your account.
Error responses
| HTTP | Code | Meaning |
|---|---|---|
| 400 | bad_request | The file parameter is missing. |
| 422 | empty_file | The uploaded file is zero bytes. |
| 422 | unsupported_format | The MIME type is outside the supported list, or the asset's dimensions or duration could not be probed. |
| 422 | image_size_exceeded | Image larger than 20 MB. meta.limit_bytes carries the limit. |
| 422 | image_dimensions_exceeded | Image wider or taller than 4,096 pixels. meta.limit_width, meta.limit_height, meta.actual_width, and meta.actual_height carry the values. |
| 422 | video_size_exceeded | Video larger than 500 MB. meta.limit_bytes carries the limit. |
| 422 | video_duration_exceeded | Video longer than 10 minutes. meta.limit_seconds carries the limit. |
| 403 | unauthorized | API key does not have access to upload assets of this type. |
| 429 | daily_image_quota_exceeded | Daily image upload quota reached. meta.limit carries the cap. |
| 429 | daily_video_quota_exceeded | Daily video upload quota reached. meta.limit carries the cap. |