LOADING
Complete REST API to automate video ad generation. Simple authentication, powerful endpoints, real-time webhooks.
Base URL: https://cinematicads.studio
OpenAPI 3.1: openapi.json (72 routes, 99 operations)
All API requests require a Bearer token in the Authorization header. Get your API key from your account settings.
Web sessions use an HTTP-Only cookie. External API clients use the Bearer header.
Authorization: Bearer YOUR_API_KEY
Each workflow consumes credits. The cost depends on the type and quality tier.
Quality tiers:
| Workflow | Standard | Premium |
|---|---|---|
| Director (cinematic) | 1 | 2 |
| Presenter (avatar) | 2 | 3 |
| Multi-Format (factory) | 3 | 5 |
| Inspiration (clone) | 3 | 5 |
| Influencer | 8 | 15 |
| Brand Clone | 15 | 25 |
| Static Ad | 1 | 1 |
| Pain Point | 1 | 1 |
| Ad Optimizer | 1 | 2 |
| Local Audit | 2 | 3 |
/api/workflow AuthLaunches a video generation workflow. Returns a jobId for real-time tracking.
typestringrequiredType: avatar | cinematic | clone | factory | influencer | brand | staticad | painpoint | ad-optimizerurlstringSource URL (required for clone/factory)conceptstringCreative concept (for cinematic/brand)qualitystringTier: standard (default) | premiumasyncbooleanAsync mode (default: true). Returns immediately with jobId.modelsobject{ image, video, voice } — AI model selectionformatsstringVideo formats: 9:16, 1:1, 16:9 (comma-separated)seasonalstringSeasonal campaign: ramadan | eidframeworkstringMarketing framework: pas | aida | sb7 | cialdini | uvp | banthitlbooleanHuman-in-the-loop: pause after art direction for review/api/workflow/stream?jobId={id} AuthServer-Sent Events connection for real-time workflow tracking. Emits step, progress, and result events.
jobIdstringrequiredJob ID returned by POST /api/workflow/api/batch/status?batchId={id} AuthReturns status of a batch of workflows (total, completed, failed, pending, active).
batchIdstringrequiredBatch IDcurl -X POST https://cinematicads.studio/api/workflow \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "cinematic",
"concept": "Luxury perfume ad with golden tones",
"quality": "premium",
"formats": "9:16,1:1",
"async": true
}'{
"success": true,
"jobId": "wf_abc123xyz",
"message": "Workflow queued",
"cost": 2
}curl -N "https://cinematicads.studio/api/workflow/stream?jobId=wf_abc123xyz" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: text/event-stream"
event: step
data: {"step":"art_direction","status":"completed","progress":20}
event: step
data: {"step":"video_generation","status":"completed","progress":60}
event: result
data: {"success":true,"videoUrl":"https://...","duration":15}/api/user/credits AuthReturns the current credit balance.
/api/user/stats AuthReturns user statistics: projects by type, credits used, success rate.
startDatestringStart date filter (YYYY-MM-DD)endDatestringEnd date filter (YYYY-MM-DD)/api/user/analytics AuthReturns advanced analytics: trends, usage by type, credit distribution, peak hours.
periodstringPeriod: 7d | 30d | 90d (default: 30d)/api/user/projects AuthReturns all user projects, sorted by date descending.
/api/user/projects/export AuthExports user projects as a ZIP file with videos and metadata.
/api/user/brand AuthReturns the configured brand profile (name, colors, tone, industry, audience).
/api/user/brand AuthCreates or updates the brand profile. All future generations will use these settings.
namestringrequiredBrand nameindustrystringIndustry sectortonestringCommunication tonetargetAudiencestringTarget audiencecolorsobject{ primary, secondary, accent }/api/user/brand/knowledge/urls AuthAdds a URL to the Brand Knowledge Base. Content is scraped and indexed automatically.
urlstringrequiredURL to scrape and index/api/user/brand/knowledge/files AuthUploads a file to the Knowledge Base (PDF, DOCX, XLSX, CSV, TXT). Max 10MB.
fileFilerequiredFile (multipart/form-data)/api/models/statusReturns available AI capabilities (text, image, video) without exposing provider names.
/api/healthChecks service status. Returns status and version.
/api/export AuthDownloads a generated video as MP4. Allowed domains only (SSRF-safe).
sourcestringrequiredSource video URL (HTTPS, allowed domains only)Receive real-time notifications via Server-Sent Events (SSE) or HTTP webhooks.
workflow.startedA workflow has startedworkflow.stepA workflow step completed (progress update)workflow.completedA workflow completed successfullyworkflow.failedA workflow failed (credits automatically refunded)video.readyA video is ready for downloadworkflow.suspendedA workflow is waiting for human review (HITL)The API uses standard HTTP codes. All responses follow the format { success, data?, error? }.
| Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad request (missing parameter or invalid format) |
| 401 | Unauthorized (missing or expired token) |
| 402 | Insufficient credits or trial expired |
| 403 | Forbidden (reserved workflow or restricted resource) |
| 404 | Resource not found |
| 429 | Rate limit exceeded (see Rate Limiting) |
| 500 | Internal server error |
| 503 | Service temporarily unavailable (queue/Redis) |
{
"success": false,
"error": "Insufficient credits. Required: 2, available: 0"
}The API enforces per-endpoint rate limits to ensure service stability.
10 requests/hour10 connections/hour100 requests/minuteResponse headers include:
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 97 X-RateLimit-Reset: 1709312400
Client libraries to integrate CinematicAds quickly.
npm install @cinematicads/sdkpip install cinematicadscurl -X POST https://cinematicads.studio/api/workflowAvailable on Agency and Enterprise plans.
Get my API key