Videos
POST https://gateway-api.mastra.ai/v1/videos
GET https://gateway-api.mastra.ai/v1/videos
GET https://gateway-api.mastra.ai/v1/videos/{id}
GET https://gateway-api.mastra.ai/v1/videos/{id}/content
Video generation runs as a job. Create a job, poll it until it finishes, then download the video. Replace google/veo-3.1 with any video model from /v1/models.
Create a jobDirect link to Create a job
curl https://gateway-api.mastra.ai/v1/videos \
-H "Authorization: Bearer $MASTRA_GATEWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "google/veo-3.1",
"prompt": "A lighthouse at dusk, waves crashing, slow aerial pan",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
model:
prompt:
duration:
resolution?:
aspect_ratio?:
generate_audio?:
true to generate an audio track.seed?:
Each job produces one video. Unknown fields return 422. Each model supports its own set of durations, resolutions, and aspect ratios. If no route serves the combination you ask for, the request is refused before any credit is held.
The response returns 202 with the job:
{
"id": "...",
"object": "video",
"model": "google/veo-3.1",
"status": "pending",
"created_at": 1763460000
}
Check a jobDirect link to Check a job
curl https://gateway-api.mastra.ai/v1/videos/$VIDEO_ID \
-H "Authorization: Bearer $MASTRA_GATEWAY_API_KEY"
status is one of pending, in_progress, completed, failed, or expired. A failed job includes an error code. A completed job includes expires_at, the Unix time after which the video can no longer be downloaded.
Status and download requests count against the key's rate limits.
Download the videoDirect link to Download the video
When status is completed, fetch the content:
curl https://gateway-api.mastra.ai/v1/videos/$VIDEO_ID/content \
-H "Authorization: Bearer $MASTRA_GATEWAY_API_KEY" \
-o lighthouse.mp4
List jobsDirect link to List jobs
GET /v1/videos lists your jobs, so you can recover a job ID if the create response was lost. It accepts limit (1 to 100, default 20) and after, the ID of the last job on the previous page.
BillingDirect link to Billing
Gateway holds credit for the requested duration when the job is created, then settles on the provider's reported cost. A job that produces no video isn't charged.