Developers

BuzzSmile API · v1.0.0

Quotes, AI media creation, job tracking, balance: one key, one door, the same rules as the screens.

The reference reads in French and in English (button at the top); the contract — field names, codes, paths — is the same in every language.

Get started in three calls

A quote, a creation at the quoted price, tracking until the output. Replace the values in angle brackets.

# 1. Le prix, et son jeton de devis
curl -s -X POST "https://www.buzz-smile.com/api/v1/quotes" -H "Authorization: Bearer $BUZZSMILE_API_KEY" -H "Content-Type: application/json" \
  -d '{"capability":"image.generate","prompt":"Un chat roux sur un canapé jaune","width":1024,"height":1024}'

# 2. La création, au prix annoncé (quote_token) → job_id + job_token
curl -s -X POST "https://www.buzz-smile.com/api/v1/images/generations" -H "Authorization: Bearer $BUZZSMILE_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"Un chat roux sur un canapé jaune","width":1024,"height":1024,"quote_token":"<quote_token>"}'

# 3. Le suivi, toutes les 3 secondes, jusqu'à status = succeeded ; puis la sortie
curl -s "https://www.buzz-smile.com/api/v1/jobs/<job_id>" -H "Authorization: Bearer $BUZZSMILE_API_KEY" -H "X-Job-Token: <job_token>"
curl -s "https://www.buzz-smile.com/api/v1/jobs/<job_id>/outputs/<asset_id>" -H "Authorization: Bearer $BUZZSMILE_API_KEY" -o image.png

# (Facultatif) Une entrée à vous — photo à retoucher, voix, vidéo — : son id se donne ensuite en `image`, `audio` ou `video`
curl -s -X POST "https://www.buzz-smile.com/api/v1/media" -H "Authorization: Bearer $BUZZSMILE_API_KEY" -F "file=@photo.jpg"

Authentication

Every call carries a shop API key in the `Authorization: Bearer …` header. A key has scopes; each endpoint requires its own.

compte:lire — read the balance and the allowance
travaux:lire — read jobs and their outputs
cout:lire — request a quote, reserving nothing
travaux:ecrire — start generations — spends the key creator's tokens

Devis

Demander un devis

POST/api/v1/quotesScope : cout:lire

Le prix RÉEL d'une demande, chez le fournisseur que la politique de routage retiendrait, marge du plan comprise — sans rien réserver ni débiter. La réponse porte un `quote_token` : représentez-le à la création pour que le montant réservé soit exactement celui-ci.

Un devis est mis en cache quelques minutes par réglages (pas par consigne) : changer `width`/`height` le recalcule.Un fournisseur à devis observable est réellement interrogé : un devis n'est pas gratuit en appels, seulement en jetons.

Request body

Name	Type	Required	Description
`capability`	`string ∈ image.generate \| image.edit \| image.cutout \| image.upscale \| image.outpaint \| image.inpaint \| video.generate \| video.lipsync \| video.upscale \| video.edit \| video.motion \| video.extend \| video.clip \| video.render \| audio.tts \| audio.transcribe \| audio.music \| audio.voiceclone`	yes	La capacité à deviser — celle de l'endpoint de création que vous appellerez ensuite.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`…`	`object`	no	Les mêmes champs que l'endpoint de création visé (`prompt`, `width`, `height`, `image`, `duration_s`…) : un devis se calcule sur les réglages exacts de la demande.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/quotes" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"capability":"image.generate","tier":"standard","prompt":"Un chat roux sur un canapé jaune","width":1024,"height":1024}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`capability`	`string`	La capacité devisée.
`tier`	`string`	Le palier devisé.
`tokens`	`integer`	Le prix en jetons (1 jeton = 0,001 $), marge comprise.
`model`	`string`	Le modèle que la politique retiendrait à cet instant.
`provider`	`string`	Le fournisseur de ce modèle.
`quote_token`	`string`	Le jeton de devis, à représenter à la création.
`expires_in_s`	`integer`	La validité du jeton, en secondes.
`request_id`	`string`	L'identifiant de corrélation.

Response example

{
  "ok": true,
  "capability": "image.generate",
  "tier": "standard",
  "tokens": 25,
  "model": "google/nano-banana",
  "provider": "kie",
  "quote_token": "aigen:devis:image.generate:standard:2c9b…",
  "expires_in_s": 300,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescapacite_non_ouvertefonction_indisponibleaucun_candidat

Images

Générer une image

POST/api/v1/images/generationsScope : travaux:ecrireimage.generate

Une image depuis une consigne. La définition visée choisit la plus proche que le modèle servi sait produire.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	La consigne, en langue naturelle (3 000 signes au plus).
`negative_prompt`	`string`	no	Ce qu'il ne faut pas voir. Ignoré par les modèles qui ne le lisent pas.
`width`	`integer`	no	Largeur visée en pixels. Le modèle servi honore la définition la plus proche qu'il sait produire. [64 – 8192]
`height`	`integer`	no	Hauteur visée en pixels. [64 – 8192]
`steps`	`integer`	no	Étapes de diffusion, bornées par le modèle servi (un modèle qui n'en accepte qu'une valeur la pose lui-même). [1 – 100]
`seed`	`integer`	no	Graine de reproductibilité ; absente ou `-1` = au hasard.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/images/generations" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Un chat roux sur un canapé jaune, lumière du matin","width":1024,"height":1024,"quote_token":"aigen:devis:…"}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Retoucher une image

POST/api/v1/images/editsScope : travaux:ecrireimage.edit

Une retouche guidée par la consigne sur toute l'image (Qwen Image Edit, Nano Banana, FLUX Kontext… selon la politique).

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	La consigne, en langue naturelle (3 000 signes au plus).
`image`	`string (uuid)`	yes	L'identifiant d'une image PUBLIQUE de la médiathèque de la boutique (`GET /api/v1/media`). Jamais une adresse : le socle la résout et vérifie qu'elle vous appartient.
`steps`	`integer`	no	Étapes de diffusion, bornées par le modèle servi (un modèle qui n'en accepte qu'une valeur la pose lui-même). [1 – 100]
`seed`	`integer`	no	Graine de reproductibilité ; absente ou `-1` = au hasard.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/images/edits" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"fond blanc, lumière de studio","image":"5641914d-89fe-45f8-b8e5-81bcb566f58e"}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Détourer une image

POST/api/v1/images/cutoutsScope : travaux:ecrireimage.cutout

Retire le fond ; la sortie est un PNG transparent. Pas de consigne : l'opération se suffit.

Request body

Name	Type	Required	Description
`image`	`string (uuid)`	yes	L'identifiant d'une image PUBLIQUE de la médiathèque de la boutique (`GET /api/v1/media`). Jamais une adresse : le socle la résout et vérifie qu'elle vous appartient.
`seed`	`integer`	no	Graine de reproductibilité ; absente ou `-1` = au hasard.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/images/cutouts" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"5641914d-89fe-45f8-b8e5-81bcb566f58e"}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Agrandir une image

POST/api/v1/images/upscalesScope : travaux:ecrireimage.upscale

Agrandissement ×4 (RealESRGAN, Topaz, Recraft… selon la politique). Pas de consigne.

Request body

Name	Type	Required	Description
`image`	`string (uuid)`	yes	L'identifiant d'une image PUBLIQUE de la médiathèque de la boutique (`GET /api/v1/media`). Jamais une adresse : le socle la résout et vérifie qu'elle vous appartient.
`seed`	`integer`	no	Graine de reproductibilité ; absente ou `-1` = au hasard.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/images/upscales" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"5641914d-89fe-45f8-b8e5-81bcb566f58e"}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Étendre le cadre

POST/api/v1/images/outpaintsScope : travaux:ecrireimage.outpaint

L'image reste entière, le cadre grandit jusqu'à la définition visée : le fournisseur mesure l'image et ne peint que du côté où le rapport visé dépasse, symétriquement, sans rogner.

Request body

Name	Type	Required	Description
`image`	`string (uuid)`	yes	L'identifiant d'une image PUBLIQUE de la médiathèque de la boutique (`GET /api/v1/media`). Jamais une adresse : le socle la résout et vérifie qu'elle vous appartient.
`width`	`integer`	yes	Largeur VISÉE : elle dit de combien étendre. [64 – 8192]
`height`	`integer`	yes	Hauteur visée. [64 – 8192]
`prompt`	`string`	no	Facultatif : ce qu'on peint dans les marges.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/images/outpaints" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"5641914d-89fe-45f8-b8e5-81bcb566f58e","width":1920,"height":1080,"prompt":"une plage au soleil"}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Retoucher localement (masque)

POST/api/v1/images/inpaintsScope : travaux:ecrireimage.inpaint

Repeint la zone masquée de l'image selon la consigne. Le masque est une image NOIR ET BLANC aux dimensions de l'image : BLANC = la zone à repeindre, noir = ce qu'on garde. La convention de chaque fournisseur (OpenAI en transparence, Ideogram inversée) est traduite par le socle.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	La consigne, en langue naturelle (3 000 signes au plus).
`image`	`string (uuid)`	yes	L'identifiant d'une image PUBLIQUE de la médiathèque de la boutique (`GET /api/v1/media`). Jamais une adresse : le socle la résout et vérifie qu'elle vous appartient.
`mask`	`string (uuid)`	yes	L'identifiant du MASQUE : une image publique de la médiathèque, noir et blanc, aux dimensions exactes de l'image. Un masque d'une autre taille est refusé avant tout paiement.
`steps`	`integer`	no	Étapes de diffusion, bornées par le modèle servi (un modèle qui n'en accepte qu'une valeur la pose lui-même). [1 – 100]
`seed`	`integer`	no	Graine de reproductibilité ; absente ou `-1` = au hasard.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/images/inpaints" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"un chapeau rouge","image":"5641914d-89fe-45f8-b8e5-81bcb566f58e","mask":"1a2b3c4d-0000-0000-0000-00000000a002"}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Vidéos

Générer une vidéo

POST/api/v1/videos/generationsScope : travaux:ecrirevideo.generate

Texte → vidéo, ou image → vidéo si `image` est donnée (l'image de départ). Le prix se calcule à la seconde chez la plupart des fournisseurs : `duration_s` fait le devis.

Les durées et cadences honorées sont celles du modèle servi ; une valeur hors bornes est ramenée à la plus proche.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	La consigne, en langue naturelle (3 000 signes au plus).
`negative_prompt`	`string`	no	Ce qu'il ne faut pas voir. Ignoré par les modèles qui ne le lisent pas.
`width`	`integer`	no	Largeur visée en pixels. Le modèle servi honore la définition la plus proche qu'il sait produire. [64 – 8192]
`height`	`integer`	no	Hauteur visée en pixels. [64 – 8192]
`duration_s`	`integer`	no	Durée demandée en secondes, bornée par le modèle servi. [1 – 60]
`fps`	`integer`	no	Images par seconde, si le modèle le lit. [1 – 60]
`image`	`string (uuid)`	no	Facultatif : l'image de DÉPART (image → vidéo).
`seed`	`integer`	no	Graine de reproductibilité ; absente ou `-1` = au hasard.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/videos/generations" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Un drone survole une plage au lever du soleil","width":1920,"height":1080,"duration_s":5}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Présentateur (lèvres synchronisées)

POST/api/v1/videos/lipsyncsScope : travaux:ecrirevideo.lipsync

Une vidéo parlante sur une VOIX (la sortie d'un travail `audio/speech`, ou un audio public) et une image du présentateur. La durée est celle de la voix, mesurée sur le fichier : c'est elle qui fait le prix.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	La consigne, en langue naturelle (3 000 signes au plus).
`audio`	`string`	yes	L'identifiant d'un audio public de la médiathèque, ou `actif:<asset_id>` (la voix qu'un travail vient de synthétiser).
`image`	`string (uuid)`	no	L'image du présentateur (facultative chez certains fournisseurs, requise chez d'autres — donnez-la).
`width`	`integer`	no	Largeur visée en pixels. Le modèle servi honore la définition la plus proche qu'il sait produire. [64 – 8192]
`height`	`integer`	no	Hauteur visée en pixels. [64 – 8192]
`seed`	`integer`	no	Graine de reproductibilité ; absente ou `-1` = au hasard.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/videos/lipsyncs" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Une personne parle face caméra, attitude naturelle","audio":"actif:74cc343e-8fed-4347-b433-11a1e8e5cf93","image":"5641914d-89fe-45f8-b8e5-81bcb566f58e","width":576,"height":1024}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Agrandir une vidéo

POST/api/v1/videos/upscalesScope : travaux:ecrirevideo.upscale

Topaz (kie, fal, MuAPI, Replicate). La durée de la vidéo est mesurée sur le fichier pour deviser à la seconde. Pas de consigne.

Request body

Name	Type	Required	Description
`video`	`string`	yes	L'identifiant d'une vidéo publique de la médiathèque, ou `actif:<asset_id>` — la sortie d'un de vos travaux.
`scale`	`integer ∈ 2 \| 4`	no	Le facteur (défaut 2).
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/videos/upscales" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video":"actif:74cc343e-8fed-4347-b433-11a1e8e5cf93","scale":2}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Retoucher une vidéo

POST/api/v1/videos/editsScope : travaux:ecrirevideo.edit

Vidéo → vidéo par consigne (Wan 2.7, Seedance 2.5, Luma, Runway Aleph, Kling Omni…). La sortie suit la source si aucune définition n'est donnée.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	La consigne, en langue naturelle (3 000 signes au plus).
`video`	`string`	yes	L'identifiant d'une vidéo publique de la médiathèque, ou `actif:<asset_id>` — la sortie d'un de vos travaux.
`negative_prompt`	`string`	no	Ce qu'il ne faut pas voir. Ignoré par les modèles qui ne le lisent pas.
`width`	`integer`	no	Largeur visée en pixels. Le modèle servi honore la définition la plus proche qu'il sait produire. [64 – 8192]
`height`	`integer`	no	Hauteur visée en pixels. [64 – 8192]
`seed`	`integer`	no	Graine de reproductibilité ; absente ou `-1` = au hasard.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/videos/edits" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"ciel orageux, ambiance dramatique","video":"actif:74cc343e-8fed-4347-b433-11a1e8e5cf93"}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Animer par mouvement

POST/api/v1/videos/motionsScope : travaux:ecrirevideo.motion

Un personnage (image) reproduit le mouvement d'une vidéo de référence (Kling motion control, Seedance 2). La durée est celle de la référence.

Request body

Name	Type	Required	Description
`image`	`string (uuid)`	yes	L'identifiant d'une image PUBLIQUE de la médiathèque de la boutique (`GET /api/v1/media`). Jamais une adresse : le socle la résout et vérifie qu'elle vous appartient.
`video`	`string`	yes	La vidéo de RÉFÉRENCE du mouvement.
`prompt`	`string`	no	Facultatif.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/videos/motions" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"5641914d-89fe-45f8-b8e5-81bcb566f58e","video":"actif:74cc343e-8fed-4347-b433-11a1e8e5cf93"}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Prolonger une vidéo

POST/api/v1/videos/extensionsScope : travaux:ecrirevideo.extend

Un nouveau segment après la dernière image, guidé par la consigne. `duration_s` est le SEGMENT AJOUTÉ (5 s par défaut), pas la durée de la source.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	La consigne, en langue naturelle (3 000 signes au plus).
`video`	`string`	yes	L'identifiant d'une vidéo publique de la médiathèque, ou `actif:<asset_id>` — la sortie d'un de vos travaux.
`duration_s`	`integer`	no	Le segment ajouté, en secondes (1 à 30 ; 5 par défaut). [1 – 30]
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/videos/extensions" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"la caméra recule lentement","video":"actif:74cc343e-8fed-4347-b433-11a1e8e5cf93","duration_s":5}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Découper une vidéo longue en clips

POST/api/v1/videos/clipsScope : travaux:ecrirevideo.clip

Une vidéo longue (un média public de la médiathèque, ou la sortie d'un travail) → N clips courts prêts pour TikTok, Reels, Shorts, avec un manifeste JSON (titres, durées, scores). OpusClip ou Vizard selon la politique. Le prix se compte à la MINUTE de vidéo source, mesurée sur le fichier — OpusClip compte 10 minutes au moins par projet.

La sortie est MULTIPLE : `outputs[]` porte chaque clip (`video/mp4`) puis un manifeste `application/json` — `{sorties: [{rang, actif_id, titre, duree_s, score, texte}]}` — dont l'ordre est celui des clips.Un travail de découpage dure de quelques minutes à une demi-heure : sondez toutes les 30 secondes.

Request body

Name	Type	Required	Description
`video`	`string`	yes	La vidéo LONGUE : l'identifiant d'une vidéo publique de la médiathèque, ou `actif:<asset_id>`. Le fournisseur la télécharge lui-même ; sa durée fait le prix.
`prompt`	`string`	no	Facultatif : ce qu'il faut chercher — des mots-clés (ClipBasic, Vizard) ou une consigne libre (ClipAnything : « les moments drôles »).
`lang`	`string`	no	La langue parlée (code court) ; détectée si absente.
`clip_min_s`	`integer`	no	Longueur minimale visée d'un clip, en secondes. [0 – 600]
`clip_max_s`	`integer`	no	Longueur maximale visée d'un clip (sans elle, le fournisseur choisit). [5 – 600]
`max_clips`	`integer`	no	Le nombre de clips au plus (les mieux notés). [1 – 100]
`width`	`integer`	no	Avec `height`, le FORMAT de sortie — 9:16 par défaut ; 16:9 et 1:1 aussi. [64 – 8192]
`height`	`integer`	no	Hauteur visée en pixels. [64 – 8192]
`subtitles`	`boolean`	no	Sous-titres incrustés (défaut `true`).
`headline`	`boolean`	no	Une accroche générée en tête de clip (défaut `false`).
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/videos/clips" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video":"actif:74cc343e-8fed-4347-b433-11a1e8e5cf93","prompt":"IA, agents","clip_max_s":60,"max_clips":10,"width":1080,"height":1920}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Rendre un gabarit

POST/api/v1/videos/rendersScope : travaux:ecrirevideo.render

Un gabarit du projet (dessiné dans l'éditeur Creatomate) et ses éléments nommés remplis → une vidéo ou une image. La liste des gabarits et de leurs éléments : `GET /api/v1/templates`. Le prix se compte en crédits (pixels × images ÷ 100 M) au tarif du forfait.

Request body

Name	Type	Required	Description
`template`	`string`	yes	Le gabarit, tel que `GET /api/v1/templates` le nomme (`template:<id>`). Il est épinglé : le rendu se fait sur celui-là.
`modifications`	`object`	yes	Les éléments nommés à remplir : `{"<nom>": <texte \| nombre \| identifiant d'un média public>}`. Un identifiant de média de la médiathèque devient son adresse publique ; les éléments non nommés gardent le contenu du gabarit. 60 éléments au plus.
`width`	`integer`	no	Avec `height`, borne la sortie (`max_width`/`max_height` chez Creatomate — le gabarit est réduit, jamais agrandi). [64 – 8192]
`height`	`integer`	no	Hauteur visée en pixels. [64 – 8192]
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/videos/renders" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"template:087d94b5-cef6-44b7-96d4-4c651beec61d","modifications":{"Titre":"Soldes d'été","Fond":"5641914d-89fe-45f8-b8e5-81bcb566f58e"}}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Audio

Synthétiser une voix

POST/api/v1/audio/speechScope : travaux:ecrireaudio.tts

Texte → voix (MP3). `voice` accepte une voix du fournisseur, ou une voix CLONÉE `clone:<fournisseur>:<id>` rendue par `audio/voices` — le routage ne garde alors que ce fournisseur.

Request body

Name	Type	Required	Description
`text`	`string`	yes	Le texte à dire (5 000 signes au plus).
`lang`	`string`	no	La langue (code court : `fr`, `en`, `pt-br`). Défaut `en`.
`voice`	`string`	no	Une voix du fournisseur (identifiant ou nom), ou `clone:<fournisseur>:<voice_id>`.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/audio/speech" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Bonjour et bienvenue chez BuzzSmile.","lang":"fr"}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Transcrire

POST/api/v1/audio/transcriptionsScope : travaux:ecrireaudio.transcribe

Audio ou vidéo → JSON horodaté (`text`, `language`, `segments: [{start, end, text}]`), rangé comme un média `application/json`. La durée du fichier est mesurée pour deviser.

Request body

Name	Type	Required	Description
`audio`	`string`	yes	Un audio OU une vidéo publique de la médiathèque, ou `actif:<asset_id>`.
`lang`	`string`	no	La langue, si vous la connaissez (sinon détectée).
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/audio/transcriptions" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio":"5641914d-89fe-45f8-b8e5-81bcb566f58e","lang":"fr"}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Composer une musique

POST/api/v1/audio/musicScope : travaux:ecrireaudio.music

Une musique depuis une description de style (`prompt`), des paroles facultatives et une durée.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	Le STYLE (3 à 300 signes chez la plupart des modèles).
`lyrics`	`string`	no	Les paroles (5 000 signes au plus). Absentes : instrumental.
`duration_s`	`integer`	no	Durée en secondes (30 par défaut). [1 – 240]
`lang`	`string`	no	La langue des paroles.
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/audio/music" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"lo-fi piano, calme, pluie","duration_s":30}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Cloner une voix

POST/api/v1/audio/voicesScope : travaux:ecrireaudio.voiceclone

Un échantillon audio (10 s à 2 min d'une seule voix, sans musique) → une voix réutilisable. La sortie est un JSON `{voice_id, fournisseur, nom, voice}` : redonnez `voice` (`clone:<fournisseur>:<id>`) à `audio/speech`. ElevenLabs : compris dans le forfait ; MiniMax : 1,5 $ la voix, effacée après 7 jours sans usage.

Request body

Name	Type	Required	Description
`audio`	`string`	yes	L'échantillon : un audio public de la médiathèque, ou `actif:<asset_id>`.
`name`	`string`	yes	Le nom de la voix chez le fournisseur (64 signes au plus).
`tier`	`string ∈ brouillon \| standard \| finition`	no	Le palier de qualité (défaut `standard`) : il choisit la politique de routage, donc les modèles candidats et le prix.
`quote_token`	`string`	no	Le jeton rendu par `POST /api/v1/quotes` pour ces mêmes réglages. Il IMPOSE le modèle et le montant annoncés : sans lui, le socle redevise et peut retenir un autre modèle de la politique.
`client_request_id`	`string`	no	Clé d'idempotence choisie par vous (64 signes au plus). Rejouer la même demande avec la même clé rend le MÊME travail, sans le facturer deux fois.
`callback_url`	`string (uri)`	no	Le webhook de fin de travail : une adresse https PUBLIQUE, que nous appelons quand le travail se termine (voir « Webhooks »). La réponse de création rend alors `callback_secret`, la clé qui signe nos appels.

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/audio/voices" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audio":"5641914d-89fe-45f8-b8e5-81bcb566f58e","name":"Voix off Richard"}'

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string (uuid)`	L'identifiant du travail — à sonder par `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	Le jeton de suivi du travail, rendu UNE FOIS, ici. Passez-le en en-tête `X-Job-Token` pour obtenir la progression et le grand livre détaillé du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	L'état à la création : `queued`.
`tokens_reserved`	`integer`	Les jetons RÉSERVÉS (le devis). Le débit final, plafonné à cette réservation, s'écrit à la fin ; un échec rend tout.
`callback_secret`	`string`	Seulement avec `callback_url` : le secret de CE travail, rendu une fois, qui signe le webhook (HMAC-SHA256). Gardez-le pour vérifier `X-BuzzSmile-Signature`.
`request_id`	`string`	L'identifiant de corrélation de l'appel, aussi dans l'en-tête `X-Correlation-Id`. À citer dans un signalement.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "job_token": "v1.…",
  "status": "queued",
  "tokens_reserved": 25,
  "request_id": "01J8…"
}

Possible errors : parametres_invalidescredits_epuisesdevis_perimecapacite_non_ouvertefonction_indisponibleaucun_candidatcontenu_refusetrop_de_demandesfournisseur_en_echec

Travaux

Lister mes travaux

GET/api/v1/jobsScope : travaux:lire

Les 50 derniers travaux du porteur de la clé, avec leur état et leurs sorties.

Request example

curl -s "https://www.buzz-smile.com/api/v1/jobs" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY"

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`jobs`	`array`	Les travaux, du plus récent au plus ancien.
`request_id`	`string`	L'identifiant de corrélation.

Response example

{
  "ok": true,
  "jobs": [
    {
      "job_id": "96adf818-…",
      "status": "succeeded",
      "capability": "image.generate",
      "tier": "standard",
      "created_at": "2026-09-17T10:12:03Z",
      "tokens_charged": 25,
      "outputs": [
        {
          "asset_id": "74cc343e-…",
          "mime": "image/png",
          "url": "/api/v1/jobs/96adf818-…/outputs/74cc343e-…"
        }
      ]
    }
  ],
  "request_id": "01J8…"
}

Suivre un travail

GET/api/v1/jobs/{job_id}Scope : travaux:lire

L'état d'un travail et ses sorties. Avec l'en-tête `X-Job-Token` (le `job_token` rendu à la création), la réponse porte aussi la progression et le grand livre du travail (réservation, libération, débit).

Sondez toutes les 2 à 5 secondes : une image arrive en quelques secondes, une vidéo en une à quelques minutes.Sans `X-Job-Token`, l'état vient de la liste de vos 50 derniers travaux.

Parameters

Name	Type	Required	Description
`job_id`	`string (uuid)`	yes	L'identifiant rendu à la création.

Request example

curl -s "https://www.buzz-smile.com/api/v1/jobs/96adf818-1804-4cc7-a2f7-f10bcfadd42b" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -H "X-Job-Token: $JOB_TOKEN"

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`job_id`	`string`	L'identifiant du travail.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	`queued` : reçu ; `running` : chez le fournisseur ; `succeeded` : sorties disponibles ; `failed` : échec, jetons rendus ; `cancelled` : annulé.
`capability`	`string`	La capacité.
`tier`	`string`	Le palier.
`created_at`	`string (date-time)`	La date de création (UTC).
`tokens_charged`	`integer`	Les jetons DÉBITÉS (0 tant que le travail n'est pas fini).
`outputs`	`array`	Les sorties, vides tant que le travail n'est pas `succeeded`. `asset_id` (string) — L'identifiant de la sortie — réutilisable comme entrée sous `actif:<asset_id>`. `mime` (string) — Le type : `image/png`, `video/mp4`, `audio/mpeg`, `application/json`… `url` (string) — Le chemin de téléchargement (`GET /api/v1/jobs/{job_id}/outputs/{asset_id}`), à appeler avec la même clé.
`progress`	`number`	Avec `X-Job-Token` seulement : 0 à 1.
`ledger`	`array`	Avec `X-Job-Token` seulement : les écritures du grand livre de ce travail (`{type, tokens, at}`).
`request_id`	`string`	L'identifiant de corrélation.

Response example

{
  "ok": true,
  "job_id": "96adf818-1804-4cc7-a2f7-f10bcfadd42b",
  "status": "succeeded",
  "capability": "image.generate",
  "tier": "standard",
  "created_at": "2026-09-17T10:12:03Z",
  "tokens_charged": 25,
  "outputs": [
    {
      "asset_id": "74cc343e-8fed-4347-b433-11a1e8e5cf93",
      "mime": "image/png",
      "url": "/api/v1/jobs/96adf818-1804-4cc7-a2f7-f10bcfadd42b/outputs/74cc343e-8fed-4347-b433-11a1e8e5cf93"
    }
  ],
  "request_id": "01J8…"
}

Possible errors : travail_inconnuacces_refuse

Télécharger une sortie

GET/api/v1/jobs/{job_id}/outputs/{asset_id}Scope : travaux:lire

Le fichier d'une sortie, tel quel (`Content-Type` = son `mime`). Privé : la même clé que le travail. Rien n'est mis en cache.

Parameters

Name	Type	Required	Description
`job_id`	`string (uuid)`	yes	Le travail.
`asset_id`	`string (uuid)`	yes	La sortie (`outputs[].asset_id`).

Request example

curl -s "https://www.buzz-smile.com/api/v1/jobs/96adf818-1804-4cc7-a2f7-f10bcfadd42b/outputs/74cc343e-8fed-4347-b433-11a1e8e5cf93" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -o sortie.bin

Response

Name	Type	Description
`(corps)`	`string (binary)`	Les octets du fichier.

Response example

{
  "(corps)": "…octets…"
}

Possible errors : travail_inconnuacces_refuse

Compte

Lire mon solde

GET/api/v1/accountScope : compte:lire

Le solde du porteur de la clé : sa bourse, plus le pot commun de la boutique où il peut puiser. 1 jeton = 0,001 $.

Request example

curl -s "https://www.buzz-smile.com/api/v1/account" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY"

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`balance_tokens`	`integer`	Ce que le porteur PEUT dépenser (bourse + pot commun accessible).
`purse_tokens`	`integer`	Sa bourse propre (peut être `null` si le grand livre ne distingue pas).
`shared_pool_tokens`	`integer`	Le pot commun de la boutique (idem).
`email`	`string`	L'adresse du porteur de la clé (`null` si le compte n'est pas relu).
`email_verified_at`	`string (date-time)`	Quand l'adresse a été vérifiée par le lien reçu par courriel ; `null` si elle ne l'a jamais été.
`request_id`	`string`	L'identifiant de corrélation.

Response example

{
  "ok": true,
  "balance_tokens": 12480,
  "purse_tokens": 480,
  "shared_pool_tokens": 12000,
  "email": "vous@exemple.fr",
  "email_verified_at": "2026-09-18T20:12:00Z",
  "request_id": "01J8…"
}

Médiathèque

Lister les médias publics

GET/api/v1/mediaScope : travaux:lire

Les médias PUBLICS de la boutique — ce que les endpoints de création acceptent comme entrée (`image`, `mask`, `audio`, `video`). Déposez-les par `POST /api/v1/media`, ou dans Médias (visibilité publique).

Parameters

Name	Type	Required	Description
`kind`	`string ∈ image \| audio \| video`	no	Filtre sur le genre (paramètre de requête `?kind=`).

Request example

curl -s "https://www.buzz-smile.com/api/v1/media" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY"

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`media`	`array`	Les médias, du plus récent au plus ancien (200 au plus). `id` (string) — L'identifiant à donner en entrée. `kind` (string) — `image`, `audio` ou `video`. `mime` (string) — Le type MIME. `name` (string) — Le nom d'origine du fichier. `url` (string) — Son adresse publique.
`request_id`	`string`	L'identifiant de corrélation.

Response example

{
  "ok": true,
  "media": [
    {
      "id": "5641914d-89fe-45f8-b8e5-81bcb566f58e",
      "kind": "image",
      "mime": "image/jpeg",
      "name": "presentatrice.jpg",
      "url": "https://www.buzz-smile.com/api/medias/5641914d-89fe-45f8-b8e5-81bcb566f58e"
    }
  ],
  "request_id": "01J8…"
}

Téléverser un média

POST/api/v1/mediaScope : travaux:ecrire

Dépose un fichier dans la médiathèque de la boutique, en visibilité PUBLIQUE — celle que les endpoints de création acceptent en entrée. Le corps est un `multipart/form-data` ; le format est reconnu par les OCTETS du fichier, jamais par son nom : PNG, JPEG, GIF, WebP, AVIF, SVG sans script, MP4, WebM, MP3, WAV, OGG, FLAC, M4A. 20 Mo au plus. Rien n'est débité.

Un `.png` qui commence par `<html>` est refusé (`parametres_invalides`), comme un SVG qui porte un script : c'est le contenu qui décide.

Request body

Name	Type	Required	Description
`file`	`string (binary)`	yes	Le fichier (champ de formulaire `file`).

Request example

curl -s -X POST "https://www.buzz-smile.com/api/v1/media" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY" \
  -F "file=@presentatrice.jpg"

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`media`	`object`	Le média déposé — mêmes champs que `GET /api/v1/media` (`id`, `kind`, `mime`, `name`, `url`) : `id` se donne aussitôt en entrée.
`request_id`	`string`	L'identifiant de corrélation.

Response example

{
  "ok": true,
  "media": {
    "id": "5641914d-89fe-45f8-b8e5-81bcb566f58e",
    "kind": "image",
    "mime": "image/jpeg",
    "name": "presentatrice.jpg",
    "url": "https://www.buzz-smile.com/api/medias/5641914d-89fe-45f8-b8e5-81bcb566f58e"
  },
  "request_id": "01J8…"
}

Possible errors : parametres_invalidesfonction_indisponible

Lister les gabarits de rendu

GET/api/v1/templatesScope : travaux:lire

Les gabarits que `POST /api/v1/videos/renders` sait rendre — ceux du projet Creatomate de la plateforme — avec leurs éléments nommés et le type attendu pour chacun (`texte`, `image`, `video`, `audio`).

Request example

curl -s "https://www.buzz-smile.com/api/v1/templates" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY"

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`templates`	`array`	Les gabarits. `template` (string) — Le nom à donner à `POST /videos/renders` (`template:<id>`). `name` (string) — Son nom dans l'éditeur. `tags` (array) — Ses étiquettes. `fields` (object) — `{<nom d'élément>: "texte" \| "image" \| "video" \| "audio"}` — ce qu'on peut remplir. `output` (string) — `video` ou `image`. `width` (integer) — Largeur du gabarit (si connue). `height` (integer) — Hauteur. `duration_s` (number) — Durée en secondes (si connue).
`request_id`	`string`	L'identifiant de corrélation.

Response example

{
  "ok": true,
  "templates": [
    {
      "template": "template:087d94b5-cef6-44b7-96d4-4c651beec61d",
      "name": "Promo verticale",
      "tags": [
        "Produit"
      ],
      "fields": {
        "Titre": "texte",
        "Fond": "video",
        "Logo": "image"
      },
      "output": "video",
      "width": 1080,
      "height": 1920,
      "duration_s": 12
    }
  ],
  "request_id": "01J8…"
}

Référence

Ce que cette installation sert

GET/api/v1/capabilitiesScope : travaux:lire

Les capacités de création et, pour chacune, si un fournisseur la sert ICI, à quels paliers — la vérité du routage à cet instant. Une capacité non servie répond `501 fonction_indisponible` à la création : demandez ici avant d'intégrer.

Request example

curl -s "https://www.buzz-smile.com/api/v1/capabilities" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY"

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`capabilities`	`array`	Une entrée par endpoint de création, dans l'ordre de cette référence. `capability` (string) — Le nom de la capacité (`image.generate`…), celui de `POST /api/v1/quotes`. `endpoint` (string) — L'endpoint de création qui la sert. `servable` (boolean) — `true` si au moins un fournisseur la sert à un palier. `tiers` (array) — Les paliers servis (`brouillon`, `standard`, `finition`) — vide si aucun. `tokens_from` (integer) — Le prix de départ en jetons (`GET /api/v1/prices`), quand le relevé en a un pour cette capacité ; absent sinon.
`request_id`	`string`	L'identifiant de corrélation.

Response example

{
  "ok": true,
  "capabilities": [
    {
      "capability": "image.generate",
      "endpoint": "/api/v1/images/generations",
      "servable": true,
      "tiers": [
        "brouillon",
        "standard",
        "finition"
      ],
      "tokens_from": 4
    },
    {
      "capability": "video.clip",
      "endpoint": "/api/v1/videos/clips",
      "servable": false,
      "tiers": []
    }
  ],
  "request_id": "01J8…"
}

Possible errors : service_en_echec

Les prix de départ

GET/api/v1/pricesScope : travaux:lire

Le prix « à partir de », en jetons, d'une demande de référence par capacité (une image 16:9 en 1024 — le premier réglage du studio, bornée par le modèle servi —, cinq secondes de vidéo, une minute de transcription…) — relevé plusieurs fois par jour par le VRAI devis, avec le fournisseur et le modèle qui le font. Un ordre de grandeur pour dimensionner une intégration ; le prix ferme d'UNE demande reste `POST /api/v1/quotes`. Sans relevé (installation qui vient de démarrer), `prices` est vide et `surveyed_at` nul : rien n'est inventé.

Request example

curl -s "https://www.buzz-smile.com/api/v1/prices" \
  -H "Authorization: Bearer $BUZZSMILE_API_KEY"

Response

Name	Type	Description
`ok`	`boolean`	`true`.
`tier`	`string`	Le palier du relevé (`standard`).
`surveyed_at`	`string`	L'instant du relevé (ISO 8601), ou `null` s'il n'y en a pas encore.
`prices`	`array`	Une entrée par capacité chiffrée ; une capacité sans prix (aucun fournisseur, entrée de référence non devisable) n'y figure pas. `capability` (string) — Le nom de la capacité (`image.generate`…). `tokens_from` (integer) — Le prix de la demande de référence, en jetons, arrondi au supérieur. `unit` (string) — Ce que la référence représente : `image`, `5s`, `8s`, `10s`, `30s`, `1min`, `30min`, `200car`, `voix`, `rendu`. `provider` (string) — Le fournisseur qui fait ce prix. `model` (string) — Son modèle.
`request_id`	`string`	L'identifiant de corrélation.

Response example

{
  "ok": true,
  "tier": "standard",
  "surveyed_at": "2026-09-18T09:07:06Z",
  "prices": [
    {
      "capability": "image.generate",
      "tokens_from": 4,
      "unit": "image",
      "provider": "deapi",
      "model": "Flux1schnell"
    },
    {
      "capability": "video.generate",
      "tokens_from": 57,
      "unit": "5s",
      "provider": "deapi",
      "model": "Ltx2_3_22B_Dist_INT8"
    }
  ],
  "request_id": "01J8…"
}

Possible errors : service_en_echec

Webhooks : la fin d'un travail

POST(votre callback_url)Public

Quand un travail créé avec `callback_url` se termine (`succeeded`, `failed`, `cancelled`), nous POSTons ce signal à votre adresse — puis vous lisez les sorties par `GET /api/v1/jobs/{job_id}`. C'est un SIGNAL, jamais un fichier. Signé : `X-BuzzSmile-Signature: sha256=HMAC-SHA256(callback_secret, "<X-BuzzSmile-Timestamp>.<corps brut>")`. Répondez 2xx ; sinon nous réessayons (1 min, 5, 15, 60, 6 h) puis abandonnons après six essais — sondez de toute façon.

En-têtes envoyés : `X-BuzzSmile-Event`, `X-BuzzSmile-Timestamp` (secondes Unix), `X-BuzzSmile-Signature`, `X-BuzzSmile-Delivery` (`<job_id>:<essai>`). Refusez un horodatage de plus de cinq minutes : c'est votre garde contre le rejeu.Votre adresse doit être https et publique : les hôtes privés, locaux ou lien-local sont refusés à la création (`parametres_invalides`, `callback_url`).

Request body

Name	Type	Required	Description
`event`	`string ∈ job.finished`	no	Le seul événement pour l'instant.
`job_id`	`string (uuid)`	no	Le travail.
`status`	`string ∈ succeeded \| failed \| cancelled`	no	L'état final.
`capability`	`string`	no	La capacité.
`tokens_charged`	`integer`	no	Les jetons débités.
`client_request_id`	`string`	no	Votre clé d'idempotence, si vous en aviez donné une.
`at`	`string (date-time)`	no	L'horodatage de l'envoi (UTC).

Request example

curl -s -X POST "https://hooks.exemple.com/buzzsmile" \
  -H "Content-Type: application/json" \
  -H "X-BuzzSmile-Event: job.finished" \
  -H "X-BuzzSmile-Timestamp: 1789590000" \
  -H "X-BuzzSmile-Signature: sha256=<HMAC-SHA256(callback_secret, "1789590000." + corps)>" \
  -H "X-BuzzSmile-Delivery: 96adf818-1804-4cc7-a2f7-f10bcfadd42b:1" \
  -d '{"event":"job.finished","job_id":"96adf818-1804-4cc7-a2f7-f10bcfadd42b","status":"succeeded","capability":"image.generate","tokens_charged":4,"client_request_id":"commande-4812-visuel-1","at":"2026-09-17T10:12:41Z"}'

Response

Name	Type	Description
`(votre réponse)`	`string`	Un statut 2xx suffit ; le corps est ignoré.

Response example

{
  "(votre réponse)": "HTTP 204"
}

Le document OpenAPI

GET/api/v1/openapi.jsonPublic

Cette référence, en OpenAPI 3.1 — à importer dans Postman, Bruno, un générateur de client. Public.

Request example

curl -s "https://www.buzz-smile.com/api/v1/openapi.json"

Response

Name	Type	Description
`(document)`	`object`	OpenAPI 3.1.0.

Response example

{
  "openapi": "3.1.0",
  "info": {
    "title": "BuzzSmile API",
    "version": "1.0.0"
  }
}

Common errors

Every refusal is `{ok: false, code}`: the code is a stable identifier, never a text.

HTTP	`code`	Meaning	What to do
401	`connexion_requise`	Clé absente, inconnue, expirée ou révoquée — le même refus dans tous les cas.	Vérifier la clé (`/api-keys`).
403	`acces_refuse`	La clé n'a pas la portée exigée, ou l'objet n'est pas à vous.	Créer une clé avec la bonne portée.
400	`parametres_invalides`	Un champ manque ou est refusé (média inconnu ou privé, masque d'une autre taille, texte trop long…).	Corriger la demande.
402	`credits_epuises`	Le solde ne couvre pas le devis.	Recharger.
403	`capacite_non_ouverte`	La capacité exige un plan que la boutique n'a pas.	Changer de plan.
404	`travail_inconnu`	Aucun travail à cet identifiant pour cette clé.	Vérifier `job_id`.
409	`devis_perime`	Le `quote_token` a expiré ou ne correspond pas à ces réglages.	Redemander un devis.
422	`contenu_refuse`	Le fournisseur a refusé le contenu (modération). Jetons rendus.	Reformuler.
429	`trop_de_demandes`	Cadence dépassée (30 créations par minute et par porteur).	Réessayer plus tard.
501	`fonction_indisponible`	Cette installation n'a aucun fournisseur pour la capacité.	Rien à faire côté client.
502	`fournisseur_en_echec`	Le fournisseur n'a pas répondu. Jetons rendus.	Réessayer.
503	`aucun_candidat`	Des modèles existent, aucun n'a pu servir cette demande (passager).	Réessayer ; changer de format ou de palier.
502	`service_en_echec`	Le socle est indisponible.	Réessayer plus tard.