Files
Upload inputs, import media from a link, and download results through short-lived signed URLs.
Jobs read their inputs from files and write their outputs to files. A file has an id, a type, a status, and, once it is ready, a signed download_url.
{
"id": "0193a5b3-1d0e-7a51-8c44-2f9b6e7d1a30",
"object": "file",
"kind": "audio",
"status": "ready",
"name": "interview.mp3",
"mime": "audio/mpeg",
"bytes": 482133,
"duration_ms": 14350,
"width": null,
"height": null,
"source": "upload",
"job_id": null,
"created_at": "2026-11-17T10:24:31.000Z",
"expires_at": null,
"download_url": "https://files.example.com/…",
"download_expires_at": "2026-11-17T10:39:31.000Z"
}Uploading a file
Uploads take three requests: register the file, send the bytes, then confirm.
Register the upload
Tell Voiser the type and exact size of the file. POST/v2/files returns the file (status pending) and an upload object.
curl -X POST https://api.34.181.188.80.sslip.io/v2/files \
-H "Authorization: Bearer $VOISER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "interview.mp3", "mime": "audio/mpeg", "bytes": 482133, "purpose": "input" }'{
"file": { "id": "0193a5b3-1d0e-7a51-8c44-2f9b6e7d1a30", "object": "file", "status": "pending", "…": "…" },
"upload": {
"url": "https://files.example.com/upload/…",
"method": "PUT",
"headers": { "Content-Type": "audio/mpeg" },
"resumable": false,
"chunk_bytes": null,
"expires_at": "2026-11-17T11:24:31.000Z"
}
}purpose tells Voiser how the file will be used: input (default; media to process), reference, first_frame, last_frame (images for video), or document (DOCX, PDF, EPUB, TXT for text to speech projects).
Send the bytes
PUT the raw file to upload.url with exactly the headers in upload.headers. Do not send your API key to this URL.
curl -X PUT "<upload.url>" \
-H "Content-Type: audio/mpeg" \
--data-binary @interview.mp3For large files, upload.resumable is true: send the file in chunks of upload.chunk_bytes with a Content-Range header on each request, so an interrupted upload can continue where it stopped. Finish before upload.expires_at.
Complete the upload
POST/v2/files/{file_id}/complete checks the bytes (type, size, duration). The file becomes ready, or rejected with a reason.
curl -X POST https://api.34.181.188.80.sslip.io/v2/files/0193a5b3-1d0e-7a51-8c44-2f9b6e7d1a30/complete \
-H "Authorization: Bearer $VOISER_API_KEY"Now pass the file id to any endpoint that takes a file_id.
Importing from a link
If the media is already online, let Voiser fetch it. POST/v2/files/import accepts a direct file link or a page from a supported video platform or social network. The import is free and runs as a job; its result contains the new file_id.
curl -X POST https://api.34.181.188.80.sslip.io/v2/files/import \
-H "Authorization: Bearer $VOISER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/media/interview.mp4", "name": "Interview" }'The link must be publicly reachable; private network addresses are refused (job_url_not_allowed), and unreadable links fail the job with job_url_unreachable.
Downloading results
Jobs list their outputs in files (and usually in result.file_id). GET/v2/files/{file_id} returns the file with a fresh download_url:
- The URL is signed and valid for 15 minutes (
download_expires_at). Anyone with the URL can download the file during that time, so do not log or share it. - There are no permanent URLs. Store the file id, not the URL, and request the file again whenever you need a new link.
- Download the bytes and store them yourself if you need them long-term. Files with an
expires_atare deleted after that time.
The legacy v1 API returns file URLs that stay valid for 7 days. v2 always uses short-lived URLs.
File errors
| Code | Status | Meaning |
|---|---|---|
asset_not_found | 404 | No file with this id in your account. |
asset_too_large | 413 | The file exceeds the size limit. |
asset_too_long | 400 | The media is longer than allowed for this use. |
asset_type_not_allowed | 415 | This file type is not accepted. |
asset_type_mismatch | 415 | The bytes do not match the declared mime. |
asset_upload_incomplete | 409 | complete was called before all bytes arrived. |
asset_upload_expired | 410 | The upload URL expired; register the file again. |
asset_not_ready | 409 | The file is still pending or was rejected. |
asset_corrupt | 422 | The file is damaged or cannot be read. |
asset_no_audio_track | 422 | The video has no audio. |