La session d'upload résumable Instagram et l'hôte rupload

Qu'est-ce qu'un upload résumable Instagram ?

Meta l'appelle un upload résumable Instagram, et c'est un flux à deux hôtes : POST /<IG_ID>/media avec upload_type=resumable crée le conteneur sur graph.facebook.com et vous rend une cible d'envoi, puis les octets partent vers rupload.facebook.com dans une seconde requête que vous pilotez.

Le comportement par défaut est l'arrangement inverse. Dans un envoi standard, vous passez video_url et Meta va chercher le fichier chez vous : « We will cURL your image using the passed in URL so it must be on a public server. » Votre serveur répond à une requête du crawler de Meta, et le transfert réussit ou échoue quelque part où vous ne voyez rien. Le mode résumable inverse cela. Vous ouvrez la connexion, vous envoyez les octets, et vous obtenez une réponse à leur sujet.

La raison d'être du flux selon Meta apparaît dans la liste d'endpoints du guide Content Publishing, coquille comprise : « upload_type=resumable Create a resumbable upload session to upload large videos from an area with frequent network interruptions or other transmission failures. »

Le paramètre lui-même est documenté comme optionnel et sensible à la casse sur la référence média : « An optional parameter for users want to upload video through the rupload protocol, values can be set to lowercase string value: resumable. » La minuscule compte. RESUMABLE n'est pas une valeur documentée.

Qu'envoie chaque étape du flux ?

Quatre étapes, deux hôtes, et un schéma d'autorisation différent sur chacun.

L'étape un diffère d'une création de conteneur standard par ce qu'elle omet. Il n'y a pas de video_url, parce qu'il n'y a rien à aller chercher pour Meta. Une session de Reel donne la forme complète :

POST https://graph.facebook.com/v25.0/<YOUR_APP_USERS_INSTAGRAM_USER_ID>/media
  ?media_type=REELS
  &upload_type=resumable
  &caption=<IMAGE_CAPTION>
  &collaborators=<COLLABORATOR_USERNAMES>
  &cover_url=<COVER_URL>
  &audio_name=<AUDIO_NAME>
  &location_id=<LOCATION_PAGE_ID>
  &thumb_offset=<THUMB_OFFSET>
  &access_token=<USER_ACCESS_TOKEN>

La réponse porte un second champ qu'un conteneur standard ne renvoie pas :

{
  "id": "<IG_CONTAINER_ID>",
  "uri": "https://rupload.facebook.com/ig-api-upload/v25.0/<IG_CONTAINER_ID>"
}

Utilisez l'uri que Meta vous donne plutôt que d'assembler le chemin vous-même. L'étape deux y poste ensuite le fichier :

curl -X POST "https://rupload.facebook.com/ig-api-upload/v25.0/<IG_CONTAINER_ID>" \
  -H "Authorization: OAuth <USER_ACCESS_TOKEN>" \
  -H "offset: 0" \
  -H "file_size: Your_file_size_in_bytes" \
  --data-binary "@Your_local_file_path.extension"

Meta documente les deux en-têtes numériques en une ligne chacun. « offset is set to the first byte being upload, generally 0. » « file_size is set to the size of your file in bytes. » Un fichier déjà hébergé saute entièrement le corps et déplace la source dans un troisième en-tête :

curl -X POST "https://rupload.facebook.com/ig-api-upload/v25.0/<IG_CONTAINER_ID>" \
  -H "Authorization: OAuth <USER_ACCESS_TOKEN>" \
  -H "file_url: <VIDEO_URL>"

Le succès tient en deux champs : {"success":true,"message":"Upload successful."}.

Pourquoi l'en-tête d'autorisation diffère-t-il sur rupload ?

Parce que Meta l'écrit différemment sur chaque hôte, et que les exemples sont côte à côte sur la même page. Les appels à graph.facebook.com dans le guide Content Publishing utilisent -H "Authorization: Bearer <ACCESS_TOKEN>". Chaque appel à rupload.facebook.com sur cette même page utilise -H "Authorization: OAuth <ACCESS_TOKEN>".

Même token, nom de schéma différent. Meta ne donne aucune explication, et les exemples rupload ne montrent jamais Bearer. Recopiez le schéma de l'exemple qui correspond à l'hôte que vous appelez.

Deux autres détails se perdent facilement dans les blocs de code. Le curl publié par Meta pour l'étape rupload contient un backtick parasite dans l'URL, entre l'emplacement de l'identifiant de conteneur et le guillemet fermant. C'est une coquille dans la doc, pas un élément de syntaxe. Et la liste de paramètres du guide Content Publishing pour l'étape d'envoi s'arrête au milieu d'une phrase : elle annonce « the following parameters », imprime access_token, puis se termine sur une puce vide. La liste complète des en-têtes n'existe que sur la référence de l'endpoint média, pas dans le guide.

Quand le mode résumable est-il obligatoire plutôt qu'optionnel ?

Meta ne publie jamais de taille de fichier qui le rende obligatoire, et la réponse honnête est que la seule exigence ferme porte sur votre flux de connexion, pas sur votre fichier.

Le guide Content Publishing restreint tout le flux en une clause : upload_type=resumable est « Only for apps that have implemented Facebook Login for Business. » Le tableau des prérequis sur la même page le confirme en listant les URL d'hôtes par type de connexion. Instagram API with Instagram Login obtient graph.instagram.com. Instagram API with Facebook Login obtient graph.facebook.com et rupload.facebook.com, annoté « (For resumable video uploads). »

Une app bâtie sur Business Login for Instagram ne peut donc pas utiliser le mode résumable du tout. La vidéo doit arriver par video_url et la récupération de Meta. C'est une décision d'architecture de connexion prise bien avant que quiconque envoie un fichier, et elle n'est pas réversible requête par requête.

Là où le mode résumable est disponible, les indications de Meta sont qualitatives plutôt que chiffrées. Le déclencheur est « large videos from an area with frequent network interruptions or other transmission failures », sans aucun seuil en octets. Les seuls chiffres liés que Meta publie sont les plafonds de spécification : les Reels plafonnent à 300 Mo et 15 minutes, les Stories à 100 Mo et 60 secondes. Aucun des deux n'est décrit comme un seuil de bascule vers le mode résumable.

Lecture pratique : utilisez le mode résumable dès que votre fichier source est local plutôt que déjà posé sur un CDN, parce que l'alternative vous oblige à héberger le fichier publiquement pendant toute la récupération de Meta. Cela compte surtout pour tout ce qui est long, et c'est là que l'envoi de vidéo longue sur Instagram devient pénible et que les durées de Reels que Meta teste font grimper la taille des fichiers.

Comment reprendre concrètement un envoi interrompu ?

Meta ne le documente pas. C'est le plus gros trou de la fonctionnalité, et il se trouve juste sous le nom de celle-ci.

L'en-tête offset est le seul mécanisme qui évoque des transferts partiels, et les deux endroits où Meta le décrit pointent vers la même valeur : « offset is set to the first byte being upload, generally 0. » Il n'y a aucune taille de morceau documentée, aucun endpoint qui indique combien d'octets le serveur détient déjà, aucune seconde forme de requête pour poursuivre un transfert interrompu, et aucun exemple dans toute la documentation d'Instagram Platform qui passe un offset non nul. Une session d'envoi « résumable », telle que publiée, est un POST unique du fichier entier avec un champ d'offset toujours à zéro dans les exemples.

Ce que Meta vous donne, en revanche, c'est un conteneur qui survit à un échec assez longtemps pour recommencer depuis le début. Les conteneurs expirent après 24 heures, et un compte peut en créer 400 sur une période glissante de 24 heures. Un transfert d'octets raté coûte un conteneur sur ces 400, pas une publication sur votre quota quotidien, donc recommencer est bon marché dans le budget qui compte. Tout ce qui est mis en file à l'avance doit respecter les mêmes plafonds, ce qui explique pourquoi les posts Instagram planifiés échouent plus souvent à l'étape du conteneur qu'à celle de la publication.

À quoi ressemble un envoi en échec ?

Un échec sur l'hôte rupload ne revient pas sous la forme d'un objet d'erreur Graph API standard. Il revient dans une enveloppe debug_info avec la vraie erreur sérialisée en chaîne à l'intérieur :

{
  "debug_info": {
    "retriable": false,
    "type": "ProcessingFailedError",
    "message": "{\"success\":false,\"error\":{\"message\":\"unauthorized user request\"}}"
  }
}

Analysez retriable en premier. C'est le champ qui vous dit si une nouvelle tentative vaut le conteneur. false signifie que le transfert échouera de la même façon, et l'exemple choisi par Meta, une requête utilisateur non autorisée, est exactement ce genre d'échec.

Les échecs qui remontent plus tard, côté Graph API, utilisent les couples code et sous-code habituels.

Meta rattache 2207053 spécifiquement à ce flux : « An unknown error occured during upload. Generate a new container and use it to try again. This should only affect video uploads. »

Quelles erreurs apparaissent après un envoi réussi ?

Celles qui viennent du traitement, et vous ne les voyez qu'en interrogeant le conteneur. Meta est explicite sur le fait qu'un identifiant de conteneur ne prouve rien : « Video uploads are asynchronous, so receiving a container ID does not guarantee that the upload was successful. »

GET /<IG_CONTAINER_ID>?fields=status_code renvoie l'une de cinq valeurs.

Seul FINISHED est sûr à publier. Demander le champ status à côté de status_code vaut le paramètre supplémentaire, parce que Meta le définit comme la ligne de détail : « If status_code is ERROR, this value will be an error subcode. »

Meta plafonne ses conseils d'interrogation à une cadence précise : « We recommend querying a container's status once per minute, for no more than 5 minutes. » Un Reel long peut encore être en traitement après ce délai, et Meta ne dit pas quoi faire ensuite. Le schéma qui fonctionne consiste à continuer d'interroger à un rythme plus lent jusqu'à ce que le conteneur finisse ou atteigne l'expiration à 24 heures, ce qui est aussi la façon dont la planification de Reels via l'API doit être construite et dont les conteneurs de Stories se comportent sur leur propre horloge de 24 heures.

Questions fréquentes

Que fait upload_type=resumable sur l'API Instagram ?

Il crée un conteneur qui attend que vous poussiez vous-même la vidéo vers rupload.facebook.com, au lieu de laisser Meta aller la chercher sur un video_url que vous hébergez. La réponse inclut à la fois un id et une uri pointant vers l'hôte d'envoi.

Quel hôte gère les uploads résumables Instagram ?

rupload.facebook.com, au chemin /ig-api-upload/<API_VERSION>/<IG_CONTAINER_ID>. La création du conteneur, les vérifications de statut et la publication restent toutes sur graph.facebook.com.

De quels en-têtes la requête rupload a-t-elle besoin ?

Authorization: OAuth <ACCESS_TOKEN> plus soit offset et file_size pour un fichier local, soit file_url pour un fichier déjà hébergé publiquement. Notez que les exemples rupload utilisent OAuth là où les exemples Graph API utilisent Bearer.

Les apps qui utilisent Instagram Login peuvent-elles faire des uploads résumables ?

Non. Meta réserve upload_type=resumable aux apps qui ont implémenté Facebook Login for Business, et ne liste rupload.facebook.com que sous ce type de connexion.

À partir de quelle taille de fichier Instagram exige-t-il un upload résumable ?

Meta ne publie aucun seuil de ce genre. Le guide recommande le mode résumable pour « large videos from an area with frequent network interruptions » sans nommer de taille, et documente le paramètre lui-même comme optionnel.

Comment reprendre un envoi Instagram interrompu ?

Meta ne documente aucune procédure de reprise. L'en-tête offset existe mais chaque exemple publié le met à 0, et aucun endpoint n'indique combien d'octets le serveur a déjà reçus. Créez un nouveau conteneur et recommencez.

Combien de temps un conteneur d'upload Instagram reste-t-il valide ?

Un conteneur expire 24 heures après sa création, qu'il ait été publié ou non. Si cette fenêtre est dépassée, Meta renvoie le code -2, sous-code 2207020, avec le message indiquant que le média a expiré et qu'il faut retenter l'envoi. Le champ status_code signale la même chose avec la valeur EXPIRED.

À quelle fréquence faut-il vérifier le statut d'un conteneur Instagram ?

Meta limite sa propre recommandation à une vérification par minute, pendant 5 minutes maximum. Un reel long peut encore afficher IN_PROGRESS passé ce délai, et Meta ne documente pas la marche à suivre ensuite. En pratique, on continue à vérifier à un rythme plus espacé jusqu'à ce que le conteneur atteigne FINISHED ou dépasse les 24 heures d'expiration.

Que signifie le champ retriable dans une erreur rupload ?

C'est le premier champ à consulter dans l'enveloppe debug_info que renvoie rupload en cas d'échec. Une valeur false signifie que la requête échouera de la même façon si elle est renvoyée, comme dans l'exemple donné par Meta d'une requête utilisateur non autorisée. Vérifier retriable avant de réessayer évite de dépenser un autre conteneur sur une requête qui ne peut pas aboutir.

L'id d'un conteneur signifie-t-il que l'envoi Instagram a réussi ?

L'id d'un conteneur, à lui seul, ne prouve rien. Meta précise que les envois vidéo sont asynchrones, donc recevoir un id de conteneur ne garantit pas que l'envoi s'est bien passé. La seule façon de le savoir est d'interroger le conteneur avec GET /<IG_CONTAINER_ID>?fields=status_code et d'attendre le statut FINISHED avant de publier.