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

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

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) — le générateur LLM s'en sert pour produire du texte qui colle au sujet. 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 : sans ce champ, le LLM ne voit que l'URL et produit des réactions génériques ; avec, les commentaires collent au contenu réel. Optionnel mais fortement recommandé pour la qualité des comments.
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
}
be-famousv1.0
© 2026 · Spec MVP, sujet à évolution