Spécification complète de l’API vidéo

Cette page décrit la spécification unifiée de génération vidéo que 88API met à la disposition de ses clients. Elle s’applique à tous les modèles vidéo proposés par 88API. Il vous suffit de récupérer l’ID model dans la liste des modèles visibles par votre clé API, puis d’utiliser l’API unifiée décrite ici.

Toutes les tâches vidéo suivent le même protocole : « découverte du modèle → création → interrogation → téléchargement ». Les ID de modèles visibles peuvent varier d’un compte à l’autre, de même que les durées, formats d’image, résolutions et nombres de médias de référence pris en charge. N’appliquez jamais les capacités d’un modèle à un autre.

Mis à jour le 2026-10-10. Les paramètres et exemples propres à chaque marque figurent désormais sur des pages dédiées : voir Spécifications par marque ci-dessous. Flux recommandé : appelez d’abord GET /v1/models pour obtenir les ID de modèles disponibles pour votre clé ; référencez directement un média HTTPS déjà accessible ; pour un fichier local, téléversez-le d’abord → créez la génération → interrogez la tâche pour obtenir l’URL du résultat → lisez-la, téléchargez-la ou réutilisez-la comme référence pour la génération suivante. Un téléversement réussi ne garantit pas que le modèle accepte ce type de média : les capacités du modèle et celles du stockage sont deux choses distinctes.

Règle d’intégration unifiée : renseignez model avec l’id exact renvoyé par GET /v1/models, créez la tâche avec POST /v1/videos, conservez l’id de la réponse et interrogez GET /v1/videos/{id}. Pour toute nouvelle intégration, n’utilisez pas l’ancien /v1/video/generations, ne dépendez pas de task_id et ne considérez pas callback_url comme une fonctionnalité prise en charge par tous les modèles. Si vous avez besoin d’une compatibilité stable, utilisez systématiquement l’interrogation (polling).

1. Règles minimales d’intégration unifiée

Si un même client doit s’intégrer à plusieurs modèles vidéo, il suffit de figer le flux suivant :

1. Appelez GET /v1/models avec la clé API en cours.
2. Choisissez dans la réponse un id de modèle auquel le client a réellement accès. Ne codez pas en dur dans une configuration globale un nom affiché dans la place de marché des modèles, un ancien nom ou un nom visible sur un autre compte.
3. Créez les tâches avec le même format de requête POST /v1/videos.
4. Interrogez les tâches uniquement avec l’id public renvoyé dans la réponse. N’analysez et ne construisez aucun autre ID de tâche.
5. Récupérez la vidéo via url, video_url ou result_url dans la réponse de fin de tâche.

Champs communs recommandés :

Ce tableau correspond à l’écriture commune à la plupart des modèles. Certaines marques utilisent d’autres champs (par exemple, chez Wan, le tableau media est recommandé pour les images de début et de fin et les références, et un champ de média illisible renvoie 400) : reportez-vous aux spécifications par marque.

size est un champ de compatibilité utilisé par certains modèles et d’anciens clients. Les nouveaux clients doivent privilégier ratio ou aspect_ratio et choisir la valeur selon les capacités documentées du modèle cible.

Dans les exemples qui suivent, <MODEL_ID> désigne l’ID de modèle réel obtenu via /v1/models selon les étapes ci-dessus ; il ne s’agit pas d’une chaîne fixe que tous les clients devraient utiliser.

2. Référence rapide des points de terminaison

En-têtes de requête

Authorization: Bearer sk-votre-clé-API
Content-Type: application/json
Accept: application/json

La clé API doit rester côté serveur. Ne l’intégrez jamais dans le code front-end d’un navigateur, d’une mini-application ou d’une application mobile.

Une lecture anonyme n’implique ni un téléversement anonyme, ni l’accès aux détails de la tâche. Toute personne qui détient l’URL d’un média public peut lire le fichier pendant sa durée de validité : ne considérez pas l’URL comme un mécanisme strict de confidentialité. Ne transmettez jamais votre clé API aux URL de médias, aux URL de résultats officielles ni aux destinations de redirection.

Obtenir d’abord les ID de modèles disponibles pour votre compte

Les ID de modèles ne sont pas identiques pour tous les comptes. Lors de la première intégration ou du rafraîchissement périodique de la liste des modèles, exécutez d’abord :

curl 'https://api.88api.ai/v1/models' \
  --header 'Authorization: Bearer sk-xxxx'

Choisissez un modèle dans data[].id et reportez cette valeur telle quelle dans le champ model des requêtes POST /v1/videos suivantes. Ne reconstituez pas l’ID à partir du nom affiché du modèle et ne supposez pas qu’un nom de modèle vu sur un autre compte ou dans une ancienne documentation est forcément disponible pour votre compte.

{
  "object": "list",
  "data": [
    {
      "id": "<MODEL_ID>",
      "object": "model",
      "owned_by": "88api"
    }
  ]
}

3. Requête de création standard

Requête minimale de texte vers vidéo

curl --request POST 'https://api.88api.ai/v1/videos' \
  --header 'Authorization: Bearer sk-xxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "<MODEL_ID>",
    "prompt": "Voiture de sport argentée dans une ville pluvieuse la nuit, travelling en contre-plongée, reflets de néons, rendu cinématographique",
    "duration": 8,
    "ratio": "16:9"
  }'

Vous pouvez aussi exprimer duration sous forme de chaîne avec seconds :

{
  "model": "<MODEL_ID>",
  "prompt": "Vue aérienne d’une côte au lever du soleil, nuages qui défilent lentement",
  "seconds": "8",
  "ratio": "16:9"
}

Champs de requête communs

Choisir la résolution

L’API de création est la même pour tous, mais la façon de choisir la résolution peut varier selon le modèle. Basez-vous d’abord sur l’ID de modèle renvoyé par GET /v1/models et sur la description des capacités du modèle.

Modèles à résolution fixe : choisir la résolution par l’ID de modèle

Certains modèles fixent la résolution de sortie dans leur nom ou leur ID. Récupérez d’abord via GET /v1/models les ID réellement disponibles pour votre compte, puis choisissez directement le modèle correspondant à la résolution voulue :

{
  "model": "<FIXED_RESOLUTION_MODEL_ID>",
  "prompt": "Une voiture traverse lentement une rue dans un paysage urbain nocturne",
  "duration": 8,
  "ratio": "16:9"
}

Pour un modèle à résolution fixe, resolution ne permet pas de modifier ponctuellement la résolution de sortie. Même si le client envoie resolution, ne vous en servez pas pour outrepasser les capacités du modèle.

Modèles à résolution variable : utiliser le champ resolution

Lorsqu’un modèle prend en charge plusieurs résolutions, indiquez resolution en minuscules dans la requête :

{
  "model": "<MULTI_RESOLUTION_MODEL_ID>",
  "prompt": "Une voiture traverse lentement une rue dans un paysage urbain nocturne",
  "duration": 8,
  "resolution": "720p",
  "ratio": "16:9"
}

Les résolutions et valeurs réellement disponibles restent déterminées par /v1/models pour la clé API en cours, par la description du modèle et par la validation côté serveur. Un client qui doit gérer plusieurs modèles peut conserver le champ resolution : les modèles qui le prennent en charge l’utilisent pour choisir la résolution de sortie, tandis que les modèles à résolution fixe s’en tiennent à model. N’utilisez pas quality ou vquality et ne modifiez pas le nom du modèle pour contourner ses limites ; une combinaison non prise en charge renvoie 400.

4. Images, vidéos et audios de référence

3.1 Images de référence

Plusieurs images se transmettent toujours dans le tableau images au niveau racine :

{
  "model": "<MODEL_ID>",
  "prompt": "Garder le visage, la tenue et les couleurs du personnage cohérents, marche lente au bord de la mer, lumière douce de cinéma",
  "duration": 10,
  "ratio": "16:9",
  "images": [
    "https://cdn.example.com/character-front.jpg",
    "https://cdn.example.com/character-side.jpg"
  ]
}

Pour une seule image, image ou input_reference sont également acceptés, mais nous recommandons d’utiliser systématiquement le tableau images dans les nouvelles intégrations.

3.2 Vidéos de référence

Pour les modèles qui acceptent plusieurs vidéos de référence d’après le tableau des capacités, utilisez metadata.referenceVideos :

{
  "model": "<MODEL_ID>",
  "prompt": "Reprendre le rythme et les mouvements de caméra de la référence sans modifier l’apparence du sujet",
  "duration": 8,
  "ratio": "16:9",
  "images": ["https://cdn.example.com/subject.jpg"],
  "metadata": {
    "referenceVideos": [
      "https://cdn.example.com/camera-motion.mp4"
    ]
  }
}

3.3 Audio de référence

Pour les modèles qui acceptent l’audio de référence d’après le tableau des capacités, utilisez metadata.referenceAudios :

{
  "model": "<MODEL_ID>",
  "prompt": "Le personnage chante sur le rythme de l’audio de référence, synchronisation labiale naturelle",
  "duration": 10,
  "ratio": "16:9",
  "images": ["https://cdn.example.com/singer.jpg"],
  "metadata": {
    "referenceAudios": [
      "https://cdn.example.com/voice-reference.mp3"
    ]
  }
}

Pour les images de référence de MiniMax H3, n’utilisez pas images au niveau racine : utilisez metadata.referenceImages comme indiqué dans l’API vidéo MiniMax.

3.4 Médias mixtes pour les modèles multi-références

{
  "model": "<MODEL_ID>",
  "prompt": "Publicité tech reprenant l’apparence du produit des images, le rythme de caméra de la vidéo et l’ambiance sonore de l’audio de référence",
  "duration": 12,
  "ratio": "16:9",
  "images": [
    "https://cdn.example.com/product-front.jpg",
    "https://cdn.example.com/product-detail.jpg"
  ],
  "metadata": {
    "referenceVideos": [
      "https://cdn.example.com/motion-reference.mp4"
    ],
    "referenceAudios": [
      "https://cdn.example.com/sound-reference.mp3"
    ]
  }
}

N’utilisez pas plusieurs alias pour un même type de média. Par exemple, n’envoyez pas à la fois images au niveau racine et metadata.referenceImages : lorsque plusieurs champs de compatibilité coexistent, la passerelle n’en retient qu’un seul jeu, sans garantie de fusion.

3.5 Exigences relatives aux URL des médias

1. Les vidéos et audios de référence doivent être des URL HTTPS publiques téléchargeables anonymement. blob:, les chemins locaux et data:video/... ne constituent pas un protocole universel de vidéo de référence ; téléversez d’abord les fichiers locaux comme indiqué dans la section suivante.
2. L’URL ne doit dépendre ni de cookies, ni d’une session de navigateur, ni du Referer, ni d’en-têtes personnalisés.
3. N’utilisez pas localhost, une IP privée, un nom de service Docker ni une adresse accessible uniquement depuis votre réseau interne.
4. L’URL doit rester valide pendant toute la génération ; une validité d’au moins 60 minutes est recommandée.
5. Formats recommandés : JPG, PNG ou WebP pour les images ; MP4/MOV pour les vidéos ; MP3/WAV pour l’audio.
6. Il est recommandé de ne pas dépasser 50 Mo par vidéo et 15 Mo par fichier audio ; un média trop volumineux peut échouer lors du téléchargement ou de la modération.
7. Avant de référencer des médias de tiers, assurez-vous de disposer des droits d’auteur, droits à l’image et autorisations d’utilisation nécessaires.

Qu’une page de média s’ouvre ne signifie pas que les octets de la vidéo sont téléchargeables : l’URL doit renvoyer le média lui-même, et non une page de partage HTML. Une URL accessible ne garantit pas non plus que l’encodage, la durée ou les dimensions respectent les exigences du modèle cible. Pour les modèles vidéo Google, les images peuvent aussi être transmises en Base64 ou par téléversement de fichier, voir l’API vidéo Google ; les vidéos de référence restent acceptées uniquement par URL.

3.6 Téléverser un média local (autorisation, puis PUT)

Ce point de terminaison fournit un stockage temporaire de médias. Il ne génère pas de vidéo, ne transcode pas, ne compresse pas et n’extrait pas automatiquement d’images.

Étape 1 : demandez une autorisation de téléversement côté serveur.

POST https://api.88api.ai/v1/media/uploads
Authorization: Bearer sk-xxxx
Content-Type: application/json

{
  "size": 1234567,
  "mime_type": "video/mp4",
  "sha256": "<SHA-256 des octets bruts du fichier, encodé en Base64URL sans padding>"
}

Types acceptés : video/mp4, video/webm, video/quicktime ; audio/mpeg, audio/wav, audio/ogg, audio/mp4, audio/flac ; image/png, image/jpeg, image/webp, image/gif. La limite de téléversement n’est pas la limite de référence du modèle : le média doit aussi respecter les limites plus strictes du modèle cible.

Exemple de réponse HTTP 200 (les chevrons sont des espaces réservés, pas des valeurs réelles utilisables) :

{
  "url": "https://assets.88api.ai/media/reference-media/<object-id>.mp4",
  "upload_url": "https://assets.88api.ai/media/reference-media/<object-id>.mp4",
  "method": "PUT",
  "headers": {
    "Content-Type": "video/mp4",
    "X-Media-Upload-Token": "<scoped-upload-token>"
  },
  "expires_at": 1789373400
}

Ici, expires_at est l’échéance de l’autorisation de téléversement (secondes Unix, environ 10 minutes) et non la durée de conservation du fichier ; à ce stade, url ne signifie pas non plus que le fichier a été téléversé. L’autorisation permet uniquement d’écrire le fichier désigné et ne donne pas accès à l’ensemble du bucket.

Étape 2 : téléversez le fichier binaire d’origine avant l’échéance de l’autorisation. Reprenez tels quels upload_url, method et headers de la réponse :

# Ces variables proviennent de la réponse d’autorisation ; n’envoyez pas API_KEY à l’adresse de téléversement.
curl --request PUT "$UPLOAD_URL" \
  --header 'Content-Type: video/mp4' \
  --header "X-Media-Upload-Token: $UPLOAD_TOKEN" \
  --data-binary @reference.mp4

Il ne s’agit ni de multipart/form-data (pas de -F), ni de Base64 dans du JSON. Envoyez le même Content-Length, le même type MIME et les mêmes octets que lors de la demande. Un navigateur peut envoyer directement un File/Blob et calcule lui-même le Content-Length. Un client de streaming côté serveur doit lui aussi fournir la longueur exacte ; n’utilisez pas de téléversement chunked de longueur inconnue.

HTTP 201 confirme la fin du téléversement et renvoie url, size, mime_type et expires_at. Cette fois, expires_at est bien l’échéance du média (secondes Unix, 30 jours après le téléversement de l’objet). Une fois le succès confirmé, placez url dans le champ de référence attendu par le modèle cible. Une application web doit demander l’autorisation via son propre back-end puis téléverser directement depuis le navigateur, sans jamais exposer de clé API longue durée côté front-end.

Une même adresse de téléversement ne peut pas être écrasée : un PUT répété renvoie 409, réutilisez alors l’adresse déjà téléversée avec succès. En cas de coupure réseau au résultat incertain, vérifiez d’abord l’URL par une requête HEAD anonyme au lieu de demander immédiatement un nouvel objet. Le téléversement et la référence ne créent aucune nouvelle tâche de génération.

5. Mode images de début et de fin pour les modèles compatibles

Les images de début et de fin se placent dans metadata.firstFrame et metadata.lastFrame :

L’exemple ci-dessous s’applique aux modèles multi-références qui prennent en charge ces champs. Veo et Gemini Omni acceptent également metadata.firstFrame et metadata.lastFrame ; pour les autres écritures, voir l’API vidéo Google.

{
  "model": "<MODEL_ID>",
  "prompt": "Transition fluide d’une place vide à l’aube vers le même cadrage la nuit, lumières allumées",
  "duration": 10,
  "ratio": "16:9",
  "metadata": {
    "firstFrame": "https://cdn.example.com/start.jpg",
    "lastFrame": "https://cdn.example.com/end.jpg"
  }
}

Règles :

• lastFrame ne peut pas être utilisé seul : firstFrame doit aussi être fourni.
• La plupart des modèles compatibles n’autorisent pas à combiner les images de début et de fin avec des images, vidéos ou audios de référence ordinaires.
• Lorsque le tableau des capacités indique « exclusif », choisissez soit les images de début et de fin, soit les médias de référence ordinaires.

6. Capacités actuelles des modèles vidéo

Les tableaux ci-dessous présentent les capacités des modèles publics recensés ; ce ne sont pas des ID de modèles fixes à utiliser dans les requêtes. Les requêtes doivent utiliser l’id obtenu par la clé API en cours via /v1/models. Les ID de modèles peuvent varier selon les comptes ; tant que vous utilisez le protocole unifié /v1/videos, le client n’a pas besoin de savoir comment le serveur choisit le modèle.

Spécifications par marque

Les paramètres et les champs de médias diffèrent d’une marque à l’autre. Consultez la page de la marque concernée avant toute intégration :

Tableau récapitulatif des capacités

La numérotation commence à 1 et sert uniquement à la lecture ; ce n’est pas un paramètre de requête. Les noms publics et les familles de capacités du tableau sont également donnés à titre de correspondance : dans vos appels, utilisez l’id exact renvoyé par /v1/models pour la clé API en cours, sans reconstituer de nom ni deviner de correspondance.

Règles propres à chaque modèle

Les champs varient fortement d’une marque à l’autre. Voici les points les plus souvent sources d’erreurs ; les règles complètes figurent sur les pages des marques ci-dessus :

• Wan wan3.0-video* : envoyez les images de début et de fin et les références dans le tableau media (recommandé). metadata.firstFrame/lastFrame/referenceImages/referenceVideos/referenceAudios (formes snake_case comprises), firstFrame/first_frame/lastFrame/last_frame au niveau racine et images au niveau racine (1re = image de début, 2e = image de fin, 2 au maximum) sont aussi convertis en media. Un champ de média illisible renvoie 400.
• Pour Grok, aspect_ratio et ratio sont équivalents ; si plusieurs champs de format sont envoyés, leurs valeurs doivent concorder. Une seule image d’entrée au maximum.
• minimax-h3 reçoit ses images de référence dans metadata.referenceImages et ses images de début et de fin dans metadata.firstFrame/lastFrame ; le sens de images au niveau racine varie selon la ligne attribuée : ne vous y fiez pas. Les résolutions 480P et 4K ont été retirées.
• Veo et Gemini Omni reçoivent leurs vidéos de référence dans video/videos au niveau racine, et non dans metadata.referenceVideos.
• Seedance relais officiel accepte aussi les champs au singulier image, input_reference, video et audio comme médias de référence, et un même média envoyé deux fois n’est compté qu’une fois ; un size en conflit avec ratio, aspect_ratio ou resolution renvoie 400. Ce groupe prend aussi en charge la bibliothèque de portraits virtuels, les brouillons 2.5, la dernière image, la recherche web, l’annulation des tâches en file d’attente et l’ID de tâche officiel ; voir Seedance relais officiel.
• SD2.5 exige un format d’image explicite et ne prend pas en charge auto.
• Seedance édition officielle, SD2.5, SD2.0 et kling-3.0-turbo n’ont qu’un seul nom de modèle par série : resolution sélectionne le niveau, qui détermine aussi la facturation ; à défaut, le niveau le plus bas de la série s’applique, et un niveau non pris en charge renvoie 400. Les anciens noms avec suffixe de niveau (par exemple SD2.5 720P ou SD2.0 4K) restent utilisables, mais sont fixés au niveau indiqué dans le nom et ne sont plus affichés sur la place des modèles. Les anciens noms Kling avec suffixe de niveau ont été retirés.

7. Réponse de création

Une création réussie renvoie immédiatement l’ID public de la tâche :

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "<MODEL_ID>",
  "status": "queued",
  "progress": 0,
  "created_at": 1788249600
}

Conservez l’id. L’API standard ne garantit pas la présence de task_id : les nouvelles intégrations doivent utiliser id.

HTTP 200 signifie « tâche acceptée », et non que la vidéo est déjà générée.

8. Interroger la tâche (polling)

curl 'https://api.88api.ai/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Authorization: Bearer sk-xxxx'

États unifiés

Exemple de réponse de réussite :

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "<MODEL_ID>",
  "status": "completed",
  "progress": 100,
  "created_at": 1788249600,
  "completed_at": 1788250200,
  "url": "https://assets.88api.ai/media/task-videos/2026/09/<object-key>.mp4",
  "video_url": "https://assets.88api.ai/media/task-videos/2026/09/<object-key>.mp4",
  "result_url": "https://assets.88api.ai/media/task-videos/2026/09/<object-key>.mp4"
}

Exemple de réponse d’échec :

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "<MODEL_ID>",
  "status": "failed",
  "progress": 100,
  "error": {
    "code": "video_generation_failed",
    "message": "Échec de la génération vidéo"
  }
}

Stratégie d’interrogation

1. Attendez 3 à 5 secondes après la création avant la première interrogation.
2. Interrogez de préférence toutes les 10 à 15 secondes, jamais toutes les secondes.
3. Un client interactif peut se fixer un budget d’attente de 15 minutes ; côté serveur, conservez l’ID de la tâche pour poursuivre l’interrogation ou recevoir un rappel. L’arrêt de l’attente côté client ne signifie ni échec, ni annulation, ni remboursement de la tâche.
4. Ne soumettez pas à nouveau la même tâche tant qu’elle est queued ou in_progress, sous peine de facturation en double.
5. Si vous configurez aussi un rappel, l’interrogation peut servir de mécanisme de secours.

Le délai d’expiration d’une requête HTTP, la durée d’attente totale du client et l’échéance de la tâche côté serveur sont des notions distinctes. Ne présentez pas les 15 minutes comme une garantie d’arrêt côté serveur, et ne déduisez pas le succès de progress=100 seul : fiez-vous à status. Une fois la page ou le réseau rétabli, vous pouvez continuer à interroger la tâche d’origine.

9. Rappels (webhooks)

Cette section concerne uniquement les modèles qui prennent explicitement en charge les rappels. Pour les modèles vidéo Google (Veo, Gemini Omni) et les autres modèles sans prise en charge explicite, utilisez l’interrogation et ne définissez pas callback_url.

Configuration à la création

{
  "model": "<MODEL_ID>",
  "prompt": "Survol en drone d’une ville cyberpunk",
  "duration": 8,
  "size": "16:9",
  "callback_url": "https://api.customer.example/webhooks/88api/video"
}

callback_url doit :

• être une URL HTTP(S) accessible publiquement ; HTTPS est fortement recommandé en production ;
• ne pas dépasser 2048 caractères ;
• ne pas pointer vers une IP privée, localhost, une adresse link-local ou un port restreint ;
• répondre par un code 2xx quelconque en moins de 15 secondes.

Les rappels sont envoyés uniquement à l’état final :

• video.completed
• video.failed

En-têtes du rappel

Content-Type: application/json
User-Agent: NewAPI-Task-Callback/1.0
X-NewAPI-Event: video.completed
X-NewAPI-Delivery: evt_task_xxx_completed
X-NewAPI-Timestamp: 1788250200
X-NewAPI-Signature: sha256=<hex-hmac>

Événement de réussite

{
  "id": "evt_task_xxxxxxxxxxxxxxxxxxxxxxxx_completed",
  "type": "video.completed",
  "created_at": 1788250200,
  "data": {
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
    "model": "<MODEL_ID>",
    "status": "completed",
    "progress": "100%",
    "output_url": "https://assets.88api.ai/media/task-videos/2026/09/<object-key>.mp4",
    "created_at": 1788249600,
    "completed_at": 1788250200
  }
}

Événement d’échec

{
  "id": "evt_task_xxxxxxxxxxxxxxxxxxxxxxxx_failed",
  "type": "video.failed",
  "created_at": 1788250200,
  "data": {
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
    "model": "<MODEL_ID>",
    "status": "failed",
    "progress": "100%",
    "error": "Échec de la génération vidéo",
    "created_at": 1788249600,
    "completed_at": 1788250200
  }
}

Vérifier la signature du rappel

La clé de signature est la clé API complète (préfixe sk- compris) utilisée pour créer la tâche. La chaîne signée est :

X-NewAPI-Timestamp + "." + octets bruts du corps de la requête

Exemple de vérification en Node.js :

import crypto from "node:crypto";
import express from "express";

const app = express();

// Conserver le corps brut de la requête avant d’analyser le JSON.
app.use(
  express.json({
    verify: (req, _res, buffer) => {
      req.rawBody = buffer;
    },
  }),
);

app.post("/webhooks/88api/video", (req, res) => {
  const timestamp = req.header("X-NewAPI-Timestamp") || "";
  const timestampNumber = Number(timestamp);
  if (
    !Number.isFinite(timestampNumber) ||
    Math.abs(Date.now() / 1000 - timestampNumber) > 300
  ) {
    return res.status(401).send("stale timestamp");
  }
  const received = (req.header("X-NewAPI-Signature") || "").replace(
    /^sha256=/,
    "",
  );
  const secret = process.env.API_KEY; // clé complète sk-xxxx
  const signed = Buffer.concat([
    Buffer.from(`${timestamp}.`, "utf8"),
    req.rawBody,
  ]);
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signed)
    .digest("hex");

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send("invalid signature");

  // Dédupliquer de façon idempotente avec X-NewAPI-Delivery ou req.body.id.
  console.log(req.body.type, req.body.data.task_id);
  return res.sendStatus(204);
});

Nouvelles tentatives et idempotence

• En cas de délai dépassé, d’erreur réseau ou de réponse autre que 2xx, 88API réessaie avec un backoff exponentiel.
• Chaque requête expire au bout de 15 secondes ; 8 tentatives au maximum, avec un backoff plafonné à 15 minutes.
• Un même événement peut être livré plusieurs fois. Le client doit dédupliquer de façon idempotente à l’aide de X-NewAPI-Delivery ou de l’id de l’événement.
• Pour limiter le risque de rejeu, il est recommandé de rejeter les rappels dont l’horodatage s’écarte de plus de 5 minutes de l’heure de votre serveur.
• Il est recommandé de vérifier la signature, d’enregistrer l’événement et de répondre 2xx immédiatement, puis de traiter la logique métier longue dans votre propre file asynchrone.

10. Récupérer le fichier vidéo

Lorsque la tâche passe à completed, utilisez de préférence l’url renvoyée par l’interrogation ; un client de compatibilité peut se rabattre sur video_url/result_url, et un rappel fournit data.output_url. Ces champs constituent le résultat livré par le serveur : ne construisez jamais de chemin de média à partir de l’ID de tâche ou d’un ID interne.

# RESULT_URL provient tel quel de la réponse finale ; n’envoyez pas la clé API au serveur de médias.
curl --fail --location "$RESULT_URL" --output result.mp4

Remarques :

• Le client doit suivre les redirections HTTP 3xx ; avec curl, ajoutez --location.
• Les résultats archivés par 88API utilisent des adresses anonymes https://assets.88api.ai/media/... ; les résultats officiels qui remplissent les conditions d’un accès direct sûr conservent leur URL d’origine et ne sont pas réécrits vers notre domaine.
• Les autres résultats qui ne peuvent pas être publiés directement ou mis en correspondance de façon certaine peuvent continuer à renvoyer une adresse de compatibilité avec des paramètres d’accès. Conservez intégralement l’URL et les paramètres renvoyés par le serveur, sans supprimer de paramètres ni remplacer le domaine ; n’ajoutez pas de paramètres de requête aux adresses assets (réponse 400).
• L’ancien /v1/videos/{id}/content fournit une redirection 307 de compatibilité pour les vidéos archivées ; ne le considérez pas comme un lien direct officiel ni comme un passage obligé pour tous les résultats. En cas de 404, interrogez à nouveau la tâche pour obtenir l’adresse réelle du résultat au lieu de relancer aveuglément une génération.
• L’output_url d’un rappel est une adresse de résultat opaque qui peut expirer ; n’analysez ni son domaine ni la structure de son chemin.
• Ne construisez, ne conservez et ne dépendez d’aucun autre ID de tâche ; utilisez uniquement l’id public renvoyé à la création.
• Pour conserver durablement vos vidéos, téléchargez-les dans votre propre stockage objet une fois la tâche terminée.

9.1 Conservation, lecture et réutilisation entre modèles

• Les médias téléversés et les vidéos archivées par 88API sont conservés 30 jours à compter du téléversement de chaque objet. Les lectures répétées, l’interrogation d’anciennes tâches et les références répétées ne prolongent pas ce délai et ne créent pas de nouvelle copie. Les URL de résultats officielles suivent la durée de validité de leur source, sans garantie de 30 jours.
• L’absence de paramètres de signature et de connexion ne signifie pas une conservation permanente : un fichier expiré renvoie 410, et peut renvoyer 404 après suppression par les règles de cycle de vie. L’existence d’un enregistrement de tâche ne garantit pas que le fichier binaire existe encore.
• Les médias publics prennent en charge GET, HEAD, les requêtes Range à plage unique et la lecture cross-origin depuis un navigateur. L’en-tête X-Media-Expires-At (secondes Unix) est lisible ; une requête Range réussie renvoie généralement 206. Le cache ne prolonge pas l’échéance d’origine et ne garantit pas une vitesse de téléchargement identique dans toutes les régions.
• Un résultat généré par Veo peut servir d’entrée à un autre modèle qui accepte les vidéos de référence, à condition que l’adresse soit toujours valide et que le format, les dimensions et la durée respectent les exigences du modèle cible. Placez directement l’URL du résultat dans le champ de référence de ce modèle, sans téléchargement ni nouveau téléversement. Veo lui-même n’accepte une vidéo d’entrée que pour la prolongation et ne prend pas en charge les vidéos de référence.

{
  "model": "<MODEL_ID>",
  "prompt": "Conserver le sujet et le mouvement de la vidéo de référence et prolonger le plan",
  "duration": 4,
  "ratio": "16:9",
  "metadata": {
    "referenceVideos": ["<URL HTTPS complète du résultat renvoyée par la tâche précédente>"]
  }
}

11. Exemple complet d’interrogation en JavaScript

Node.js 22 ou version ultérieure ; définissez côté serveur API_KEY, MODEL_ID et REFERENCE_FILE (chemin d’un fichier MP4). MODEL_ID doit provenir de la réponse GET /v1/models pour la clé API en cours. Définissez TASK_ID pour reprendre directement une tâche existante, sans nouveau téléversement ni nouvelle génération. L’exemple crée une génération payante, puis affiche uniquement le corps de la requête suivante, sans lancer automatiquement une deuxième génération. Pour plus de lisibilité, il charge le fichier en mémoire : limitez la concurrence si vous traitez de gros fichiers en masse.

// video-api-example.mjs — Node.js 22+, run with API_KEY, MODEL_ID, and REFERENCE_FILE.
import { readFile, stat } from "node:fs/promises";
import { createHash } from "node:crypto";

const apiKey = process.env.API_KEY;
if (!apiKey) throw new Error("Set API_KEY on your server");
const baseUrl = "https://api.88api.ai";
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function apiJSON(path, body) {
  // No automatic POST retry: a timed-out create may already have been accepted.
  const response = await fetch(baseUrl + path, {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(120000),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  return response.json();
}

async function uploadMedia(file, mimeType) {
  const info = await stat(file);
  if (!info.isFile() || info.size < 1 || info.size > 100000000) {
    throw new Error("File must contain 1–100000000 bytes");
  }
  const bytes = await readFile(file);
  const permit = await apiJSON("/v1/media/uploads", {
    size: bytes.length, mime_type: mimeType,
    sha256: createHash("sha256").update(bytes).digest("base64url"),
  });
  const target = new URL(permit.upload_url);
  if (target.origin !== "https://assets.88api.ai" || permit.method !== "PUT") {
    throw new Error("Unexpected upload destination; do not send credentials");
  }
  const response = await fetch(target, {
    method: "PUT", headers: permit.headers, body: bytes,
    redirect: "error", signal: AbortSignal.timeout(120000),
  });
  // A 409/ambiguous upload is not automatically retried; HEAD permit.url first.
  if (response.status !== 201) throw new Error(`Upload HTTP ${response.status}`);
  return response.json();
}

async function waitForVideo(id, budgetMs = 15 * 60 * 1000) {
  const deadline = Date.now() + budgetMs;
  let delay = 4000;
  while (Date.now() < deadline) {
    await sleep(Math.min(delay, deadline - Date.now()));
    const remaining = deadline - Date.now();
    if (remaining <= 0) break;
    let response, state;
    try {
      response = await fetch(`${baseUrl}/v1/videos/${encodeURIComponent(id)}`, {
        headers: { Authorization: `Bearer ${apiKey}` },
        signal: AbortSignal.timeout(Math.min(30000, remaining)),
      });
      if (response.ok) state = await response.json();
    } catch {
      delay = Math.min(delay * 2, 60000);
      continue; // Retry a read, never create a replacement task.
    }
    if (response.status === 429 || response.status >= 500) {
      const retryAfter = response.headers.get("Retry-After");
      const seconds = retryAfter && /^\d+$/.test(retryAfter)
        ? Number(retryAfter)
        : (Date.parse(retryAfter || "") - Date.now()) / 1000;
      delay = Number.isFinite(seconds) && seconds > 0
        ? Math.max(1000, seconds * 1000)
        : Math.min(delay * 2, 60000);
      await response.body?.cancel();
      continue;
    }
    if (!response.ok) throw new Error(`Task ${id}: HTTP ${response.status}`);
    if (state.status === "completed") {
      const result = state.url || state.video_url || state.result_url;
      if (typeof result !== "string" || new URL(result).protocol !== "https:") {
        throw new Error(`Task ${id} completed without a usable HTTPS result URL`);
      }
      return result; // Keep official URLs and capability query parameters intact.
    }
    if (state.status === "failed") {
      throw new Error(`Task ${id}: ${state.error?.message || "video generation failed"}`);
    }
    if (!["queued", "in_progress", "unknown"].includes(state.status)) {
      throw new Error(`Task ${id}: unexpected status ${state.status}`);
    }
    delay = 12000;
  }
  throw new Error(`Stopped waiting for ${id}; save this ID and query later. Not cancelled.`);
}

async function main() {
  // Resume a saved task without uploading or creating another paid task.
  let id = process.env.TASK_ID;
  if (!id) {
    if (!process.env.MODEL_ID) throw new Error("Set MODEL_ID from GET /v1/models");
    if (!process.env.REFERENCE_FILE) throw new Error("Set REFERENCE_FILE");
    const media = await uploadMedia(process.env.REFERENCE_FILE, "video/mp4");
    const task = await apiJSON("/v1/videos", {
      model: process.env.MODEL_ID, prompt: "Conserver le sujet et le mouvement de la vidéo de référence et prolonger le plan",
      duration: 4, ratio: "16:9", metadata: { referenceVideos: [media.url] },
    });
    id = task.id;
    if (!id) throw new Error("Create response did not contain a task ID; do not blindly retry");
    console.log("Save task ID:", id); // Persist to your database in production.
  }
  const resultURL = await waitForVideo(id);
  console.log("Result URL:", resultURL); // This grants media access; do not log publicly.
  // This only shows the NEXT request body; it does not create a second paid task.
  console.log(JSON.stringify({
    model: process.env.MODEL_ID, prompt: "Conserver le sujet et le mouvement de la vidéo de référence et prolonger le plan",
    duration: 4, ratio: "16:9", metadata: { referenceVideos: [resultURL] },
  }, null, 2));
}

await main();

12. Gestion des erreurs et nouvelles tentatives

POST /v1/videos ne garantit pas encore de clé d’idempotence fournie par le client. Si un délai réseau expire après l’envoi complet d’une requête, ne la renvoyez pas aveuglément tout de suite : plusieurs tâches risqueraient d’être générées et facturées.