API

API

Appeler vos workflows depuis n8n, Make ou votre backend

Vue d’ensemble

L’API publique laisse un service externe appeler votre compte avec une clé, sans passer par l’interface. Elle sert à lancer vos workflows et à en récupérer le résultat.

URL de base

bash
https://us-central1-beemm-vision.cloudfunctions.net/publicApi

Mettez-la en configuration, pas en dur : elle changera si l’API passe derrière un domaine dédié

Les six routes

bash
GET  /v1/models

Catalogue des modèles exécutables

bash
GET  /v1/balance

Votre solde, et ce qui reste sur l’enveloppe de la clé

bash
GET  /v1/apps

Vos workflows en mode App

bash
GET  /v1/apps/{appId}

Le contrat d’une app : paramètres et sorties

bash
POST /v1/apps/{appId}/runs

Lance une app — dépense des crédits

bash
GET  /v1/runs/{runId}

État et résultat d’un run

Une clé, un secret

Affiché une seule fois, révocable à tout moment

Aucune publication

Le mode App suffit à rendre un workflow appelable

Plafond obligatoire

Chaque requête fixe ce qu’elle s’autorise à dépenser

Runs longs

Jusqu’à une heure d’exécution par run

Il n’existe pas de route de génération d’image ou de vidéo en une requête. Pour générer par l’API, mettez le modèle dans un workflow et lancez-le.

Créer une clé

  1. 1
    Ouvrez les Réglages depuis le tableau de bord, en bas à gauche. Raccourci : Cmd + , (Ctrl + , sur Windows).
  2. 2
    Groupe Développeurs → Clés API. Nommez la clé d’après son intégration : une clé par service.
  3. 3
    Choisissez les droits. Lecture pour consulter, Exécution pour lancer. Une clé déposée chez un tiers ne reçoit que le strict nécessaire.
  4. 4
    Copiez le secret : il n’est affiché qu’une seule fois. Perdu, il est perdu — il faut révoquer et recréer.

L’en-tête

bash
curl -s $BASE/v1/apps -H "Authorization: Bearer bv_live_VOTRE_SECRET"

Le même en-tête sur toutes les routes

Les trois droits

Lecture — lister vos apps, lire un résultat, consulter votre solde. Ne dépense rien.

Exécution — lancer une app. Chaque run est facturé à votre portefeuille.

Génération — réservé : aucune route ne l’utilise encore.

Créer une clé et lancer une app ne demandent aucun abonnement : il suffit d’avoir des crédits. Une clé sans crédits lit encore, mais ne lance plus.

L’enveloppe mensuelle

Vous pouvez borner ce qu’une clé consomme par mois calendaire. C’est la protection qui compte pour une clé déposée ailleurs : elle survit à une intégration qui s’emballe. La jauge de l’écran Clés API montre où en est chaque clé, et le plafond se modifie à tout moment sans avoir à remplacer la clé chez le tiers.

Rendre un workflow appelable

Il n’y a aucun geste de publication. Trois conditions, toutes dans l’éditeur de workflow.

  1. 1
    Activez le mode App dans l’éditeur du workflow, puis cliquez Configurer.
  2. 2
    Posez le rôle Entrée sur les nœuds qui deviendront des paramètres : Texte, Nombre, Seed, Interrupteur, Import, Palette, Tableau.
  3. 3
    Posez le rôle Sortie sur les nœuds dont vous voulez le résultat. La barre affiche alors « Appelable par l’API » avec l’identifiant à copier.

L’identifiant d’app

bash
proj_3d90b7:wf_8f2c1a4e

Format projet:workflow — un identifiant de workflow seul n’est pas unique

Le contrat suit le graphe

Renommer un nœud d’entrée renomme le paramètre. Chaque réponse porte donc une empreinte, contractHash : relevez-la à l’intégration et comparez-la. Elle change exactement quand ce que vous envoyez doit changer, et jamais sur un déplacement de nœud ou un changement de modèle.

Désactiver le mode App retire immédiatement l’app de l’API. Les runs passés restent lisibles.

Lancer une app

bash
curl -X POST $BASE/v1/apps/proj:wf/runs \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: commande-4821" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"prompt":"un chat"},"maxCredits":20}'

Rend 202 et un identifiant de run

Trois choses obligatoires

Idempotency-Key — un en-tête, 1 à 256 caractères. C’est lui qui garantit qu’un retry réseau ne crée pas un second run facturé. Prenez une valeur métier : numéro de commande, identifiant de tâche.

maxCredits — le plafond que ce run ne doit pas dépasser. Aucun défaut n’est appliqué : un paramètre anodin peut changer le régime tarifaire d’un nœud en aval, et vous seul savez ce que vous êtes prêt à payer.

inputs — les paramètres nommés du contrat. Un nom inconnu est refusé, jamais ignoré. Omettez-le pour lancer avec les valeurs par défaut.

Rejeu et conflit

La même clé d’idempotence avec le même corps rend 200 et le run existant, sans rien recréer ni refacturer. Avec un corps différent, elle rend 409 : prenez une clé neuve pour une requête neuve.

Le plafond, en pratique

Les crédits sont débités nœud par nœud. Si un débit ferait dépasser maxCredits, le run s’arrête avant ce débit, en erreur, avec spendCeilingRefused: true. Ce qui a déjà été produit reste lisible et facturé ; le reste n’est ni exécuté ni facturé.

Lire un résultat

bash
curl -s $BASE/v1/runs/$RUN_ID -H "Authorization: Bearer $KEY"

À interroger toutes les pollAfterSeconds secondes

Les états

queued — en file. Relisez après pollAfterSeconds.

running — en cours. La progression avance, et certaines sorties peuvent déjà être là.

success — terminé. Lisez outputs.

error — interrompu. error et failedNodeId disent où.

cancelled — annulé depuis l’application.

Ce que contient une sortie

image ou video — une url, sur le stockage Beemm Vision. Téléchargez ce que vous voulez conserver.

text — un text, coupé à 10 000 caractères.

number, boolean, json — une value.

none — rien d’exploitable n’a été produit.

Les noms de sortie sont ceux du contrat au moment du lancement, figés sur le run. Éditer le workflow ensuite ne réécrit pas l’histoire d’un run passé. Les médias produits apparaissent aussi dans Generate, comme n’importe quelle autre génération.

Limites et erreurs

Limites

60 requêtes par minute et par clé. Un dépassement rend 429 avec un en-tête Retry-After.

20 clés actives par compte, 10 créations par heure.

Enveloppe mensuelle par clé, si vous en fixez une. Le plafond demandé est comparé à ce qui reste, avant même de créer le run.

200 workflows examinés par listage. La réponse le signale dans truncated.

Erreurs fréquentes

401 invalid_key

En-tête absent ou mal formé, clé inconnue, révoquée ou expirée. Le message ne dit jamais si la clé a existé.

403 insufficient_scope

La clé n’a pas le droit exigé par la route. Un lancement demande Exécution. Les droits d’une clé ne se modifient pas : révoquez et recréez.

404 not_found sur une app

Identifiant mal formé, workflow inconnu, mode App désactivé, hors restriction de la clé, ou vous n’êtes pas éditeur du projet. Les cinq cas rendent la même réponse, à dessein.

400 max_credits_required

Le plafond est obligatoire à chaque lancement. Aucun défaut n’est appliqué.

409 idempotency_conflict

La même clé d’idempotence a déjà servi pour une requête différente. Prenez-en une neuve.

429 key_quota_exceeded

Le plafond demandé dépasse l’enveloppe mensuelle restante de la clé. Baissez maxCredits, ou relevez l’enveloppe depuis Réglages.

402 plan_required

Le portefeuille payeur ne peut rien payer : ni abonnement, ni crédits. La lecture, elle, reste ouverte.

Toutes les erreurs ont la même forme : { "error": { "code": "…", "message": "…" } }. Branchez votre logique sur code, jamais sur le message.

Ensuite

Rendre un workflow appelableLe mode App suffit.Protéger une cléDroits minimaux, enveloppe, révocation.