agent-media

API Reference

Generate UGC videos, list actors, and check job status via REST API.

Download OpenAPI Spec·Import into Postman / Insomnia: agent-media.ai/openapi.json

Getting Started

Zero to first video in 5 minutes.

1. Get an API Key

Create one in your dashboard settings. Starts with ma_.

2. List Actors

curl https://api-v2-production-2f24.up.railway.app/v1/actors?limit=5 \
  -H "Authorization: Bearer ma_YOUR_KEY"

3. Generate a Video

curl -X POST https://api-v2-production-2f24.up.railway.app/v1/generate/ugc_video \
  -H "Authorization: Bearer ma_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "Have you ever struggled with creating video content? This tool changed everything.",
    "actor_slug": "sofia",
    "tone": "energetic",
    "style": "hormozi",
    "target_duration": 10
  }'

4. Poll for Status

curl https://api-v2-production-2f24.up.railway.app/v1/videos/{job_id} \
  -H "Authorization: Bearer ma_YOUR_KEY"

# When status: "completed", video_url has your MP4.

Authentication

All endpoints require a Bearer token. API keys (ma_ prefix) or Supabase JWTs.

Authorization: Bearer ma_YOUR_API_KEY
POST/v1/generate/ugc_video

Generate a UGC-style video from a script or prompt.

Parameters

NameTypeDescription
scriptstringNarration script (50-3000 chars). Required if no prompt.
promptstringAI generates script from this. Required if no script.
actor_slugstringAI actor slug. Use GET /v1/actors to browse.
toneenumenergetic, calm, confident, dramatic
stylestringSubtitle style (17 options). Default: hormozi
target_durationnumber5, 10, or 15 seconds
musicenumchill, energetic, corporate, dramatic, upbeat
aspect_ratioenum9:16, 16:9, 1:1
allow_brollbooleanEnable B-roll cutaway scenes
broll_imagesstring[]Image URLs for B-roll (max 10)
webhook_urlstringHTTPS URL for completion callback
ctastringEnd screen CTA (max 100 chars)
GET/v1/actors

List available AI actors. Paginated with limit/offset.

# Response: { actors: [...], total: 200, limit: 50, offset: 0 }
GET/v1/videos/{jobId}

Poll job status. Returns video_url when completed.

{ "job_id": "uuid", "status": "completed", "video_url": "https://...mp4" }

Webhooks

Pass webhook_url to receive a POST when the job finishes.

# Completed: { "job_id": "uuid", "status": "completed", "video_url": "https://...mp4" }
# Failed:    { "job_id": "uuid", "status": "failed", "error_message": "..." }

HTTPS only. 3 retries, exponential backoff. Test with webhook.site.

SDKs

TypeScript

import { AgentMedia } from '@agent-media/sdk';
const client = new AgentMedia({ apiKey: 'ma_xxx' });
const video = await client.createVideo({ script: '...', actor_slug: 'sofia' });
console.log(video.video_url);

Python

from agent_media import AgentMedia
client = AgentMedia(api_key="ma_xxx")
video = client.create_video(script="...", actor_slug="sofia")
print(video["video_url"])

Interactive API Explorer

Try endpoints below. Enter your API key in the auth field.