Documentation API

Introduction

L’API fait exactement ce que fait le site. Vous transmettez une occasion, le prénom de la personne dont parle la chanson et quelques détails concrets. Il en naît d’abord un texte complet, puis un enregistrement produit avec voix, arrangement et mixage. L’ensemble prend en général cinq à dix minutes.

Toutes les requêtes vont vers https://api.chansonminute.fr/v1. L’API ne parle que HTTPS, accepte du JSON et répond en JSON. Il n’existe aucun SDK obligatoire : n’importe quel langage capable de faire du HTTP convient. Les exemples de cette page utilisent curl, Python et Node, car ce sont les trois cas les plus fréquents.

Chaque domaine possède sa propre base API et son propre prix dans la monnaie locale. Une clé vaut pour le domaine pour lequel elle a été émise. Qui sert plusieurs marchés reçoit plusieurs clés ou une clé ouverte sur plusieurs domaines.

Accès

Il n’y a volontairement pas d’inscription automatique. Nous délivrons les clés à la main, parce que chaque chanson représente de vrais coûts de production et que nous voulons savoir à quoi sert l’intégration. En pratique, cela tient en un court message et un jour ouvré.

Écrivez à songs@maxkuch.com en indiquant quatre choses :

• Ce que vous voulez construire, en deux ou trois phrases.
• Le volume approximatif par mois.
• Dans quelles langues les chansons doivent être chantées.
• Si vous pouvez recevoir des webhooks ou si vous préférez interroger l’API.

Vous recevez deux clés : une clé de test préfixée sk_test_, gratuite, qui renvoie des enregistrements de démonstration fixes, et une clé live préfixée sk_live_. Les deux fonctionnent immédiatement, sans avoir à débloquer des points d’accès un par un.

Authentification

Chaque requête porte la clé dans l’en-tête Authorization sous forme de jeton bearer. Les requêtes sans en-tête valide reçoivent un 401 et le type d’erreur authentication_error.

curl https://api.chansonminute.fr/v1/songs \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "occasion": "birthday",
    "recipient_name": "Anna",
    "relationship": "sister",
    "language": "fr",
    "mood": "happy",
    "style": "pop",
    "voice": "female",
    "details": "Climbs every weekend, always ten minutes late, calls everyone chef.",
    "callback_url": "https://example.com/hooks/songs"
  }' 

Traitez la clé comme un mot de passe : côté serveur uniquement, jamais dans du code frontal, jamais dans un dépôt public. Si une clé s’égare, écrivez-nous : nous la bloquons aussitôt et en émettons une nouvelle. Un compte peut avoir plusieurs clés actives, le remplacement se fait donc sans interruption.

Les clés de test et live partagent les mêmes points d’accès. Le champ livemode de chaque objet indique si la requête s’est faite en mode test.

Démarrage rapide

Créer une chanson tient en un seul appel. La réponse arrive immédiatement et contient un identifiant au statut queued. Tout le reste se passe en arrière-plan.

import os, time, requests

API = "https://api.chansonminute.fr/v1"
HEAD = {"Authorization": "Bearer " + os.environ["SONG_API_KEY"]}

song = requests.post(API + "/songs", headers=HEAD, json={
    "occasion": "wedding",
    "recipient_name": "Lea and Tim",
    "relationship": "friends",
    "language": "fr",
    "mood": "romantic",
    "details": "Met at a bike repair shop, dog named Miso, both terrible dancers.",
}).json()

while song["status"] not in ("preview_ready", "complete", "failed"):
    time.sleep(5)
    song = requests.get(API + "/songs/" + song["id"], headers=HEAD).json()

print(song["lyrics"])
print(song["preview_url"])

Pour la simplicité, l’exemple interroge l’API toutes les cinq secondes. En production, les webhooks sont la meilleure voie, car ils évitent la connexion ouverte et l’attente. Les deux sont possibles, les webhooks sont décrits plus bas.

Le champ décisif est details. C’est là que vont les choses concrètes sur la personne : le surnom, la manie, les vacances qui ont mal tourné. Des phrases générales comme « c’est quelqu’un de chaleureux » donnent des vers généraux. Trois à cinq détails concrets suffisent, et ils font la différence entre une chanson agréable et une chanson qui parle vraiment de quelqu’un.

Les points d’accès en bref

Créer une chanson

POST /v1/songs reçoit le brief et démarre aussitôt. Trois champs seulement sont obligatoires, tous les autres ont des valeurs par défaut raisonnables ou sont choisis selon l’occasion.

const res = await fetch("https://api.chansonminute.fr/v1/songs", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SONG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    occasion: "anniversary",
    recipient_name: "Mara",
    relationship: "partner",
    language: "fr",
    mood: "warm",
    details: "Ten years, three apartments, one very loud coffee machine.",
    callback_url: "https://example.com/hooks/songs",
    metadata: { order_id: "A-10423" },
  }),
});

const song = await res.json();
console.log(song.id, song.status);

L’objet chanson

Tout point d’accès qui renvoie une chanson unique renvoie le même objet. Les champs qui n’existent pas encore valent null et se remplissent pendant la production.

{
  "id": "sng_3n8Kd2ZpQv",
  "object": "song",
  "status": "queued",
  "created_at": "2026-09-16T09:41:02Z",
  "occasion": "birthday",
  "recipient_name": "Anna",
  "relationship": "sister",
  "language": "fr",
  "mood": "happy",
  "style": "pop",
  "voice": "female",
  "lyrics": null,
  "preview_url": null,
  "audio_url": null,
  "duration_seconds": null,
  "paid": false,
  "price": { "amount": 2999, "currency": "EUR" },
  "metadata": {},
  "livemode": true
}

{
  "id": "sng_3n8Kd2ZpQv",
  "object": "song",
  "status": "complete",
  "created_at": "2026-09-16T09:41:02Z",
  "completed_at": "2026-09-16T09:47:35Z",
  "lyrics": "[Verse 1]\nAnna, six in the morning, chalk on your hands ...",
  "preview_url": "https://cdn.chansonminute.fr/preview/sng_3n8Kd2ZpQv.mp3",
  "audio_url": "https://cdn.chansonminute.fr/full/sng_3n8Kd2ZpQv.mp3?expires=1789412855&sig=...",
  "duration_seconds": 184,
  "paid": true,
  "price": { "amount": 2999, "currency": "EUR" },
  "metadata": { "order_id": "A-10423" },
  "livemode": true
}

Valeurs de statut

Une chanson traverse ces états dans cet ordre. Elle ne revient jamais en arrière, et complete, failed et cancelled sont des états finaux.

Une tentative de production ratée ne mène pas directement à failed. En interne, nous réessayons plusieurs fois et n’abandonnons que si toutes les tentatives échouent. failed est donc rare et signifie vraiment : cette chanson n’arrivera pas.

Récupérer et lister

GET /v1/songs/{id} renvoie l’état actuel d’une chanson. Le point d’accès est léger et supporte d’être interrogé chaque seconde, tant que vous restez dans la limite de fréquence.

curl -G https://api.chansonminute.fr/v1/songs \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -d status=complete \
  -d limit=20 \
  -d starting_after=sng_3n8Kd2ZpQv

Les listes fonctionnent par curseur. Vous recevez au plus limit entrées, 20 par défaut et 100 au maximum, les plus récentes d’abord. Si has_more est vrai, vous passez next_cursor comme starting_after à l’appel suivant. Vous pouvez filtrer sur status, occasion, language, paid ainsi que created_after et created_before.

{
  "object": "list",
  "data": [
    { "id": "sng_9Wq1LmT4bR", "status": "complete", "recipient_name": "Jonas", "...": "..." },
    { "id": "sng_3n8Kd2ZpQv", "status": "complete", "recipient_name": "Anna",  "...": "..." }
  ],
  "has_more": true,
  "next_cursor": "sng_3n8Kd2ZpQv"
}

Texte et audio

Le texte est gratuit et complet, ce n’est pas un extrait. GET /v1/songs/{id}/lyrics le renvoie en text/plain, avec les marques de couplet et de refrain. Le même texte figure dans le champ lyrics de l’objet chanson.

Pour l’audio, il y a deux niveaux. L’aperçu correspond aux 45 premières secondes de l’enregistrement terminé, ce n’est pas une démo séparée : même voix, même arrangement, même texte. Il est disponible sans paiement et le reste. Le fichier complet est fourni par GET /v1/songs/{id}/audio, seulement après déblocage.

Les deux adresses sont signées et valables 24 heures. Elles servent au téléchargement, pas au lien permanent. Si vous avez besoin d’un fichier plus longtemps, téléchargez-le une fois et conservez-le. Un nouvel appel au point d’accès fournit à tout moment une adresse fraîche.

Le format est toujours du MP3 à 320 kbit/s. Qui a besoin de WAV ajoute ?format=wav, disponible pour les comptes avec l’option studio.

Régénérer

Si un résultat ne convainc pas, la régénération ne coûte rien. POST /v1/songs/{id}/regenerate crée une nouvelle version sous le même identifiant et remet le statut à queued. La version précédente reste sous previous_versions.

curl https://api.chansonminute.fr/v1/songs/sng_3n8Kd2ZpQv/regenerate \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keep_lyrics": false,
    "reason": "voice_not_matching",
    "note": "Please try a lower male voice and a slower tempo."
  }' 

Avec keep_lyrics: true, le texte reste et seul l’enregistrement est refait. C’est la bonne voie quand le texte fonctionne et que seule la voix ou le tempo n’allait pas. Avec false, le texte est aussi réécrit.

Le champ note entre directement dans la régénération, une phrase concrète est donc payante. « Voix masculine plus grave, plus lent » fonctionne, « fais mieux » non. Trois régénérations par chanson sont gratuites, au-delà parlez-nous-en.

Paiement et déblocage

Il y a deux façons de débloquer une chanson, selon qui paie.

Le client final paie

POST /v1/songs/{id}/checkout crée chez nous une page de paiement dans la monnaie du domaine, avec les moyens de paiement usuels du pays. Vous y envoyez le client et recevez l’événement song.paid quand le paiement aboutit.

curl https://api.chansonminute.fr/v1/songs/sng_3n8Kd2ZpQv/checkout \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://example.com/thanks?song=sng_3n8Kd2ZpQv",
    "cancel_url": "https://example.com/cart"
  }' 

{
  "object": "checkout_session",
  "song": "sng_3n8Kd2ZpQv",
  "url": "https://pay.chansonminute.fr/c/cs_live_8Hd2Kq...",
  "amount": 2999,
  "currency": "EUR",
  "expires_at": "2026-09-16T11:41:02Z"
}

Vous payez

Sur les comptes à facturation groupée, POST /v1/songs/{id}/unlock débloque la chanson immédiatement et facture 29,99 € au compte. Pas de détour par une page de paiement, pratique quand vous avez votre propre caisse.

curl https://api.chansonminute.fr/v1/songs/sng_3n8Kd2ZpQv/unlock \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -X POST

Dans les deux cas, le même droit d’usage s’applique : non exclusif, mais expressément commercial. Vous pouvez transmettre, vendre et publier la chanson terminée dans le cadre de votre offre.

Valeurs valides

Les listes d’occasions, d’ambiances, de styles, de voix et de langues évoluent de temps en temps. Plutôt que de les écrire en dur, interrogez GET /v1/options et gardez la réponse en cache quelques heures.

{
  "object": "options",
  "language": "fr",
  "occasions": ["birthday", "wedding", "anniversary", "farewell", "funeral",
                "christening", "graduation", "christmas", "declaration", "other"],
  "moods":     ["happy", "warm", "funny", "romantic", "gentle", "epic", "surprise_me"],
  "styles":    ["pop", "rock", "folk", "schlager", "hiphop", "ballad", "country",
                "electronic", "jazz", "childrens", "surprise_me"],
  "voices":    ["female", "male", "duet", "choir", "childrens", "surprise_me"],
  "languages": ["de", "en", "dk", "nl", "it", "se", "fr", "es", "no", "pl", "fi", "is", "jp"]
}

Chacune de ces valeurs peut aussi être omise. La valeur surprise_me n’est pas un remplissage mais une vraie consigne : nous choisissons alors sciemment quelque chose qui colle à l’occasion et aux détails.

Webhooks

Indiquez une callback_url à la création et nous y envoyons chaque événement par POST. C’est la voie recommandée, elle évite les interrogations répétées et l’attente.

{
  "id": "evt_5Tb7Rn2WqX",
  "object": "event",
  "type": "song.completed",
  "created_at": "2026-09-16T09:47:35Z",
  "data": {
    "object": {
      "id": "sng_3n8Kd2ZpQv",
      "object": "song",
      "status": "complete",
      "audio_url": "https://cdn.chansonminute.fr/full/sng_3n8Kd2ZpQv.mp3?expires=1789412855&sig=...",
      "...": "..."
    }
  }
}

Vérifier la signature

Chaque livraison porte un en-tête avec horodatage et HMAC-SHA256 sur horodatage, point et corps brut. Vérifiez-le avant de faire confiance au contenu et rejetez tout ce qui a plus de cinq minutes.

X-Song-Signature: t=1789412855,v1=7f2c1d9a4b6e8035c1f7a29d4e5b0c8371a6d2f94e8b3c07a15d9e2f6b4c8a01

import hashlib, hmac, os, time
from flask import Flask, request, abort

SECRET = os.environ["SONG_WEBHOOK_SECRET"].encode()
app = Flask(__name__)


@app.post("/hooks/songs")
def hook():
    header = request.headers.get("X-Song-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    timestamp, signature = parts.get("t", ""), parts.get("v1", "")

    if abs(time.time() - int(timestamp or 0)) > 300:
        abort(400)  # older than five minutes, treat as replay

    expected = hmac.new(
        SECRET, (timestamp + "." + request.get_data(as_text=True)).encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        abort(400)

    event = request.get_json()
    if event["type"] == "song.completed":
        store(event["data"]["object"])

    return "", 200

Répétitions

Nous attendons une réponse 2xx dans les dix secondes. Si elle n’arrive pas, nous réessayons huit fois sur 24 heures avec des intervalles croissants. Les livraisons peuvent donc se répéter et, rarement, arriver dans le désordre : rendez votre point d’accès idempotent et fiez-vous à created_at, pas à l’heure d’arrivée.

Idempotence

Chaque POST accepte l’en-tête Idempotency-Key avec une valeur unique quelconque, le plus souvent un UUID. Si la même clé revient dans les 24 heures, nous renvoyons la réponse d’origine au lieu de créer une deuxième chanson.

curl https://api.chansonminute.fr/v1/songs \
  -H "Authorization: Bearer $SONG_API_KEY" \
  -H "Idempotency-Key: 9f1c7c2e-0a3b-4c8d-9e21-5f7a1b6c3d40" \
  -H "Content-Type: application/json" \
  -d '{ "occasion": "birthday", "recipient_name": "Anna", "language": "fr", "details": "..." }' 

C’est exactement la protection dont on a besoin contre les erreurs réseau : si une réponse se perd et que votre code répète la requête, il ne naît quand même qu’une seule chanson. Si vous envoyez la même clé avec un corps différent, nous répondons 409 avec le type d’erreur conflict.

Erreurs

Les erreurs arrivent toujours sous la même forme, avec un type et un code lisibles par la machine, un message lisible et, le cas échéant, le champ concerné. Joignez la request_id à toute demande de support, nous retrouvons ainsi l’appel dans les journaux.

{
  "error": {
    "type": "validation_error",
    "code": "details_too_short",
    "message": "details must contain at least 40 characters so the song has something to work with",
    "param": "details",
    "request_id": "req_2Lm9Xc4Kd1"
  }
}

Pour un 429 et les 5xx, réessayer a du sens, de préférence avec des intervalles exponentiels et un peu de hasard. Pour un 4xx autre que 429, non : la même requête échouera de nouveau.

Limites

Chaque réponse porte l’état actuel dans ses en-têtes, vous n’avez donc pas à deviner.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1789412880
X-Concurrent-Limit: 10
X-Concurrent-Running: 3

Des limites plus élevées ne posent pas de problème, ce n’est simplement pas le réglage de départ. Si le volume grandit, écrivez-nous deux lignes et nous les relevons.

Versionnement

La version majeure figure dans le chemin et reste stable. À l’intérieur de v1, seules des modifications additives arrivent : nouveaux champs, nouvelles valeurs dans les listes, nouveaux points d’accès. Les champs existants ne disparaissent pas et ne changent pas de sens.

Pour plus de sûreté, vous pouvez fixer une date dans un en-tête. Sans en-tête, c’est toujours le comportement le plus récent qui s’applique.

X-Song-Version: 2026-09-01

Votre code devrait ignorer les champs inconnus dans les réponses plutôt que de casser. C’est la seule hypothèse que nous faisons sur les clients.

Mode test

Les clés préfixées sk_test_ passent exactement par les mêmes points d’accès, mais ne lancent aucune production réelle et ne coûtent rien. Après quelques secondes, vous recevez un texte de démonstration fixe et un enregistrement de démonstration, et chaque objet porte livemode: false.

Cela permet aussi d’éprouver les cas désagréables. Certains prénoms dans le champ recipient_name forcent une issue précise : test_fail mène à failed, test_slow à une production d’environ dix minutes, test_ratelimit à une réponse 429. Vous pouvez donc tester votre gestion des erreurs sans attendre une vraie panne.

Les webhooks fonctionnent aussi en mode test, avec le même mécanisme de signature et un secret dédié.

Droits et données

Avec le déblocage, vous obtenez un droit d’usage non exclusif mais expressément commercial sur la chanson terminée. Vous pouvez la transmettre, la vendre, l’exécuter en public et l’intégrer à votre produit. Non exclusif signifie que nous conservons le droit d’utiliser nous-mêmes l’enregistrement, par exemple comme exemple.

Sur le droit d’auteur de la musique créée par intelligence artificielle, beaucoup d’ordres juridiques n’ont pas encore de réponse définitive. Nous vous garantissons l’usage par contrat, mais ne pouvons pas assurer qu’un droit d’auteur propre naisse sur l’enregistrement et tienne face à des tiers. Qui en dépend devrait faire vérifier la question en amont.

Nous conservons les données saisies et les chansons terminées 90 jours, ensuite elles sont supprimées. Pour supprimer une chanson plus tôt, il y a DELETE /v1/songs/{id}. Les informations de details ne servent qu’à produire cette chanson et jamais à entraîner nos propres modèles.

Si vous nous transmettez les données de vos clients, vous êtes responsable du traitement et nous sous-traitant. Un accord de sous-traitance est disponible sur demande.

Assistance

Questions, limites plus élevées, accord de sous-traitance, cas particuliers : songs@maxkuch.com. Pour les problèmes techniques, indiquez la request_id de la réponse d’erreur, nous retrouvons l’appel immédiatement.

Pour les intégrations via des agents d’intelligence artificielle, il existe aussi un serveur Model Context Protocol, documenté sur /mcp/, qui utilise les mêmes clés que l’API REST.