be-famous / docs · api reference

API reference

L'API Be-Famous est REST, JSON-only. Toutes les requêtes sont authentifiées par bearer token, retournent du JSON, et utilisent les codes HTTP standards. Une seule règle : la livraison suit une sigmoïde, jamais un spike.

Base URLhttps://api.be-famous.tech

Versionv1 (MVP)

Statut opérationnel

Authentication

Clés API

Toutes les requêtes utilisent une clé secrète préfixée bf_live_. Génère et révoque tes clés depuis la page Clés API. La partie raw n'est affichée qu'une seule fois à la création — copie-la immédiatement. Une clé révoquée invalide toute requête en cours.

Headers requis

Trois headers sont attendus sur les requêtes mutatives. Authorization porte la clé Bearer, Content-Type est obligatoire en JSON, Idempotency-Key est fortement recommandé sur POST /v1/orders pour rejouer sans dupliquer (contrainte UNIQUE par user en base).

Orders

POST/v1/orders

Créer une commande

Crée une commande de delivery. La livraison est étalée sur plusieurs jours en suivant une courbe sigmoïde décroissante — début rapide, ralentissement progressif, plateau. La durée est auto-calculée depuis le volume : clamp(ceil(18 × log10(V/100)), 6, 240) heures. Les ratios likes/comments sont tirés aléatoirement par plateforme et figés à la création. Pour des commentaires alignés sur le contenu de ton post plutôt que des réactions génériques, passe la caption ou le sujet de la vidéo dans `post_context` (optionnel, max 2200 chars). Pour TikTok, la caption et la transcription audio du clip sont en plus récupérées automatiquement et fusionnées avec ce champ. Si tu connais déjà la caption et le texte parlé de ta vidéo, passe-les dans `post_caption` et `post_transcript` : ils remplacent la récupération automatique, qui échoue sur les vidéos non publiques. La langue des commentaires se choisit via `comment_language` : fr (défaut), en ou en-gb.

Paramètres

platformstringrequired

Plateforme cible. Valeurs : tiktok, instagram, youtube, x.

post_urlstringrequired

URL du post cible. Doit être absolue (http/https) et matcher le pattern de la plateforme. Le backend revalide via regex DB — ne jamais faire confiance au front.

viewsnumberrequired

Nombre de vues à livrer. Min 3000, max 10 000 000. Au-delà, splitter en plusieurs commandes.

post_contextstringoptional

Caption ou sujet du post (max 2200 chars). Injecté dans le LLM qui génère les commentaires. TikTok : la caption et la transcription audio du clip sont récupérées automatiquement et fusionnées avec ce champ, qui sert alors à compléter ce que l'audio ne dit pas (contexte visuel, chiffres clés). Instagram : aucune récupération automatique, sans ce champ les commentaires seront génériques. Fortement recommandé.

post_captionstringoptional

Caption réelle du post (max 2200 chars), si tu la connais déjà. Elle est utilisée telle quelle et remplace la récupération automatique, qui échoue sur toute vidéo supprimée, privée ou géo-bloquée. Différent de post_context : la caption est le texte publié sous la vidéo, post_context est ton brief libre. Les deux peuvent coexister.

post_transcriptstringoptional

Transcription du contenu parlé de la vidéo (max 16000 chars), si tu la possèdes déjà. Elle remplace la transcription automatique : ni téléchargement du média, ni speech-to-text côté serveur. C'est le moyen le plus fiable d'obtenir des commentaires collés au contenu, et le seul qui fonctionne sur les vidéos non publiques. Le texte n'est pas vérifié : un transcript hors sujet dégrade tes propres commentaires.

comment_languagestringoptional

Langue de génération des commentaires. Valeurs exactes (lowercase strict) : fr (défaut), en (anglais US), en-gb (anglais britannique, spelling et argot UK). Toute autre valeur est rejetée en 422.

Exemple de réponse

200 OK

{
  "id": "8a31f6c2-d4e5-4b8a-9f1c-3d2e1f0a4b9c",
  "platform": "tiktok",
  "post_url": "https://www.tiktok.com/@user/video/7234567890",
  "comment_language": "fr",
  "views_requested": 5000,
  "likes_calculated": 175,
  "comments_calculated": 18,
  "total_cost_usd": "2.1175",
  "planned_duration_hours": 31,
  "planned_end_at": "2026-05-26T21:22:00.000Z",
  "status": "active",
  "created_at": "2026-05-25T14:22:00.000Z"
}

Erreurs possibles

401 UnauthorizedClé manquante, invalide ou révoquée.
402 Insufficient FundsSolde wallet insuffisant pour couvrir total_cost_usd.
422 Validation ErrorParamètre manquant, URL invalide, vues < 3000 ou plateforme inconnue.
409 Idempotency ReplayIdempotency-Key déjà utilisée pour ce user → la commande existante est renvoyée.

GET/v1/orders

Lister les commandes

Retourne les commandes du user, paginées par curseur (next_cursor = id de la dernière ligne). Tri descendant sur created par défaut.

Paramètres

cursorstringoptional

ID de la dernière commande de la page précédente. Vide pour la première page.

limitnumberoptional

1 à 100. Défaut 50.

statusstringoptional

Filtre par statut : pending_validation, active, completed, failed, refunded, cancelled.

Exemple de réponse

200 OK

{
  "data": [
    {
      "id": "8a31f6c2-d4e5-4b8a-9f1c-3d2e1f0a4b9c",
      "platform": "tiktok",
      "post_url": "https://www.tiktok.com/@user/video/7234567890",
      "comment_language": "fr",
      "views_requested": 5000,
      "likes_calculated": 175,
      "comments_calculated": 18,
      "total_cost_usd": "2.1175",
      "planned_duration_hours": 31,
      "planned_end_at": "2026-05-26T21:22:00.000Z",
      "status": "active",
      "created_at": "2026-05-25T14:22:00.000Z"
    }
  ],
  "next_cursor": "8a31f6c2-d4e5-4b8a-9f1c-3d2e1f0a4b9c"
}

Erreurs possibles

401 UnauthorizedClé manquante ou invalide.
422 Validation ErrorFiltre status inconnu ou limit hors bornes.

GET/v1/orders/{id}

Récupérer une commande

Renvoie l'état détaillé d'une commande, y compris la progression (views_purchased, likes_purchased, comments_purchased) et la série temporelle de delivery au provider SMM.

Paramètres

idstringrequired

UUID v4 de l'order, renvoyé à la création.

Exemple de réponse

200 OK

{
  "id": "8a31f6c2-d4e5-4b8a-9f1c-3d2e1f0a4b9c",
  "platform": "tiktok",
  "post_url": "https://www.tiktok.com/@user/video/7234567890",
  "comment_language": "fr",
  "views_requested": 5000,
  "likes_calculated": 175,
  "comments_calculated": 18,
  "total_cost_usd": "2.1175",
  "planned_duration_hours": 31,
  "planned_end_at": "2026-05-26T21:22:00.000Z",
  "status": "active",
  "created_at": "2026-05-25T14:22:00.000Z",
  "progress": {
    "views_purchased": 1875,
    "likes_purchased": 60,
    "comments_purchased": 6,
    "series": [
      { "at": "2026-05-25T14:22:00.000Z", "total_views_purchased": 125 },
      { "at": "2026-05-25T14:32:00.000Z", "total_views_purchased": 375 }
    ]
  }
}

Erreurs possibles

401 UnauthorizedClé manquante ou invalide.
404 Not FoundAucune commande avec cet id sur ce workspace (le user qui interroge n'est pas le owner).

Wallet

GET/v1/balance

Solde du wallet

Renvoie le solde courant du user en USD. Le wallet est rechargeable côté front via Liberpay (paiement crypto). Pas de rechargement disponible côté API publique au MVP.

Exemple de réponse

200 OK

{
  "balance_usd": "127.4500"
}

Erreurs possibles

401 UnauthorizedClé manquante ou invalide.

Services

GET/v1/services

Lister les services

Catalogue des plateformes activées avec le tarif en USD pour 1000 vues, ainsi que les bornes min/max de vues par commande. Seules les vues sont facturées ; les likes et commentaires on-topic sont livrés en bonus organique. Endpoint public, pas d'authentification requise.

Exemple de réponse

200 OK

{
  "platforms": [
    {
      "code": "tiktok",
      "display_name": "TikTok",
      "price_per_1k_views_usd": "0.3000",
      "price_per_1k_likes_usd": "1.2000",
      "price_per_1k_comments_usd": "8.0000",
      "min_views": 3000,
      "max_views": 1000000
    },
    {
      "code": "instagram",
      "display_name": "Instagram",
      "price_per_1k_views_usd": "0.3000",
      "price_per_1k_likes_usd": "1.5000",
      "price_per_1k_comments_usd": "9.0000",
      "min_views": 3000,
      "max_views": 1000000
    }
  ],
  "min_views": 3000
}