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. The price, and its quote token
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. The creation, at the announced price (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. Polling every 3 seconds until status = succeeded; then the output
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

# (Optional) An input of yours — a photo to edit, a voice, a video —: its id is then given as `image`, `audio` or `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

Quotes

Request a quote

POST/api/v1/quotesScope : cout:lire

The REAL price of a request, at the provider the routing policy would pick, plan margin included — nothing reserved, nothing charged. The response carries a `quote_token`: send it back at creation so the reserved amount is exactly this one.

A quote is cached for a few minutes per settings (not per prompt): changing `width`/`height` recomputes it.A provider with observable pricing is really called: a quote is free in tokens, not in calls.

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	The capability to quote — the one of the creation endpoint you will call next.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`…`	`object`	no	The same fields as the targeted creation endpoint (`prompt`, `width`, `height`, `image`, `duration_s`…): a quote is computed on the exact settings of the request.

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`	The quoted capability.
`tier`	`string`	The quoted tier.
`tokens`	`integer`	The price in tokens (1 token = $0.001), margin included.
`model`	`string`	The model the policy would pick right now.
`provider`	`string`	The provider of that model.
`quote_token`	`string`	The quote token, to send back at creation.
`expires_in_s`	`integer`	How long the token stays valid, in seconds.
`request_id`	`string`	The correlation identifier.

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

Generate an image

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

An image from a prompt. The targeted size picks the closest one the served model can produce.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	The prompt, in natural language (3,000 characters at most).
`negative_prompt`	`string`	no	What must not appear. Ignored by models that do not read it.
`width`	`integer`	no	Targeted width in pixels. The served model honours the closest size it can produce. [64 – 8192]
`height`	`integer`	no	Targeted height in pixels. [64 – 8192]
`steps`	`integer`	no	Diffusion steps, bounded by the served model (a model that accepts a single value sets it itself). [1 – 100]
`seed`	`integer`	no	Reproducibility seed; absent or `-1` = random.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Edit an image

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

A prompt-guided edit of the whole image (Qwen Image Edit, Nano Banana, FLUX Kontext… depending on the policy).

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	The prompt, in natural language (3,000 characters at most).
`image`	`string (uuid)`	yes	The identifier of a PUBLIC image of the shop's media library (`GET /api/v1/media`). Never a URL: the platform resolves it and checks it belongs to you.
`steps`	`integer`	no	Diffusion steps, bounded by the served model (a model that accepts a single value sets it itself). [1 – 100]
`seed`	`integer`	no	Reproducibility seed; absent or `-1` = random.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Remove the background

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

Removes the background; the output is a transparent PNG. No prompt: the operation speaks for itself.

Request body

Name	Type	Required	Description
`image`	`string (uuid)`	yes	The identifier of a PUBLIC image of the shop's media library (`GET /api/v1/media`). Never a URL: the platform resolves it and checks it belongs to you.
`seed`	`integer`	no	Reproducibility seed; absent or `-1` = random.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Upscale an image

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

×4 upscaling (RealESRGAN, Topaz, Recraft… depending on the policy). No prompt.

Request body

Name	Type	Required	Description
`image`	`string (uuid)`	yes	The identifier of a PUBLIC image of the shop's media library (`GET /api/v1/media`). Never a URL: the platform resolves it and checks it belongs to you.
`seed`	`integer`	no	Reproducibility seed; absent or `-1` = random.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Extend the frame (outpaint)

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

The image stays whole and the frame grows to the targeted size: the provider measures the image and only paints on the side where the targeted ratio exceeds it, symmetrically, without cropping.

Request body

Name	Type	Required	Description
`image`	`string (uuid)`	yes	The identifier of a PUBLIC image of the shop's media library (`GET /api/v1/media`). Never a URL: the platform resolves it and checks it belongs to you.
`width`	`integer`	yes	TARGETED width: it says how far to extend. [64 – 8192]
`height`	`integer`	yes	Targeted height. [64 – 8192]
`prompt`	`string`	no	Optional: what to paint in the margins.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Edit locally (mask)

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

Repaints the masked area of the image according to the prompt. The mask is a BLACK AND WHITE image with the image's dimensions: WHITE = the area to repaint, black = what is kept. Each provider's convention (OpenAI via transparency, Ideogram inverted) is translated by the platform.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	The prompt, in natural language (3,000 characters at most).
`image`	`string (uuid)`	yes	The identifier of a PUBLIC image of the shop's media library (`GET /api/v1/media`). Never a URL: the platform resolves it and checks it belongs to you.
`mask`	`string (uuid)`	yes	The identifier of the MASK: a public image of the media library, black and white, with the exact dimensions of the image. A mask of another size is refused before any payment.
`steps`	`integer`	no	Diffusion steps, bounded by the served model (a model that accepts a single value sets it itself). [1 – 100]
`seed`	`integer`	no	Reproducibility seed; absent or `-1` = random.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Videos

Generate a video

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

Text → video, or image → video when `image` is given (the starting frame). Most providers price per second: `duration_s` drives the quote.

The durations and frame rates honoured are those of the served model; an out-of-range value is brought to the closest one.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	The prompt, in natural language (3,000 characters at most).
`negative_prompt`	`string`	no	What must not appear. Ignored by models that do not read it.
`width`	`integer`	no	Targeted width in pixels. The served model honours the closest size it can produce. [64 – 8192]
`height`	`integer`	no	Targeted height in pixels. [64 – 8192]
`duration_s`	`integer`	no	Requested duration in seconds, bounded by the served model. [1 – 60]
`fps`	`integer`	no	Frames per second, if the model reads it. [1 – 60]
`image`	`string (uuid)`	no	Optional: the STARTING image (image → video).
`seed`	`integer`	no	Reproducibility seed; absent or `-1` = random.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Presenter (lip sync)

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

A talking video from a VOICE (the output of an `audio/speech` job, or a public audio) and an image of the presenter. The duration is the voice's, measured on the file: it drives the price.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	The prompt, in natural language (3,000 characters at most).
`audio`	`string`	yes	The identifier of a public audio of the media library, or `actif:<asset_id>` (the voice a job just synthesised).
`image`	`string (uuid)`	no	The presenter's image (optional at some providers, required at others — provide it).
`width`	`integer`	no	Targeted width in pixels. The served model honours the closest size it can produce. [64 – 8192]
`height`	`integer`	no	Targeted height in pixels. [64 – 8192]
`seed`	`integer`	no	Reproducibility seed; absent or `-1` = random.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Upscale a video

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

Topaz (kie, fal, MuAPI, Replicate). The video's duration is measured on the file to quote per second. No prompt.

Request body

Name	Type	Required	Description
`video`	`string`	yes	The identifier of a public video of the media library, or `actif:<asset_id>` — the output of one of your jobs.
`scale`	`integer ∈ 2 \| 4`	no	The factor (default 2).
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Edit a video

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

Video → video by prompt (Wan 2.7, Seedance 2.5, Luma, Runway Aleph, Kling Omni…). The output follows the source when no size is given.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	The prompt, in natural language (3,000 characters at most).
`video`	`string`	yes	The identifier of a public video of the media library, or `actif:<asset_id>` — the output of one of your jobs.
`negative_prompt`	`string`	no	What must not appear. Ignored by models that do not read it.
`width`	`integer`	no	Targeted width in pixels. The served model honours the closest size it can produce. [64 – 8192]
`height`	`integer`	no	Targeted height in pixels. [64 – 8192]
`seed`	`integer`	no	Reproducibility seed; absent or `-1` = random.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Animate by motion

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

A character (image) reproduces the motion of a reference video (Kling motion control, Seedance 2). The duration is the reference's.

Request body

Name	Type	Required	Description
`image`	`string (uuid)`	yes	The identifier of a PUBLIC image of the shop's media library (`GET /api/v1/media`). Never a URL: the platform resolves it and checks it belongs to you.
`video`	`string`	yes	The REFERENCE video of the motion.
`prompt`	`string`	no	Optional.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Extend a video

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

A new segment after the last frame, guided by the prompt. `duration_s` is the ADDED SEGMENT (5 s by default), not the source's duration.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	The prompt, in natural language (3,000 characters at most).
`video`	`string`	yes	The identifier of a public video of the media library, or `actif:<asset_id>` — the output of one of your jobs.
`duration_s`	`integer`	no	The added segment, in seconds (1 to 30; 5 by default). [1 – 30]
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Cut a long video into clips

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

A long video (a public media of the library, or a job output) → N short clips ready for TikTok, Reels, Shorts, with a JSON manifest (titles, durations, scores). OpusClip or Vizard depending on the policy. The price is counted per MINUTE of source video, measured on the file — OpusClip counts at least 10 minutes per project.

The output is MULTIPLE: `outputs[]` carries each clip (`video/mp4`) then a manifest `application/json` — `{sorties: [{rang, actif_id, titre, duree_s, score, texte}]}` — in the order of the clips.A clipping job takes from a few minutes to half an hour: poll every 30 seconds.

Request body

Name	Type	Required	Description
`video`	`string`	yes	The LONG video: the identifier of a public video of the media library, or `actif:<asset_id>`. The provider downloads it itself; its duration drives the price.
`prompt`	`string`	no	Optional: what to look for — keywords (ClipBasic, Vizard) or a free prompt (ClipAnything: "the funny moments").
`lang`	`string`	no	The spoken language (short code); detected when absent.
`clip_min_s`	`integer`	no	Minimum targeted length of a clip, in seconds. [0 – 600]
`clip_max_s`	`integer`	no	Maximum targeted length of a clip (without it, the provider chooses). [5 – 600]
`max_clips`	`integer`	no	The number of clips at most (the best rated). [1 – 100]
`width`	`integer`	no	With `height`, the output FORMAT — 9:16 by default; 16:9 and 1:1 too. [64 – 8192]
`height`	`integer`	no	Targeted height in pixels. [64 – 8192]
`subtitles`	`boolean`	no	Burned-in subtitles (default `true`).
`headline`	`boolean`	no	A generated hook at the top of each clip (default `false`).
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Render a template

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

A project template (designed in the Creatomate editor) with its named elements filled in → a video or an image. The list of templates and their elements: `GET /api/v1/templates`. The price is counted in credits (pixels × frames ÷ 100 M) at the plan's rate.

Request body

Name	Type	Required	Description
`template`	`string`	yes	The template, as `GET /api/v1/templates` names it (`template:<id>`). It is pinned: the render is done on that one.
`modifications`	`object`	yes	The named elements to fill in: `{"<name>": <text \| number \| identifier of a public media>}`. A media identifier of the library becomes its public URL; elements not named keep the template's content. 60 elements at most.
`width`	`integer`	no	With `height`, bounds the output (`max_width`/`max_height` at Creatomate — the template is scaled down, never up). [64 – 8192]
`height`	`integer`	no	Targeted height in pixels. [64 – 8192]
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Synthesise a voice

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

Text → voice (MP3). `voice` accepts a provider voice, or a CLONED voice `clone:<provider>:<id>` returned by `audio/voices` — routing then keeps only that provider.

Request body

Name	Type	Required	Description
`text`	`string`	yes	The text to say (5,000 characters at most).
`lang`	`string`	no	The language (short code: `fr`, `en`, `pt-br`). Default `en`.
`voice`	`string`	no	A provider voice (identifier or name), or `clone:<provider>:<voice_id>`.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Transcribe

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

Audio or video → timestamped JSON (`text`, `language`, `segments: [{start, end, text}]`), stored as an `application/json` media. The file's duration is measured to quote.

Request body

Name	Type	Required	Description
`audio`	`string`	yes	A public audio OR video of the media library, or `actif:<asset_id>`.
`lang`	`string`	no	The language, if you know it (otherwise detected).
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Compose music

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

Music from a style description (`prompt`), optional lyrics and a duration.

Request body

Name	Type	Required	Description
`prompt`	`string`	yes	The STYLE (3 to 300 characters at most models).
`lyrics`	`string`	no	The lyrics (5,000 characters at most). Absent: instrumental.
`duration_s`	`integer`	no	Duration in seconds (30 by default). [1 – 240]
`lang`	`string`	no	The language of the lyrics.
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Clone a voice

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

An audio sample (10 s to 2 min of a single voice, no music) → a reusable voice. The output is a JSON `{voice_id, fournisseur, nom, voice}`: pass `voice` (`clone:<provider>:<id>`) back to `audio/speech`. ElevenLabs: included in the plan; MiniMax: $1.5 per voice, deleted after 7 days without use.

Request body

Name	Type	Required	Description
`audio`	`string`	yes	The sample: a public audio of the media library, or `actif:<asset_id>`.
`name`	`string`	yes	The name of the voice at the provider (64 characters at most).
`tier`	`string ∈ brouillon \| standard \| finition`	no	The quality tier (default `standard`): it picks the routing policy, hence the candidate models and the price.
`quote_token`	`string`	no	The token returned by `POST /api/v1/quotes` for these same settings. It PINS the announced model and amount: without it, the platform re-quotes and may pick another model of the policy.
`client_request_id`	`string`	no	An idempotency key of your choosing (64 characters at most). Replaying the same request with the same key returns the SAME job, without charging it twice.
`callback_url`	`string (uri)`	no	The job-completion webhook: a PUBLIC https address we call when the job finishes (see “Webhooks”). The creation response then returns `callback_secret`, the key that signs our calls.

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)`	The job identifier — to poll with `GET /api/v1/jobs/{job_id}`.
`job_token`	`string`	The job's tracking token, returned ONCE, here. Pass it in the `X-Job-Token` header to get the progress and the detailed ledger of the job.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	The status at creation: `queued`.
`tokens_reserved`	`integer`	The tokens RESERVED (the quote). The final charge, capped at this reservation, is written at the end; a failure refunds everything.
`callback_secret`	`string`	Only with `callback_url`: THIS job's secret, returned once, which signs the webhook (HMAC-SHA256). Keep it to verify `X-BuzzSmile-Signature`.
`request_id`	`string`	The correlation identifier of the call, also in the `X-Correlation-Id` header. Quote it when reporting an issue.

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

Jobs

List my jobs

GET/api/v1/jobsScope : travaux:lire

The last 50 jobs of the key holder, with their status and outputs.

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`	The jobs, newest first.
`request_id`	`string`	The correlation identifier.

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…"
}

Track a job

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

A job's status and outputs. With the `X-Job-Token` header (the `job_token` returned at creation), the response also carries the progress and the job's ledger (reservation, release, charge).

Poll every 2 to 5 seconds: an image arrives in a few seconds, a video in one to a few minutes.Without `X-Job-Token`, the status comes from the list of your last 50 jobs.

Parameters

Name	Type	Required	Description
`job_id`	`string (uuid)`	yes	The identifier returned at creation.

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`	The job identifier.
`status`	`string ∈ queued \| running \| succeeded \| failed \| cancelled`	`queued`: received; `running`: at the provider; `succeeded`: outputs available; `failed`: failure, tokens refunded; `cancelled`: cancelled.
`capability`	`string`	The capability.
`tier`	`string`	The tier.
`created_at`	`string (date-time)`	The creation date (UTC).
`tokens_charged`	`integer`	The tokens CHARGED (0 until the job is finished).
`outputs`	`array`	The outputs, empty until the job is `succeeded`. `asset_id` (string) — The output identifier — reusable as an input under `actif:<asset_id>`. `mime` (string) — The type: `image/png`, `video/mp4`, `audio/mpeg`, `application/json`… `url` (string) — The download path (`GET /api/v1/jobs/{job_id}/outputs/{asset_id}`), to call with the same key.
`progress`	`number`	With `X-Job-Token` only: 0 to 1.
`ledger`	`array`	With `X-Job-Token` only: this job's ledger entries (`{type, tokens, at}`).
`request_id`	`string`	The correlation identifier.

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

Download an output

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

The file of an output, as is (`Content-Type` = its `mime`). Private: the same key as the job. Nothing is cached.

Parameters

Name	Type	Required	Description
`job_id`	`string (uuid)`	yes	The job.
`asset_id`	`string (uuid)`	yes	The output (`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)`	The bytes of the file.

Response example

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

Possible errors : travail_inconnuacces_refuse

Account

Read my balance

GET/api/v1/accountScope : compte:lire

The balance of the key holder: their purse, plus the shop's shared pool they can draw from. 1 token = $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`	What the holder CAN spend (purse + accessible shared pool).
`purse_tokens`	`integer`	Their own purse (may be `null` if the ledger does not distinguish).
`shared_pool_tokens`	`integer`	The shop's shared pool (idem).
`email`	`string`	The key holder's email address (`null` if the account could not be read).
`email_verified_at`	`string (date-time)`	When the address was verified through the emailed link; `null` if it never was.
`request_id`	`string`	The correlation identifier.

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…"
}

Media

List the public media

GET/api/v1/mediaScope : travaux:lire

The shop's PUBLIC media — what the creation endpoints accept as input (`image`, `mask`, `audio`, `video`). Upload them with `POST /api/v1/media`, or in Media (public visibility).

Parameters

Name	Type	Required	Description
`kind`	`string ∈ image \| audio \| video`	no	Filter on the kind (query parameter `?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`	The media, newest first (200 at most). `id` (string) — The identifier to give as input. `kind` (string) — `image`, `audio` or `video`. `mime` (string) — The MIME type. `name` (string) — The original file name. `url` (string) — Its public URL.
`request_id`	`string`	The correlation identifier.

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…"
}

Upload a media

POST/api/v1/mediaScope : travaux:ecrire

Stores a file in the shop's media library, with PUBLIC visibility — the one the creation endpoints accept as input. The body is a `multipart/form-data`; the format is recognised from the file's BYTES, never from its name: PNG, JPEG, GIF, WebP, AVIF, script-free SVG, MP4, WebM, MP3, WAV, OGG, FLAC, M4A. 20 MB at most. Nothing is charged.

A `.png` that starts with `<html>` is refused (`parametres_invalides`), as is an SVG carrying a script: the content decides.

Request body

Name	Type	Required	Description
`file`	`string (binary)`	yes	The file (form field `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`	The stored media — same fields as `GET /api/v1/media` (`id`, `kind`, `mime`, `name`, `url`): `id` can be given as an input right away.
`request_id`	`string`	The correlation identifier.

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

List the render templates

GET/api/v1/templatesScope : travaux:lire

The templates `POST /api/v1/videos/renders` can render — those of the platform's Creatomate project — with their named elements and the type expected for each (`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`	The templates. `template` (string) — The name to give to `POST /videos/renders` (`template:<id>`). `name` (string) — Its name in the editor. `tags` (array) — Its tags. `fields` (object) — `{<element name>: "texte" \| "image" \| "video" \| "audio"}` — what can be filled in. `output` (string) — `video` or `image`. `width` (integer) — Template width (if known). `height` (integer) — Height. `duration_s` (number) — Duration in seconds (if known).
`request_id`	`string`	The correlation identifier.

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…"
}

Reference

What this installation serves

GET/api/v1/capabilitiesScope : travaux:lire

The creation capabilities and, for each one, whether a provider serves it HERE, at which tiers — the truth of the routing right now. A capability not served answers `501 fonction_indisponible` at creation: ask here before integrating.

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`	One entry per creation endpoint, in the order of this reference. `capability` (string) — The capability name (`image.generate`…), the one of `POST /api/v1/quotes`. `endpoint` (string) — The creation endpoint that serves it. `servable` (boolean) — `true` if at least one provider serves it at some tier. `tiers` (array) — The tiers served (`brouillon`, `standard`, `finition`) — empty if none. `tokens_from` (integer) — The starting price in tokens (`GET /api/v1/prices`), when the survey has one for this capability; absent otherwise.
`request_id`	`string`	The correlation identifier.

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

Starting prices

GET/api/v1/pricesScope : travaux:lire

The "from" price, in tokens, of a reference request per capability (a 16:9 image at 1024 — the studio's first setting, bounded by the served model —, five seconds of video, one minute of transcription…) — surveyed several times a day by the REAL quote, with the provider and model that make it. An order of magnitude to size an integration; the firm price of ONE request remains `POST /api/v1/quotes`. Without a survey (an installation that just started), `prices` is empty and `surveyed_at` is null: nothing is made up.

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`	The tier of the survey (`standard`).
`surveyed_at`	`string`	When the survey was taken (ISO 8601), or `null` if none yet.
`prices`	`array`	One entry per priced capability; a capability without a price (no provider, reference input not quotable) is not listed. `capability` (string) — The capability name (`image.generate`…). `tokens_from` (integer) — The price of the reference request, in tokens, rounded up. `unit` (string) — What the reference stands for: `image`, `5s`, `8s`, `10s`, `30s`, `1min`, `30min`, `200car`, `voix`, `rendu`. `provider` (string) — The provider that makes this price. `model` (string) — Its model.
`request_id`	`string`	The correlation identifier.

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: a job finishing

POST(votre callback_url)Public

When a job created with `callback_url` finishes (`succeeded`, `failed`, `cancelled`), we POST this signal to your address — then you read the outputs with `GET /api/v1/jobs/{job_id}`. It is a SIGNAL, never a file. Signed: `X-BuzzSmile-Signature: sha256=HMAC-SHA256(callback_secret, "<X-BuzzSmile-Timestamp>.<raw body>")`. Answer 2xx; otherwise we retry (1 min, 5, 15, 60, 6 h) then give up after six attempts — poll anyway.

Headers sent: `X-BuzzSmile-Event`, `X-BuzzSmile-Timestamp` (Unix seconds), `X-BuzzSmile-Signature`, `X-BuzzSmile-Delivery` (`<job_id>:<attempt>`). Refuse a timestamp older than five minutes: that is your guard against replay.Your address must be https and public: private, local or link-local hosts are refused at creation (`parametres_invalides`, `callback_url`).

Request body

Name	Type	Required	Description
`event`	`string ∈ job.finished`	no	The only event for now.
`job_id`	`string (uuid)`	no	The job.
`status`	`string ∈ succeeded \| failed \| cancelled`	no	The final status.
`capability`	`string`	no	The capability.
`tokens_charged`	`integer`	no	The tokens charged.
`client_request_id`	`string`	no	Your idempotency key, if you gave one.
`at`	`string (date-time)`	no	The timestamp of the delivery (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`	A 2xx status is enough; the body is ignored.

Response example

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

The OpenAPI document

GET/api/v1/openapi.jsonPublic

This reference, as OpenAPI 3.1 — to import into Postman, Bruno, a client generator. 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`	Key absent, unknown, expired or revoked — the same refusal in every case.	Check the key (`/api-keys`).
403	`acces_refuse`	The key lacks the required scope, or the object is not yours.	Create a key with the right scope.
400	`parametres_invalides`	A field is missing or refused (unknown or private media, mask of another size, text too long…).	Fix the request.
402	`credits_epuises`	The balance does not cover the quote.	Top up.
403	`capacite_non_ouverte`	The capability requires a plan the shop does not have.	Change plan.
404	`travail_inconnu`	No job with this identifier for this key.	Check `job_id`.
409	`devis_perime`	The `quote_token` has expired or does not match these settings.	Request a new quote.
422	`contenu_refuse`	The provider refused the content (moderation). Tokens refunded.	Rephrase.
429	`trop_de_demandes`	Rate exceeded (30 creations per minute and per holder).	Retry later.
501	`fonction_indisponible`	This installation has no provider for the capability.	Nothing to do on the client side.
502	`fournisseur_en_echec`	The provider did not answer. Tokens refunded.	Retry.
503	`aucun_candidat`	Models exist, none could serve this request (transient).	Retry; change the format or the tier.
502	`service_en_echec`	The platform is unavailable.	Retry later.