Comment utiliser l'API MiniMax H3 Max pour le texte et l'image vers vidéo

Ce guide suit le chemin le plus court vers une requête réussie, puis ajoute la validation, l'interrogation, le callback, le stockage et le repli nécessaires en production. En attendant les pages de documentation H3 Max dédiées, vérifiez les champs exacts dans le contrat de route actuel de la page modèle.

Créez une clé API EvoLink, consultez l'estimation en direct sur la page du modèle MiniMax H3 Max, et gardez le guide H3 Max vs H3 à portée de main si votre workflow peut nécessiter la 2K ou des références plus larges.

Prérequis

Avant d'effectuer la première requête, confirmez :

Choisir le bon identifiant de modèle H3 Max

Étape 1 : effectuer une requête texte vers vidéo

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-text-to-video",
    "prompt": "A premium running shoe rotates on a clean studio pedestal while soft daylight moves across the fabric. Slow camera push-in, realistic material detail, no text or logos added.",
    "duration": 5,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }'

Les principaux paramètres T2V sont :

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 0,
  "status": "pending",
  "type": "video"
}

Étape 2 : effectuer une requête image vers vidéo première/dernière image

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-image-to-video",
    "prompt": "The camera makes a slow half-orbit as the box opens and the product rises smoothly. Preserve the packaging shape, colors, and lighting; end exactly on the supplied final composition.",
    "image_start": "https://cdn.example.com/h3-max/start.webp",
    "image_end": "https://cdn.example.com/h3-max/end.webp",
    "duration": 8,
    "quality": "768p"
  }'

Chaque image fournie doit utiliser une URL HTTP(S) directement accessible et respecter le contrat actuel :

• JPG, JPEG, PNG, WEBP, HEIC ou HEIF.
• 30 Mo maximum par image.
• Largeur et hauteur comprises entre 256 et 5 760 pixels.
• Rapport largeur/hauteur de 0,4 à 2,5.
• Au plus une première image et une dernière image.
• Corps JSON complet ne dépassant pas 64 Mo ; Base64 et mm_file:// ne sont pas acceptés.

Étape 3 : interroger le statut de la tâche

Interrogez la tâche avec le même token Bearer :

curl --request GET \
  --url "https://api.evolink.ai/v1/tasks/task-unified-1774857405-abc123" \
  --header "Authorization: Bearer $EVOLINK_API_KEY"

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 100,
  "status": "completed",
  "results": ["https://files.example.com/generated-video.mp4"],
  "type": "video"
}

Une politique d'interrogation simple doit utiliser un backoff exponentiel borné avec gigue plutôt qu'une interrogation continue. Par exemple : commencez autour de deux secondes, augmentez vers 10-15 secondes, arrêtez-vous à une échéance définie par l'application et permettez à un worker ultérieur de reprendre à l'aide de l'identifiant de tâche stocké. Le contrat API ne prévoit pas d'annulation pour H3 Max ; un timeout client ne doit donc pas être confondu avec une annulation en amont.

Étape 4 : ajouter un callback pour la production

{
  "model": "minimax-h3-max-text-to-video",
  "prompt": "A cinematic overhead shot of a city block transitioning from morning to night.",
  "duration": 5,
  "quality": "768p",
  "aspect_ratio": "16:9",
  "callback_url": "https://api.example.com/webhooks/evolink/video"
}

Le contrat EvoLink actuel exige HTTPS, rejette les destinations en IP privée, attend jusqu'à 10 secondes et relance un callback échoué jusqu'à trois fois. Votre gestionnaire doit :

1. Authentifier la requête à l'aide du mécanisme de vérification configuré par votre application.
2. Utiliser l'identifiant de tâche comme clé d'idempotence.
3. Renvoyer rapidement une réponse 2xx.
4. Déplacer les téléchargements et le post-traitement lourd vers une file d'attente.
5. Réconcilier l'état du callback avec l'endpoint de tâche avant la livraison finale au client si nécessaire.

Gardez l'interrogation disponible comme chemin de récupération. Les webhooks peuvent être retardés, rejetés par une politique réseau ou traités deux fois par l'infrastructure applicative.

Valider les requêtes avant la soumission

Gérer les erreurs par catégorie

Séparez les erreurs HTTP des échecs de tâches asynchrones. Un appel de création peut réussir alors que la génération échoue plus tard. Journalisez l'identifiant de tâche, la route, la classe d'entrée, la durée, la qualité, le statut final, le code d'erreur, le nombre de relances et le résultat du repli, sans journaliser les secrets ni les URL sources sensibles.

Concevoir le passage en production

Stocker la relation entre requête et tâche

Créez votre propre identifiant de job avant la soumission. Stockez l'identifiant de tâche EvoLink, l'identifiant de modèle, les paramètres normalisés, l'identifiant client/espace de travail, les horodatages et l'état de livraison. Cela rend possibles la relance, l'audit et le support même si un worker redémarre.

Télécharger rapidement les résultats terminés

Les URL de résultats H3 Max sont disponibles pendant 24 heures. Copiez les résultats acceptés vers un stockage durable et enregistrez la somme de contrôle ou la clé d'objet. Ne faites pas de l'URL source temporaire la ressource client permanente.

Rendre les relances explicites

Ne soumettez pas une nouvelle génération parce qu'une requête d'interrogation a expiré. Interrogez d'abord l'identifiant de tâche stocké. Ne créez une nouvelle tâche que lorsque l'originale a atteint un échec terminal et que votre politique de relance autorise une nouvelle tentative facturée.

Router les jobs incompatibles avant l'appel

Mesurer la sortie acceptée

Suivez :

• le taux de réussite des tâches et la latence de fin ;
• l'acceptation au premier essai et le taux de relance ;
• le coût par clip accepté ;
• le respect du prompt, de l'identité et des images clés ;
• le taux de modération et de requêtes invalides ;
• la fréquence de repli et le taux de récupération ;
• l'achèvement du téléchargement avant l'expiration de l'URL.

Erreurs d'intégration courantes

Liste de vérification avant la mise en production

1. La clé API est côté serveur et peut être renouvelée.
2. T2V et I2V utilisent des schémas de validation séparés.
3. La durée, la qualité, le ratio d'aspect et les limites d'image sont appliqués localement.
4. L'id de la réponse de création est stocké avant la sortie du worker.
5. L'interrogation utilise un backoff borné et peut reprendre.
6. Le traitement du callback est idempotent et l'interrogation reste disponible.
7. Les fichiers MP4 terminés sont copiés dans les 24 heures.
8. Les journaux séparent les erreurs de requête, les échecs de tâche et les rejets de revue.
9. Le prix provient de la page de modèle actuelle ou du service de tarification, pas d'une valeur de blog codée en dur.
10. H3 et un repli indépendant sont testés pour les jobs incompatibles ou échoués.

Questions fréquentes

Quel endpoint MiniMax H3 Max utilise-t-il sur EvoLink ?

Quel identifiant de modèle dois-je utiliser ?

L'API H3 Max est-elle synchrone ?

Puis-je générer une vidéo H3 Max de quatre secondes ?

Non. La durée prise en charge est un entier de 5 à 15 secondes. C'est MiniMax H3, et non H3 Max, qui prend en charge la borne inférieure de quatre secondes sur EvoLink.

Puis-je utiliser uniquement une dernière image ?

Oui. Le modèle image vers vidéo accepte les requêtes avec première image uniquement, dernière image uniquement, et première et dernière images.

Puis-je envoyer des images en Base64 ?

L'image vers vidéo accepte-t-elle un ratio d'aspect ?

N'en envoyez pas. La sortie suit le ratio de l'image fournie. Préparez l'image source pour le format de livraison prévu.

Combien de temps les URL de résultats restent-elles valides ?

Vingt-quatre heures. Copiez les fichiers MP4 terminés vers un stockage durable dans le cadre du workflow de livraison.

Où dois-je vérifier les tarifs actuels ?

Utilisez la section de tarification en direct et l'estimateur de la page produit H3 Max. Évitez de coder en dur un tarif de blog dans la budgétisation de production.

Références API et périmètre de vérification

• Page du modèle MiniMax H3 Max et contrat de route actuel sur EvoLink
• Référence EvoLink du statut des tâches asynchrones
• Documentation officielle Video Generation V2 de MiniMax