Media uploads and conversion

Choose local upload or a public media URL, verify file metadata, and apply platform and conversion limits.

Choose the input flow before publishing. Uploading a file and converting it to meet a platform's requirements are separate operations.

Your input	Next action
Public image or video URL	Pass it directly in mediaUrls. No upload step required.
Finished Blotato visual	Pass the returned mediaUrl or imageUrls. No upload step required.
File on the user's computer or in the agent's workspace	Complete a presigned upload, then pass publicUrl.
Private download link or editor/share page	Obtain a public downloadable media URL, or upload the file bytes.

Upload a local file

1. Call blotato_create_presigned_upload_url with filename, including its extension. For REST, call POST /v2/media/uploads with the same field.

2. Send an HTTP PUT to the returned presignedUrl, with the raw file bytes as the request body.

3. After the upload succeeds, pass the returned publicUrl in the publish request's mediaUrls array.

The PUT body is raw bytes. Do not send JSON or multipart form data. The assistant needs access to the file and an HTTP tool or shell to perform the PUT. Creating the URL alone does not upload the file.

If the assistant's environment blocks the upload destination, follow the MCP network-egress troubleshooting. For REST upload shapes, see Upload Media.

Check conversion requirements

Blotato validates media for the destination platform and performs supported conversions when required. Automatic video conversion is limited to videos no longer than 120 seconds. A longer video must already meet the applicable publishing requirements.

The processing queue checks the original file and existing variants. It reuses a valid file without conversion. If none is valid, it either requests a supported conversion of the original or returns the validation error. File upload does not imply every file is converted.

1. Check the platform media requirements.

2. Check the file's container, codecs, dimensions, aspect ratio, duration, bitrate, and size.

3. If a video longer than 120 seconds needs cropping, resizing, or re-encoding, edit and export it before publishing.

4. Use a URL which serves the media without a login.

5. Submit the post and check its final publishing status.

An .mp4 filename does not prove the container, codecs, or aspect ratio. Upload success does not establish platform compatibility.

For Instagram Reels, see the Reel troubleshooting checklist. Account upload limits and platform file limits both apply. See Billing and credits and Media requirements.

Container identification errors

Unsupported media format: mov,mp4,m4a,3gp,3g2,mj2 means Blotato did not recognize the file's container brand. The listed formats describe the probe's format family, not the file's exact type. This error is separate from the 120-second conversion limit.

1. Inspect the file's container metadata, including major_brand. Do not identify the format from its filename alone.

2. Export the source as MP4 with H.264 video and AAC audio. Renaming the extension does not change the container.

3. Inspect the exported file and check its dimensions, bitrate, size, and duration against the destination's requirements.

4. Verify the original submission's status before retrying. If the error persists, provide support with the submission ID and the exported file's metadata. Keep signed URLs and credentials out of support messages.

For the agent: the current parser recognizes MP4 brands isom, iso1 through iso6, mp41, and mp42. It recognizes MOV through the exact padded brand qt . Missing or unrecognized brands produce the format-list error, even for a short video. A recognized container does not prove publishing compatibility.