agent-media

Developer

UGC Video API: Generate Videos with a POST Request

Most AI video tools lock you into a browser. agent-media exposes a public REST API at agent-media.ai/api/v1/. Send a script, pick an actor, get back a finished MP4 with lip-sync, subtitles, and music. Bearer token auth. JSON responses. Standard polling flow. See pricing.

Authentication

Every request requires a Bearer token. Generate an API key from your dashboard. Keys start with ma_ and are scoped to your account.

authentication header

Authorization: Bearer ma_your_api_key_here

All endpoints return JSON. Error responses include a message field with a human-readable explanation.

API Endpoints

POST /api/v1/videos

Submit a video generation job. Returns a job ID immediately. The video renders asynchronously. Poll the status endpoint to check progress.

curl
curl -X POST https://agent-media.ai/api/v1/videos \
  -H "Authorization: Bearer ma_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "Stop scrolling. This app saves me two hours every morning.",
    "actor": "sofia",
    "duration": 10,
    "subtitle_style": "tiktok",
    "voice_tone": "energetic",
    "aspect_ratio": "9:16"
  }'

Response (202 Accepted)

json
{
  "id": "vid_abc123",
  "status": "processing",
  "credits_charged": 300,
  "estimated_seconds": 120,
  "created_at": "2026-04-15T10:30:00Z"
}

Request Body Parameters

FieldTypeRequiredDescription
scriptstringYesThe spoken script. Word count validated against duration.
actorstringYesActor slug. Get slugs from GET /api/v1/actors.
durationnumberYes5, 10, or 15 seconds.
subtitle_stylestringNoOne of 17 styles: tiktok, hormozi, minimal, clean, bold, etc. Default: tiktok.
voice_tonestringNoenergetic, calm, confident, or dramatic. Default: energetic.
aspect_ratiostringNo9:16, 16:9, or 1:1. Default: 9:16.
music_genrestringNochill, energetic, corporate, dramatic, or upbeat.
overlay_textstringNoPersistent branded text banner on the video.

GET /api/v1/videos/:id

Check the status of a video job. When status is completed, the output_url field contains a direct link to the MP4.

curl
curl https://agent-media.ai/api/v1/videos/vid_abc123 \
  -H "Authorization: Bearer ma_your_api_key"

Response (completed)

json
{
  "id": "vid_abc123",
  "status": "completed",
  "output_url": "https://media.agent-media.ai/videos/vid_abc123.mp4",
  "duration": 10,
  "credits_charged": 300,
  "created_at": "2026-04-15T10:30:00Z",
  "completed_at": "2026-04-15T10:32:15Z"
}

GET /api/v1/actors

List all available actors. Returns slug, name, gender, and variant count. Use the slug when creating videos.

curl
curl https://agent-media.ai/api/v1/actors \
  -H "Authorization: Bearer ma_your_api_key"

Response (truncated)

json
{
  "actors": [
    {
      "slug": "sofia",
      "name": "Sofia",
      "gender": "female",
      "variants": 10
    },
    {
      "slug": "marco",
      "name": "Marco",
      "gender": "male",
      "variants": 10
    }
  ],
  "total": 200
}

Polling Flow: Submit, Poll, Download

Video generation takes 1 to 3 minutes. The recommended pattern: submit the job, then poll every 10 seconds until the status is completed or failed.

bash polling script
# Submit the video
VIDEO_ID=$(curl -s -X POST https://agent-media.ai/api/v1/videos \
  -H "Authorization: Bearer ma_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"script":"This changed everything for me.","actor":"sofia","duration":10}' \
  | jq -r '.id')

echo "Submitted: $VIDEO_ID"

# Poll until done
while true; do
  STATUS=$(curl -s https://agent-media.ai/api/v1/videos/$VIDEO_ID \
    -H "Authorization: Bearer ma_your_api_key" \
    | jq -r '.status')

  echo "Status: $STATUS"

  if [ "$STATUS" = "completed" ]; then
    OUTPUT=$(curl -s https://agent-media.ai/api/v1/videos/$VIDEO_ID \
      -H "Authorization: Bearer ma_your_api_key" \
      | jq -r '.output_url')
    echo "Download: $OUTPUT"
    break
  fi

  if [ "$STATUS" = "failed" ]; then
    echo "Video generation failed."
    break
  fi

  sleep 10
done

Status values: processing (rendering in progress), completed (MP4 ready at output_url), failed (check the error field for details).

API Pricing

The API uses the same credit system as the CLI and dashboard. 30 credits per second of video.

DurationCreditsCost
5 seconds150~$1.50
10 seconds300~$3.00
15 seconds450~$4.50

AI script generation adds 5 credits per request. View full pricing plans.

Why the agent-media API

Public API with real docs

Full REST API documentation at /docs/api. Not a hidden enterprise endpoint. Every developer gets the same access.

Standard Bearer auth

No OAuth dance. Generate an API key, add it as a Bearer token, and start making requests. Keys are scoped to your account.

Predictable JSON responses

Every endpoint returns consistent JSON shapes. Status codes follow HTTP conventions. No guessing.

200 actors via API

List actors, pick variants, and specify outfits programmatically. No browser needed to browse the actor library.

Word count validation

The API rejects scripts that exceed the word limit for the chosen duration. 12 words for 5s, 25 for 10s, 37 for 15s.

Same pricing everywhere

API, CLI, and dashboard all use the same credit pool. No API surcharge. 300 credits per 10-second video.

Related Pages

Full API Reference AI Video CLI UGC Cost Calculator TikTok UGC Ads MakeUGC Alternative
View Pricing

Last updated: April 2026