Upload a file for workflow inputs | BeatAPI API Documentation

Use file upload when your images, videos, audio, or subtitle files are not already hosted at public HTTPS URLs. The returned HTTPS URL can be used directly in images, reference_videos, audio_url, or srt_url.

Limits:

Images, audio, and subtitles: maximum 50 MB.
Motion videos: maximum 100 MB.
Images: png, jpg, jpeg, webp (image/png, image/jpeg, image/webp).
Audio: mp3, wav, aac, m4a (audio/mpeg, audio/wav, audio/aac, audio/mp4).
Audio uploads must be 10-300 seconds. The selected Music Video tier applies its own task limit: Standard 10-180 seconds; Premium 10-300 seconds.
Motion videos: mp4, mov (video/mp4, video/quicktime), 3-30 seconds. Duration and dimensions are detected during upload.
Subtitles: srt (application/x-subrip; multipart uploads may use text/plain only when the filename ends in .srt).
PDF, generic text files, octet-stream uploads, Matroska videos, and zip files are not supported for launch.
Send either multipart form-data with a file field, or send the raw file body with the asset Content-Type.
Content-Length is required and is validated before BeatAPI buffers the request body; chunked uploads without a declared length are rejected.
Returned URLs are HTTPS and long-lived for launch.
Uploaded audio files are duration-checked during upload. The response includes audio_duration_seconds when the uploaded asset is audio.
Uploaded videos are signature-, duration-, and dimension-checked. The response includes video_duration_seconds, width, and height.
Workflow task inputs still require public HTTPS URLs. Localhost, private network URLs, and data URLs are not accepted.

Use file upload when your images, videos, audio, or subtitle files are not already hosted at public HTTPS URLs. The returned HTTPS URL can be used directly in `images`, `reference_videos`, `audio_url`, or `srt_url`. Limits: - Images, audio, and subtitles: maximum 50 MB. - Motion videos: maximum 100 MB. - Images: `png`, `jpg`, `jpeg`, `webp` (`image/png`, `image/jpeg`, `image/webp`). - Audio: `mp3`, `wav`, `aac`, `m4a` (`audio/mpeg`, `audio/wav`, `audio/aac`, `audio/mp4`). - Audio uploads must be 10-300 seconds. The selected Music Video tier applies its own task limit: Standard 10-180 seconds; Premium 10-300 seconds. - Motion videos: `mp4`, `mov` (`video/mp4`, `video/quicktime`), 3-30 seconds. Duration and dimensions are detected during upload. - Subtitles: `srt` (`application/x-subrip`; multipart uploads may use `text/plain` only when the filename ends in `.srt`). - PDF, generic text files, octet-stream uploads, Matroska videos, and zip files are not supported for launch. - Send either multipart form-data with a `file` field, or send the raw file body with the asset `Content-Type`. - `Content-Length` is required and is validated before BeatAPI buffers the request body; chunked uploads without a declared length are rejected. - Returned URLs are HTTPS and long-lived for launch. - Uploaded audio files are duration-checked during upload. The response includes `audio_duration_seconds` when the uploaded asset is audio. - Uploaded videos are signature-, duration-, and dimension-checked. The response includes `video_duration_seconds`, `width`, and `height`. - Workflow task inputs still require public HTTPS URLs. Localhost, private network URLs, and data URLs are not accepted.

Authentication

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

Request

This endpoint expects a multipart form containing a file.

filefileRequired

purposeenumOptional

Allowed values:

Response

File uploaded

dataobject

Uploaded file metadata and the public HTTPS URL to use in later requests.

Errors

400

Bad Request Error

401

Unauthorized Error

429

Too Many Requests Error

500

Internal Server Error

Limits:

Images, audio, and subtitles: maximum 50 MB.
Motion videos: maximum 100 MB.
Images: png, jpg, jpeg, webp (image/png, image/jpeg, image/webp).
Audio: mp3, wav, aac, m4a (audio/mpeg, audio/wav, audio/aac, audio/mp4).
Audio uploads must be 10-300 seconds. The selected Music Video tier applies its own task limit: Standard 10-180 seconds; Premium 10-300 seconds.
Motion videos: mp4, mov (video/mp4, video/quicktime), 3-30 seconds. Duration and dimensions are detected during upload.
Subtitles: srt (application/x-subrip; multipart uploads may use text/plain only when the filename ends in .srt).
PDF, generic text files, octet-stream uploads, Matroska videos, and zip files are not supported for launch.
Send either multipart form-data with a file field, or send the raw file body with the asset Content-Type.
Content-Length is required and is validated before BeatAPI buffers the request body; chunked uploads without a declared length are rejected.
Returned URLs are HTTPS and long-lived for launch.
Uploaded audio files are duration-checked during upload. The response includes audio_duration_seconds when the uploaded asset is audio.
Uploaded videos are signature-, duration-, and dimension-checked. The response includes video_duration_seconds, width, and height.
Workflow task inputs still require public HTTPS URLs. Localhost, private network URLs, and data URLs are not accepted.

$	curl -X POST https://api.beatapi.io/v1/files \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: multipart/form-data" \
>	-F file=@string

1	{
2	"data": {
3	"id": "file_3xYz9",
4	"object": "file",
5	"url": "https://media.beatapi.io/inputs/file_3xYz9.mp3",
6	"key": "inputs/file_3xYz9.mp3",
7	"mime_type": "audio/mpeg",
8	"size_bytes": 1048576,
9	"purpose": "input",
10	"created_at": 1782210000,
11	"audio_duration_seconds": 64.02,
12	"audio_duration_source": "mp3_frame_scan"
13	}
14	}