REST API

The same primitives over HTTP.

Use the API from scripts, CI and backends with a Bearer key. Generation inputs match the corresponding MCP tool, but account checks, uploads and retry identity use the HTTP routes and headers below.

On this page

Base URL and auth
Routes
Example
OpenAPI

Base URL and auth

https://api.agent-media.ai

Authorization: Bearer YOUR_AGENT_MEDIA_API_KEY

Routes

Method	Path	Body	Returns
POST	/v1/skills/make_ugc/quote	{ script or scene_action, person?, image?, character?, product_image?, broll_url?, captions?, caption_style? }	200 { credits, available, committed, sufficient }; no generation or debit
POST	/v1/skills/make_ugc/run	the same exact quoted input	202 { skill_run_id, workflow_id, status }; poll the skill run for final_output.video_url
GET	/v1/skills/runs/{skill_run_id}	to	{ status, steps, final_output, error }; final_output.video_url when succeeded
POST	/v2/generate/{video\|image\|audio}	the tool arguments	201 new job; 200 saved receipt on retry; 202 acknowledgement uncertain. Returns job_id, request_id, credits_deducted, status_url and model details.
POST	/v2/quote/{video\|image\|audio}	the same arguments	200 { credits, usd, model, mode?, quality?, breakdown, auto? }
GET	/v1/videos/{job_id}	to	{ status, video_url, ... }; video_url holds the output for image/audio too. 503 STATUS_UNAVAILABLE: retry the same job.
GET	/v1/me/readiness	to	{ authenticated, credits, generation, uploads, billing_url }; 503 means balance unknown
GET	/v1/models	to	the catalog with modes, prices per quality and recent stats; public
POST	/v1/runs/{job_id}/rate	{ score: 1..5, note? }	200 { job_id, model, score }
GET	/v1/upload-sessions	to	{ sessions }; owned unexpired session IDs and filenames, no image URLs or tokens
GET	/v1/upload-sessions/{session_id}/previews	to	{ previews, unavailable }; owner-only bounded JPEG inspection previews, not generation inputs
POST	/v1/upload-sessions	{}; temporary uploads must be enabled	201 { session_id, upload_url, upload_token, expires_at, max_bytes, max_files, images }
GET	/v1/upload-sessions/{session_id}	to	{ session_id, expires_at, max_bytes, max_files, images }; owner authentication required
POST	/v1/uploads/presign	{ bytes, content_type?, filename? }	{ put_url, upload_key, content_type, bytes, expires_in, ... }; PUT original bytes, then confirm
POST	/v1/uploads/confirm	{ upload_key }	{ image_url, mime, bytes }
POST	/v1/uploads/image	{ image_base64 } or { image_url }	{ image_url }
GET	/v1/characters	to	saved characters with sheet/portrait URLs

The hosted connector exposes make_ugc as an optional composed workflow, with quote_ugc before spending. Agents can instead combine the direct image, video and audio tools freely. The other fixed recipes remain REST and CLI routes for the dashboard.

Quote before generating

curl -X POST https://api.agent-media.ai/v2/quote/video \
  -H "Authorization: Bearer ma_..." -H "Content-Type: application/json" \
  -d '{ "prompt": "A 28-year-old woman in a bright kitchen, phone framing, holds a serum bottle to the lens and says: \"Okay, I did not expect this to work.\"", "seconds": 5 }'

After reviewing the quote and confirming the budget, submit the same inputs to /v2/generate/video. Send a unique Idempotency-Key header for each intended generation. Keep that key and the exact inputs for retries; changing the key can charge for another run. Poll the returned status_url.

HTTP 201 creates a job; HTTP 200 can replay an existing receipt; HTTP 202 with dispatch_status: unknown means keep polling that job. A temporary HTTP 503 status error is not a failed generation or a confirmed refund.

OpenAPI

Machine-readable spec at https://api.agent-media.ai/openapi.json, interactive reference at https://api.agent-media.ai/docs.