Programmez des publications sur les réseaux sociaux avec une API REST

La séquence complète

Pour programmer une publication via Mellow Hub, identifiez ce que la clé API est autorisée à faire, sélectionnez les canaux connectés, validez une requête, puis créez la publication avec une clé d’idempotence stable. Relisez ensuite la publication créée pour savoir ce qui s’est passé sur chaque destination. Une réponse de création réussie ne prouve pas que chaque réseau l’a publiée.

Cette recette utilise REST. Un client MCP suit la séquence équivalente whoami → list_channels → validate_post → create_post → get_post décrite dans le guide MCP pour les réseaux sociaux.

Testez la vérification des entrées avec un exemple prêt à l’emploi

Téléchargez le vérificateur d’entrées Node.js et le modèle post.example.json dans le même dossier. Le script nécessite Node.js 22 ou une version plus récente, et aucun paquet. Lisez son code source, puis fournissez une clé Hub existante dans votre environnement secret, sous le nom MELLOW_HUB_KEY.

Pour cette vérification, channels:read et posts:read suffisent. Dans les réglages d’accès de Hub, ne choisissez que les canaux que vous comptez utiliser. Lister les canaux ne demande que la première permission. Cette vérification des entrées ne nécessite ni permission de publication ni abonnement.

node mellow-hub-check.mjs --channels
# Remplacez les ID de canal et l’URL du média dans post.example.json.
node mellow-hub-check.mjs post.example.json

Le script vérifie les canaux auxquels la clé a accès, envoie votre JSON modifié à l’endpoint de validation authentifié de Mellow Hub et affiche les problèmes bloquants et les remarques. Il se termine avec le code 0 si ces vérifications des entrées réussissent, 1 en cas de problème d’entrée, ou 2 en cas d’échec lié au fichier, aux permissions, à la connexion ou à une réponse inattendue. Une réponse HTTP 200 avec ok: false fait quand même échouer la vérification.

Il ne crée aucune publication, ne récupère aucun média et n’envoie aucune requête à un réseau social. Un résultat positif ne dit rien de la durée du fichier, de son format d’image, de l’autorisation finale du compte ni de la publication. Le code téléchargeable est vérifié avec des jeux de test isolés ; il ne s’agit pas de l’enregistrement d’une vraie publication client. Pour les requêtes curl ci-dessous, enregistrez votre fichier modifié sous le nom post.json.

1. Vérifiez le compte et la clé API

Connectez vos propres canaux dans Hub et créez une clé API avec les canaux et le mode que vous comptez déléguer. Stockez-la dans l’environnement secret de votre serveur sous le nom MELLOW_HUB_KEY ; ne la placez jamais dans du JavaScript côté client ni dans un dépôt public. Les exemples lisent cette variable d’environnement sans afficher sa valeur.

curl --fail-with-body https://www.mellow.world/api/hub/v1/whoami \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

curl --fail-with-body https://www.mellow.world/api/hub/v1/channels \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

Utilisez les ID de canal renvoyés pour ce compte. Les valeurs spc_… ci-dessous sont des exemples à remplacer. Vérifiez le mode et le quota disponible avant de créer quoi que ce soit. Une clé en mode validation prépare une publication qu’une personne devra approuver. Une clé en pilote automatique peut agir dans la limite des permissions, du plafond et de la durée de validité qui lui ont été délégués.

2. Décrivez la publication réelle

Enregistrez la structure suivante sous le nom post.json. Remplacez les deux ID de canal, l’adresse du média d’exemple, le texte et la date d’exemple. Utilisez un décalage horaire ISO 8601 explicite ou Z pour UTC ; l’horodatage désigne un instant précis, pas l’heure locale du lecteur. La date de l’exemple, en 2030, n’est là qu’à titre d’illustration.

{
  "caption": "A short look at how this piece was made.",
  "channels": [
    "spc_your_instagram_channel",
    "spc_your_youtube_channel"
  ],
  "media": [
    "https://cdn.example.com/your-video.mp4"
  ],
  "scheduledAt": "2030-01-15T10:00:00Z",
  "options": {
    "instagram": {
      "placement": "reels"
    },
    "youtube": {
      "title": "How this piece was made",
      "privacyStatus": "public"
    }
  }
}

Le réseau récupère le média au moment de la publication : la vraie URL HTTPS doit donc encore être accessible à ce moment-là. Un fichier local privé ou une URL signée expirée ne fonctionnera pas. Cet exemple donne à YouTube son propre titre et sélectionne l’emplacement Reels pour Instagram. La disponibilité des formats dépend toujours de vos comptes connectés et du fournisseur.

3. Validez sans publier

curl --fail-with-body https://www.mellow.world/api/hub/v1/validate \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @post.json

Examinez les champs ok, issues et notes de la réponse. Corrigez chaque problème bloquant avant de continuer. La validation peut renvoyer HTTP 200 avec ok: false : vérifier seulement le statut HTTP ne suffit donc pas. L’endpoint authentifié vérifie que les canaux vous appartiennent réellement, en plus des règles d’entrée.

Pour un aperçu sans compte des contrôles de légende, de titre et de nombre de fichiers, utilisez le vérificateur de publications gratuit. Aucun des deux aperçus ne mesure la durée ni le format d’image de votre vrai fichier, et un fournisseur peut toujours refuser la livraison.

4. Créez une fois, relancez à l’identique

La clé de départ, en lecture seule, ne peut pas créer de publications. Avant cette étape, utilisez une connexion dotée de posts:write et posts:publish pour les canaux prévus. Ces permissions sont aussi requises en mode validation ; le mode validation laisse toujours la décision de publier à une personne. Sans elles, la requête renvoie une erreur de permission.

La requête suivante crée la publication. Ne l’exécutez que lorsque le contenu et les droits sur la destination sont corrects. En mode validation, la publication attend une approbation ; en pilote automatique, l’action déléguée peut avoir lieu à l’heure programmée.

curl --fail-with-body https://www.mellow.world/api/hub/v1/posts \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: studio-process-video-slot-001" \
  --data-binary @post.json

Conservez la clé d’idempotence avec la tâche correspondante dans votre application. Si la réponse se perd, relancez la même requête avec la même clé. Ne créez pas de nouvelle clé simplement parce que le délai d’attente a expiré. Une publication différente nécessite une clé différente ; réutiliser une clé pour un contenu modifié entraîne un refus.

5. Lisez le résultat par destination

Enregistrez le post.id renvoyé et récupérez la publication avec GET /api/hub/v1/posts/{id}, en utilisant le même en-tête d’autorisation. Examinez chaque entrée de targets et son URL publique. Une publication sur plusieurs réseaux peut être partielle : une destination peut réussir pendant qu’une autre échoue.

Gardez ensemble l’heure prévue, l’ID de publication Hub, la clé d’idempotence et les résultats par destination dans votre propre suivi de tâche. Évitez de journaliser les clés API ou les en-têtes d’autorisation complets. Quand une cible échoue, appuyez-vous sur l’erreur qu’elle signale pour décider de la suite, plutôt que de recréer aveuglément toute la publication.

Reprenez une publication restée sans réponse ou publiée en partie

Un dépassement de délai signifie que l’appelant ne connaît pas le résultat. Un résultat partial signifie que Hub a enregistré des résultats différents pour les destinations sélectionnées. Distinguez bien ces deux cas pour décider de ce qu’il faut envoyer ensuite.

La réponse de création a été perdue

Conservez la charge utile d’origine et la clé d’idempotence dans votre suivi de tâche avant la première requête. Relancez cette requête inchangée avec la même clé et des droits valides. Si Hub a déjà la publication, il renvoie son ID et son état actuel. La réponse REST reste HTTP 201 : un 201 seul ne vous dit donc pas si cette tentative a créé un nouvel enregistrement. Une fois l’ID obtenu, utilisez GET pour suivre son état.

Si vous recevez 409 idempotency_key_reused, comparez la requête avec la tâche enregistrée. Ne générez pas automatiquement une autre clé pour contourner l’erreur : une nouvelle clé décrit une nouvelle opération et pourrait dupliquer la publication d’origine.

Une destination a échoué après la publication d’une autre

Lisez targets avant de préparer une reprise. Par exemple, si Instagram est published et YouTube failed, corrigez le problème signalé pour YouTube et validez une nouvelle charge utile ne contenant que ce canal YouTube. Une reprise volontaire utilise une nouvelle clé, comme studio-process-video-slot-001-youtube-recovery-1. Conservez son nouvel ID de publication avec la tâche d’origine. Les permissions habituelles des canaux, le mode validation et le quota de publications s’appliquent toujours.

Rejouer la clé d’origine renvoie la publication existante ; cela ne relance pas ses destinations en échec. Une destination encore en attente ou en cours de publication n’est pas un échec confirmé. Ne la renvoyez pas simplement parce que l’appelant a cessé d’attendre, et n’incluez pas dans la requête de reprise les destinations déjà publiées.

Les questions qui reviennent dans les vraies intégrations

Puis-je utiliser une légende différente sur un réseau ?

Oui. Une entrée perChannel indexée par l’ID réel du canal remplace la légende ou les médias de ce canal. Les champs qui valent pour toute une plateforme vont dans options. Consultez les exemples commentés dans la référence Hub.

Un agent peut-il connecter mes comptes sociaux tout seul ?

Non. C’est le titulaire du compte qui effectue lui-même le parcours de connexion correspondant. Une clé API est une délégation pour des actions déjà autorisées, pas une permission de se faire passer pour le titulaire sur l’écran de connexion d’un réseau.

Une requête compte-t-elle pour une seule publication de mon forfait ?

Le quota est décompté par destination. Consultez les forfaits actuels et le quota restant de la clé API avant de choisir les destinations.