Live

Botverse Transcode

Convert video and audio between formats. Submit a job, poll for completion, get a download URL.

MCP endpoint

https://botverse.cloud/mcp

Auth

X-API-Key header

Max source duration

10 minutes

Max source file size

5 GB

Starting price

~$0.008 / minute

Input formats

Botverse accepts a wide range of video and audio input formats. Common inputs and the correct content_type to pass to get_upload_url or transcode_from_url:

Format	Extension	content_type	Notes
MP4	.mp4	video/mp4	H.264 or H.265 source — most common
QuickTime	.mov	video/quicktime	Apple devices, Final Cut, camera raw
MKV	.mkv	video/x-matroska	Open container, any codec
WebM	.webm	video/webm	VP8/VP9 source
AVI	.avi	video/x-msvideo	Legacy Windows format
WMV	.wmv	video/x-ms-wmv	Windows Media Video — input only, not royalty-free to output
WMA	.wma	audio/x-ms-wma	Windows Media Audio — input only, not royalty-free to output
MP3	.mp3	audio/mpeg	Audio source
AAC	.aac	audio/aac	Audio source
WAV	.wav	audio/wav	Uncompressed audio
MXF	.mxf	application/mxf	Broadcast/professional camera formats

ℹ

Not seeing your format? Try passing application/octet-stream as the content_type — Botverse will detect the codec automatically during pre-flight validation. The job will be rejected with a clear error if the format isn't supported.

Output formats

output_format	Container	Codec	Use case	Status
mp4	MP4	H.264 — Main profile	Web delivery, broad device compatibility	Live
mp4	MP4	H.264 — Baseline profile	Mobile, streaming, legacy hardware (options.h264_profile: 'baseline')	Live
mp4	MP4	H.264 — High profile	Maximum quality, modern devices (options.h264_profile: 'high')	Live
webm	WebM	VP9	Web video, Chrome/Firefox native	Live
mov_prores	MOV	ProRes 422	Post-production, colour grading, editorial	Live
mp3	MP3	AAC/MP3	Audio-only extraction from video	Live
gif	GIF	Palette-optimised	Short loops, social media previews	Live
mp4_h265	MP4	H.265 (libx265)	Smaller files, streaming, modern devices	Coming soon

Pre-flight validation

Before any job is queued, Botverse validates the uploaded file synchronously. If the file fails validation, the tool returns an error immediately — you are not charged and no job is created.

Jobs are rejected if:

Source duration exceeds 10 minutes
File size exceeds 5 GB
No valid video stream is detected (unless output format is mp3)
File appears corrupted or unreadable
Codec is not in the supported set (very rare with common formats)

✓

Pre-flight results include source_resolution, source_duration, and source_codec— useful for your agent to report back to the user before submitting the job.

Tools

transcode_from_url

Fetch a video or audio file from a public HTTPS URL and submit it as a transcode job — no separate upload step required. The Botverse backend fetches the file server-side and queues the job immediately. Use this when the source file is already accessible online (CDN, Google Drive share, Dropbox, S3 public URL, etc.). Limited to 2 GB; use get_upload_url + transcode_video for larger files.

Parameters

Name	Type	Req	Description
source_url	string	yes	Public HTTPS URL of the source file. Must be a direct download link (not a webpage). Private/internal hosts (localhost, 192.168.x.x, AWS metadata) are rejected.
output_format	string	yes	One of: mp4, webm, mov_prores, mp3, gif.
options	object	no	Optional encoding parameters. Same fields as transcode_video. Key option for mp4: h264_profile ('baseline' \| 'main' \| 'high').

Response fields

Field	Type	Description
job_id	string	Unique job identifier. Poll get_job_status with this.
status	string	"pending" on success.
source_url	string	The URL that was fetched.
message	string	Human-readable status message.

get_upload_url

Get a presigned S3 PUT URL to upload a source file. The URL expires in 15 minutes. PUT your file directly to the URL — do not use multipart/form-data; send the raw file bytes with Content-Type: video/mp4 (or appropriate MIME type).

Parameters

Name	Type	Req	Description
filename	string	yes	Original filename including extension. Used to set the S3 object key suffix.
content_type	string	no	MIME type. Defaults to "video/mp4".

Response fields

Field	Type	Description
object_key	string	S3 object key. Pass this to transcode_video.
upload_url	string	Presigned S3 PUT URL. Expires in 15 minutes.

transcode_video

Submit a transcode job. Runs pre-flight validation synchronously, then queues the encode. Returns immediately with a job_id. Poll get_job_status until status is 'complete' or 'failed'.

Parameters

Name	Type	Req	Description
object_key	string	yes	S3 object key from get_upload_url.
output_format	string	yes	One of: mp4, webm, mov_prores, mp3, gif.
options.h264_profile	string	no	H.264 profile for mp4 output: 'baseline' (max compatibility — mobile, streaming, legacy hardware), 'main' (balanced, default), 'high' (best quality, modern devices).
options.start_time	string	no	Trim start position, e.g. '00:01:30' or '90' seconds.
options.duration	number	no	Encode only N seconds after start_time.
options.width / height	number	no	Resize output. Single dimension scales proportionally.
options.bitrate	string	no	Video bitrate override, e.g. '2M'.
options.framerate	number	no	Output frame rate, e.g. 24 or 30.

Response fields

Field	Type	Description
job_id	string	Unique job identifier. Use for polling and download.
status	string	"queued" on success. "failed" if pre-flight rejected the file.
error	string	Error message. Present only if status is 'failed'.
source_resolution	string	Detected resolution from pre-flight, e.g. "1920x1080".
source_duration	number	Detected duration in seconds from pre-flight.
source_codec	string	Detected video codec from pre-flight.

get_job_status

Poll the status of a transcode job. Call every 5 seconds until status is 'complete' or 'failed'. Jobs time out after 14.5 minutes; the status will be 'failed' with an appropriate error message.

Parameters

Name	Type	Req	Description
job_id	string	yes	Job ID from transcode_video response.

Response fields

Field	Type	Description
job_id	string	The job ID.
status	string	"queued" \| "encoding" \| "complete" \| "failed".
output_key	string	S3 key of the transcoded file. Present only when complete.
source_resolution	string	e.g. 2880x1704
source_duration	number	Source video duration in seconds.
job_cost	number	Cost in USD. Present only when complete.
error	string	Error message. Present only when failed.
created_at	string	ISO 8601 timestamp.
completed_at	string	ISO 8601 timestamp. Present only when complete.

get_download_url

Get a presigned S3 GET URL to download the transcoded file. The URL expires in 24 hours. Call this after get_job_status returns 'complete'.

Parameters

Name	Type	Req	Description
job_id	string	yes	Job ID from transcode_video.

Response fields

Field	Type	Description
download_url	string	Presigned S3 GET URL. Expires in 24 hours.
output_key	string	S3 key of the transcoded file.
expires_at	string	ISO 8601 expiry timestamp.

get_wallet_balance

Check the current wallet balance and auto-refill settings for your account. Callable by bots — no dashboard login needed.

Response fields

Field	Type	Description
balance_usd	number	Current prepaid balance in USD.
auto_refill	object	{ enabled: boolean, threshold_usd: number, amount_usd: number }
monthly_cap_usd	number	Monthly spend cap. Null if not set.
month_to_date_usd	number	Spend so far this calendar month.

get_usage_history

Get a list of recent jobs and their costs. Useful for generating cost reports or debugging failed jobs.

Parameters

Name	Type	Req	Description
limit	number	no	Max jobs to return. Default: 20, max: 100.
status	string	no	Filter by status: complete \| failed \| all. Default: all.

Response fields

Field	Type	Description
jobs	array	Array of job objects. Each has: job_id, status, output_format, source_duration, job_cost, created_at, completed_at.
total_cost_usd	number	Sum of all returned job costs.

Which workflow to use

Situation	Recommended tool
File is on a public URL (CDN, Dropbox, Google Drive, S3 public link)	transcode_from_url — one call, no upload step
File is on the user's machine and the agent can read/upload it (< 2 GB)	get_upload_url → PUT → transcode_video
File is on the user's machine, > 2 GB	get_upload_url → PUT → transcode_video
Running inside claude.ai — S3 PUT is network-blocked	transcode_from_url (bypasses sandbox restriction)

Example — transcode from URL

Use transcode_from_url when the source file is already hosted online. Botverse fetches it server-side — no upload step needed.

Step 1 — submit the job

Agent calls transcode_from_url

// Agent calls:
{
  "name": "transcode_from_url",
  "arguments": {
    "source_url": "https://cdn.example.com/footage/interview-raw.mp4",
    "output_format": "webm"
  }
}

// Botverse returns:
{
  "job_id": "job_3e8c4a12",
  "status": "pending",
  "source_url": "https://cdn.example.com/footage/interview-raw.mp4",
  "message": "File fetched and job queued. Poll get_job_status with job_id to track progress."
}

Step 2 — poll for completion

Agent polls get_job_status every 5 seconds

{
  "job_id": "job_3e8c4a12",
  "status": "complete",
  "source_duration": 187.4,
  "source_resolution": "3840x2160",
  "job_cost": 0.025,
  "completed_at": "2026-05-20T10:14:38Z"
}

Step 3 — get download URL

Agent calls get_download_url

{ "name": "get_download_url", "arguments": { "job_id": "job_3e8c4a12" } }

// Returns:
{
  "download_url": "https://botverse-files.s3.us-east-2.amazonaws.com/outputs/...?X-Amz-...",
  "expires_at": "2026-05-21T10:14:38Z"
}

⚠

source_url must be a direct download link, not a webpage. For Google Drive, use the export/download URL format. For Dropbox, replace ?dl=0 with ?dl=1. Private networks, localhost, and cloud metadata endpoints (169.254.169.254) are blocked.

Full example — upload and transcode

Use this flow when your agent has the file locally or the file exceeds 2 GB. The agent calls each tool in sequence, passing the output of one call as the input to the next.

Step 1 — get an upload URL

Agent calls get_upload_url

// Agent calls:
{ "name": "get_upload_url", "arguments": { "filename": "keynote-march.mp4" } }

// Botverse returns:
{
  "object_key": "uploads/acct_abc123/1747123456/keynote-march.mp4",
  "upload_url": "https://botverse-files.s3.us-east-2.amazonaws.com/uploads/...?X-Amz-..."
}

Step 2 — upload the file

HTTP PUT to the presigned URL

PUT https://botverse-files.s3.us-east-2.amazonaws.com/uploads/...?X-Amz-...
Content-Type: video/mp4
[raw file bytes]

// Response: 200 OK (no body)

Step 3 — submit the transcode job

Agent calls transcode_video

// Agent calls:
{
  "name": "transcode_video",
  "arguments": {
    "object_key": "uploads/acct_abc123/1747123456/keynote-march.mp4",
    "output_format": "webm"
  }
}

// Botverse returns (pre-flight passed, job queued):
{
  "job_id": "job_7f3a1b9c",
  "status": "queued",
  "source_resolution": "1920x1080",
  "source_duration": 342.7,
  "source_codec": "h264"
}

Step 4 — poll for completion

Agent polls get_job_status every 5 seconds

// After ~45 seconds of polling:
{
  "job_id": "job_7f3a1b9c",
  "status": "complete",
  "output_key": "outputs/acct_abc123/job_7f3a1b9c/keynote-march.webm",
  "source_resolution": "1920x1080",
  "source_duration": 342.7,
  "job_cost": 0.046,
  "created_at": "2026-05-16T14:22:10Z",
  "completed_at": "2026-05-16T14:23:02Z"
}

Step 5 — get download URL

Agent calls get_download_url

// Agent calls:
{ "name": "get_download_url", "arguments": { "job_id": "job_7f3a1b9c" } }

// Botverse returns:
{
  "download_url": "https://botverse-files.s3.us-east-2.amazonaws.com/outputs/...?X-Amz-...",
  "output_key": "outputs/acct_abc123/job_7f3a1b9c/keynote-march.webm",
  "expires_at": "2026-05-17T14:23:02Z"
}

✓

The agent can pass the download URL directly to the user, or use it as input to the next step in a multi-service pipeline. See the Workflows guide for how to chain Botverse services.