Génération vidéo Veo

Ce document s’adresse aux développeurs et explique comment appeler les modèles de génération vidéo Google Veo via aicentos. L’interface suit le format compatible avec l’API vidéo d’OpenAI (OpenAI Videos API) ; côté aval, il suffit d’utiliser le type de canal openai.

Capacités des modèlesCopier le lien d’ancre

La facturation est basée sur la durée de génération de la vidéo (en secondes). Le prix unitaire exact est celui affiché dans la console aicentos ; le débit final fait foi selon les enregistrements réels du système.

Capacités officielles et périmètre ouvert par aicentosCopier le lien d’ancre

Documentation de référence :

• Génération vidéo Veo de l’API Google Gemini
• Images de référence Veo
• Première et dernière frame Veo
• Format d’image Veo

Format d’imageCopier le lien d’ancre

La requête peut préciser le format via metadata.aspectRatio ou le champ de formulaire aspectRatio :

{
  "metadata": {
    "aspectRatio": "9:16"
  }
}

Si aucun aspectRatio n’est transmis explicitement, le système le déduit d’abord de size : par exemple 1280x720 donne 16:9 et 720x1280 donne 9:16. Si size n’est pas transmis non plus, l’amont utilise 16:9 par défaut.

AudioCopier le lien d’ancre

La série Veo 3.1 génère nativement l’audio, mais la table de paramètres Veo de l’API Gemini actuelle n’expose pas generateAudio comme paramètre contrôlable. Transmettre ce champ peut renvoyer INVALID_ARGUMENT côté amont.

Pour contrôler le contenu audio, décrivez dialogues, sons d’ambiance, effets ou style musical dans le prompt, par exemple :

Un phare au bord de la mer au crépuscule, les vagues frappant les rochers, au loin un vent sourd et des cris d’oiseaux marins, lumière cinématographique, mouvement de caméra stable

Entrées imageCopier le lien d’ancre

• Types MIME d’image pris en charge : image/jpeg, image/png, image/webp. Préférez un fichier ou du Base64 ; évitez de passer directement une URL d’image distante.
• Attention en mode images de référence : l’amont n’y prend pas en charge negativePrompt et peut renvoyer Negative prompt is not supported in your use case. N’envoyez pas de negativePrompt avec des requêtes à images de référence.
• Détail d’implémentation : dans l’API Gemini, les entrées image de Veo predictLongRunning utilisent bytesBase64Encoded + mimeType, et non l’inlineData du generateContent classique. aicentos convertit les images téléversées en multipart vers le format attendu par l’amont.

Règles de facturationCopier le lien d’ancre

• Facturation à la durée de génération, en secondes. Utilisez les durées prises en charge par le modèle (tableau ci-dessus) ; évitez de passer des durées arbitraires.
• Si la requête ne précise pas de durée, la facturation est établie par défaut sur 8 secondes.
• Ordre de priorité de lecture de la durée : metadata.durationSeconds > duration > seconds > 8 secondes par défaut.
• Ordre de priorité de lecture de la résolution : metadata.resolution > size > 720p par défaut.
• 720p / 1080p / 4K sont facturés selon les mêmes règles ; aucune majoration liée à la résolution.
• aspectRatio ne contrôle que l’orientation (paysage ou portrait) ; aucune majoration.
• Le 4K n’est possible qu’en 8 secondes.
• Le prix unitaire exact est celui de la console aicentos.

EndpointsCopier le lien d’ancre

Trois endpoints sont recommandés aujourd’hui :

Pour obtenir directement l’URL du résultat lors de l’interrogation, vous pouvez aussi utiliser :

AuthentificationCopier le lien d’ancre

export BASE_URL="https://aicentos.com"
export AICENTOS_API_KEY="sk-xxxxxx"

Toutes les requêtes incluent :

-H "Authorization: Bearer $AICENTOS_API_KEY"

Créer une tâche texte vers vidéoCopier le lien d’ancre

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "Un phare au bord de la mer au crépuscule, lent travelling avant, les vagues frappant les rochers, lumière cinématographique, mouvement de caméra stable",
    "seconds": "8",
    "size": "1280x720",
    "metadata": {
      "negativePrompt": "blurry, watermark, distorted, low quality",
      "resolution": "720p",
      "aspectRatio": "16:9",
      "seed": 20260401
    }
  }'

Réponse type :

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1775025000
}

Créer une tâche image vers vidéo (première frame)Copier le lien d’ancre

Pour l’image vers vidéo, multipart/form-data est recommandé ; le champ de la première frame doit impérativement s’appeler input_reference.

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=La fille se tourne vers la caméra, une brise légère soulève ses cheveux, les lumières de la ville en arrière-plan légèrement floutées, caméra avançant en douceur" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, deformed hands" \
  -F "seed=20260401"

Créer une tâche première/dernière frameCopier le lien d’ancre

Cette tâche exige à la fois la première et la dernière frame. Première frame via input_reference, dernière via last_frame ou lastFrame.

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=Transition naturelle de la première image (fille) à la dernière (garçon), travelling avant régulier, lumières de ville floutées, cheveux et vêtements légèrement animés par le vent, transition fluide et réaliste" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "last_frame=@./last-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, distorted face, deformed hands" \
  -F "seed=20260402"

Créer une tâche avec images de référenceCopier le lien d’ancre

Les tâches avec images de référence ne sont possibles que sur la série Veo 3.1, 3 images maximum, avec referenceType limité à asset. Les noms de champ acceptés sont reference_image, reference_images ou referenceImages. N’envoyez pas de negativePrompt sur ces tâches.

curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=En s’appuyant sur l’apparence des personnages et l’ambiance nocturne urbaine des deux images, générer un plan de rue cinématographique en duo, travelling avant régulier, lumières d’arrière-plan légèrement floutées, personnages regardant naturellement la caméra" \
  -F "reference_image=@./ref-1.png;type=image/png" \
  -F "reference_image=@./ref-2.png;type=image/png" \
  -F "reference_type=asset" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "seed=20260403"

Le JSON / Base64 est aussi accepté :

{
  "model": "veo-3.1-generate-preview",
  "prompt": "Générer un plan publicitaire à partir de l’apparence du produit des images de référence",
  "duration": 8,
  "metadata": {
    "resolution": "720p",
    "aspectRatio": "16:9",
    "referenceImages": [
      {
        "image": {
          "bytesBase64Encoded": "BASE64_IMAGE",
          "mimeType": "image/png"
        },
        "referenceType": "asset"
      }
    ]
  }
}

Consulter le statut d’une tâcheCopier le lien d’ancre

Conservez d’abord l’id ou le task_id renvoyé par l’appel de création :

export TASK_ID="task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Puis interrogez le statut :

curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"

Pendant le traitement, réponse type :

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1775025000
}

À la fin, réponse type :

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1775025000,
  "completed_at": 1775025068
}

Consulter le statut et l’URL du résultatCopier le lien d’ancre

Pour récupérer directement une URL téléchargeable lors de l’interrogation :

curl -X GET "$BASE_URL/v1/video/generations/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"

Réponse type :

{
  "code": "success",
  "message": "",
  "data": {
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "succeeded",
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "url": "https://aicentos.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"
  }
}

Télécharger la vidéoCopier le lien d’ancre

Une fois la tâche terminée, téléchargez directement :

curl -L "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -o veo-result.mp4

Signification des statutsCopier le lien d’ancre

Les statuts renvoyés par GET /v1/videos/{task_id} sont principalement :

Les statuts renvoyés par GET /v1/video/generations/{task_id} sont principalement :

Points d’attention pour l’intégrationCopier le lien d’ancre

• prompt est obligatoire.
• En image vers vidéo, le champ image doit s’appeler input_reference.
• Les tâches première/dernière frame exigent les deux frames : première via input_reference, dernière via last_frame ou lastFrame.
• Les tâches avec images de référence ne fonctionnent que sur la série Veo 3.1, 3 images maximum, et obligatoirement en 8 secondes.
• N’envoyez pas de negativePrompt sur les tâches à images de référence.
• Pour l’image vers vidéo via Gemini, évitez de passer une URL d’image distante ; préférez un fichier ou du Base64.
• Interrogez GET /v1/videos/{task_id} par polling et attendez status=completed avant de télécharger.
• La série Veo 3.1 accepte 4, 6 ou 8 secondes ; 8 secondes sont obligatoires en 1080p ou 4k. - Paysage avec aspectRatio=16:9, portrait avec aspectRatio=9:16 ; sans valeur transmise, 16:9 par défaut.
• Ne transmettez pas le paramètre generateAudio. La série Veo 3.1 génère nativement l’audio, mais l’API Gemini actuelle ne permet pas de l’activer ou de le désactiver via generateAudio ; transmettre ce champ peut renvoyer INVALID_ARGUMENT côté amont.
• Pour contrôler le contenu audio, décrivez dialogues, sons d’ambiance, effets ou style musical dans le prompt.
• Le Veo 3.1 officiel prend en charge l’extension vidéo, mais l’API aicentos actuelle n’expose pas encore l’entrée vidéo officielle.