LOADING
API REST complète pour automatiser la génération de vidéos publicitaires. Authentification simple, endpoints puissants, webhooks temps réel.
Base URL: https://cinematicads.studio
OpenAPI 3.1: openapi.json (72 routes, 99 opérations)
Toutes les requêtes API nécessitent un token Bearer dans le header Authorization. Obtenez votre clé API dans les paramètres de votre compte.
Les sessions web utilisent un cookie HTTP-Only. Les clients API externes utilisent le header Bearer.
Authorization: Bearer YOUR_API_KEY
Chaque workflow consomme des crédits. Le coût dépend du type et du tier de qualité.
Tiers de qualité:
| 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 AuthLance un workflow de génération vidéo. Retourne un jobId pour le suivi en temps réel.
typestringrequisType: avatar | cinematic | clone | factory | influencer | brand | staticad | painpoint | ad-optimizerurlstringURL source (obligatoire pour clone/factory)conceptstringConcept créatif (pour cinematic/brand)qualitystringTier: standard (défaut) | premiumasyncbooleanMode asynchrone (défaut: true). Retourne immédiatement avec jobId.modelsobject{ image, video, voice } — Sélection de modèles AIformatsstringFormats vidéo: 9:16, 1:1, 16:9 (séparés par virgule)seasonalstringCampagne saisonnière: ramadan | eidframeworkstringFramework marketing: pas | aida | sb7 | cialdini | uvp | banthitlbooleanHuman-in-the-loop: pause après direction artistique pour review/api/workflow/stream?jobId={id} AuthConnexion Server-Sent Events pour le suivi temps réel d'un workflow. Émet des événements step, progress et result.
jobIdstringrequisID du job retourné par POST /api/workflow/api/batch/status?batchId={id} AuthRetourne le statut d'un batch de workflows (total, completed, failed, pending, active).
batchIdstringrequisID du batchcurl -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 AuthRetourne le solde de crédits actuel de l'utilisateur.
/api/user/stats AuthRetourne les statistiques de l'utilisateur: projets par type, crédits utilisés, taux de réussite.
startDatestringFiltre date début (YYYY-MM-DD)endDatestringFiltre date fin (YYYY-MM-DD)/api/user/analytics AuthRetourne les analytiques avancées: tendances, usage par type, distribution de crédits, heures de pointe.
periodstringPériode: 7d | 30d | 90d (défaut: 30d)/api/user/projects AuthRetourne tous les projets de l'utilisateur, triés par date décroissante.
/api/user/projects/export AuthExporte les projets de l'utilisateur au format ZIP avec vidéos et métadonnées.
/api/user/brand AuthRetourne le profil de marque configuré (nom, couleurs, ton, industrie, audience).
/api/user/brand AuthCrée ou met à jour le profil de marque. Toutes les générations futures utiliseront ces paramètres.
namestringrequisNom de la marqueindustrystringSecteur d'activitétonestringTon de communicationtargetAudiencestringAudience ciblecolorsobject{ primary, secondary, accent }/api/user/brand/knowledge/urls AuthAjoute une URL au Knowledge Base de la marque. Le contenu est scrappé et indexé automatiquement.
urlstringrequisURL à scrapper et indexer/api/user/brand/knowledge/files AuthUpload un fichier dans le Knowledge Base (PDF, DOCX, XLSX, CSV, TXT). Max 10MB.
fileFilerequisFichier (multipart/form-data)/api/models/statusRetourne les capacités AI disponibles (texte, image, vidéo) sans exposer les noms de providers.
/api/healthVérifie l'état du service. Retourne le statut et la version.
/api/export AuthTélécharge une vidéo générée au format MP4. Domaines autorisés uniquement (SSRF-safe).
sourcestringrequisURL de la vidéo source (HTTPS, domaines autorisés)Recevez des notifications en temps réel via Server-Sent Events (SSE) ou webhooks HTTP.
workflow.startedUn workflow a démarréworkflow.stepUne étape du workflow est terminée (progression)workflow.completedUn workflow est terminé avec succèsworkflow.failedUn workflow a échoué (crédits automatiquement remboursés)video.readyUne vidéo est prête au téléchargementworkflow.suspendedUn workflow attend une review humaine (HITL)L'API utilise les codes HTTP standard. Toutes les réponses suivent le format { success, data?, error? }.
| Code | Description |
|---|---|
| 200 | Succès |
| 400 | Requête invalide (paramètre manquant ou format incorrect) |
| 401 | Non authentifié (token manquant ou expiré) |
| 402 | Crédits insuffisants ou période d'essai expirée |
| 403 | Accès refusé (workflow réservé ou ressource interdite) |
| 404 | Ressource introuvable |
| 429 | Limite de requêtes dépassée (voir Rate Limiting) |
| 500 | Erreur serveur interne |
| 503 | Service temporairement indisponible (queue/Redis) |
{
"success": false,
"error": "Insufficient credits. Required: 2, available: 0"
}L'API applique des limites de requêtes par endpoint pour garantir la stabilité du service.
10 requêtes/heure10 connexions/heure100 requêtes/minuteLes headers de réponse incluent:
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 97 X-RateLimit-Reset: 1709312400
Bibliothèques clientes pour intégrer CinematicAds rapidement.
npm install @cinematicads/sdkpip install cinematicadscurl -X POST https://cinematicads.studio/api/workflowDisponible sur les plans Agency et Enterprise.
Obtenir ma clé API