Comment utiliser l’API MiniMax H3

MiniMax H3, également recherché sous le nom de Hailuo 3 ou Hailuo 03, est le dernier modèle de génération vidéo de MiniMax. Il prend en charge trois flux de travail distincts : générer une vidéo à partir de texte, animer une image de début ou de fin et créer un nouveau clip à partir de références d'image, vidéo et audio.

Ce guide montre comment accéder au MiniMax H3 via EvoLink, choisir l'ID de modèle correct, soumettre une demande, suivre la tâche asynchrone et récupérer la vidéo terminée. Les exemples utilisent le même point de terminaison vidéo unifié dans les trois modes, vous pouvez donc ajouter H3 à un flux de production existant sans créer de système de tâches distinct.

Réponse rapide

• Point de terminaison : POST https://api.evolink.ai/v1/videos/generations
• Authentification : Clé API Bearer
• Modèle texte-vidéo : minimax-h3-text-to-video
• Modèle image vers vidéo : minimax-h3-image-to-video
• Modèle de vidéo de référence : minimax-h3-reference-to-video
• Sortie : vidéo 2K
• Durée : 4 à 15 secondes
• Flux de tâches : envoyez une requête, recevez un ID de tâche, puis interrogez l’endpoint de tâche ou utilisez un callback HTTPS
• Durée de vie des résultats : Téléchargez et stockez les vidéos terminées dans les 24 heures

Table des matières

1. Ce que MiniMax H3 peut faire
2. Principales fonctionnalités et mises à niveau pratiques
3. L'API MiniMax H3 en un coup d'œil
4. Comment accéder au MiniMax H3 API
5. Choisissez le bon mode de génération
6. Démarrage rapide : envoyer votre première requête en 60 secondes
7. Comprendre le workflow asynchrone
8. Exemple de texte vers vidéo
9. Exemples d'image en vidéo
10. Exemple de vidéo de référence
11. Télécharger les ressources locales
12. Implémentation complète de TypeScript
13. Implémentation complète de Python
14. Référence rapide des paramètres et des prompts
15. Erreurs et correctifs courants
16. Prix et planification des coûts
17. Liste de contrôle de production
18. Cas d'utilisation pratiques
19. FAQ

1. Ce que le MiniMax H3 peut faire

MiniMax H3 est conçu pour la génération de vidéos courtes avec différents niveaux de contrôle créatif. Les trois modes API partagent le même cycle de vie des tâches mais acceptent des entrées différentes.

La distinction clé est le contrôle. La conversion texte-vidéo donne au modèle le plus de liberté. L'image vers la vidéo ancre la composition sur une ou deux images. La vidéo de référence vous permet de décrire comment plusieurs ressources sources doivent influencer le résultat.

2. Principales fonctionnalités et mises à niveau pratiques

Les changements H3 les plus utiles pour les développeurs sont visibles dans le contrat d'entrée et de sortie :

• Trois flux de travail spécialement conçus. La génération de texte, d'images clés et de références multimodales a des ID de modèle distincts mais utilise un seul point de terminaison EvoLink.
• Sortie 2K. Les routes H3 actuels exposent une seule option de qualité 2k.
• Clips flexibles de 4 à 15 secondes. La durée est un nombre entier, ce qui facilite l'alignement de la durée de génération sur un plan de prise de vue.
• Contrôle de la première et de la dernière image. La conversion image-vidéo accepte une image de début, une image de fin, ou les deux.
• Entrées de référence plus riches. La vidéo de référence accepte des tableaux ordonnés d'images, de vidéos et d'audio, permettant une direction créative plus explicite qu'une image de sujet unique.
• Gestion des tâches orientée production. EvoLink fournit un point de terminaison de tâche asynchrone cohérent et un Callback d'achèvement facultatif dans les trois modes.

Le dernier point est une fonctionnalité d'intégration EvoLink, pas une capacité de modèle. C'est important car une application de production a besoin d'états de tâches, de Callbacks, de journalisation et de gestion des résultats prévisibles, quel que soit le modèle sélectionné.

En quoi cela diffère de Hailuo 2.3

Exemple officiel : référence vidéo et vocale

3. L'API MiniMax H3 en un coup d'œil

Les trois modes utilisent :

POST https://api.evolink.ai/v1/videos/generations

Règles partagées :

• duration accepte les nombres entiers de 4 à 15 ; la valeur par défaut est 5.
• quality doit être 2k. N'envoyez pas 768p.
• Les prompts peuvent être rédigées en anglais ou en chinois.
• Conservez les prompts dans environ 1 000 mots anglais ou 500 caractères chinois.
• Le débit binaire, la fréquence d'images et le codec ne sont pas configurables.
• La génération est asynchrone.

4. Comment accéder à l'API MiniMax H3

Vous avez besoin d'un compte EvoLink, d'une clé API et d'un crédit suffisant pour la tâche demandée.

1. Créez ou connectez-vous à votre compte EvoLink.
2. Ouvrez le tableau de bord Clés API et créez une clé.
3. Stockez la clé dans une variable d'environnement côté serveur.
4. Choisissez le mode H3 qui correspond à vos entrées disponibles.
5. Envoyez une demande au point de terminaison vidéo unifié.

EVOLINK_API_KEY=your_api_key

N'exposez jamais cette clé dans le JavaScript du navigateur, dans un référentiel public ou dans un ensemble d'applications mobiles. Appelez l'API EvoLink depuis votre serveur, votre action serveur, votre route API, votre travailleur ou un autre environnement d'exécution approuvé.

5. Choisissez le bon mode de génération

Utilisez cette table de routage avant de créer une charge utile :

6. Démarrage rapide : envoyer votre première requête en 60 secondes

Étape 1 : Envoyez une demande de texte vers vidéo

curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-text-to-video",
    "prompt": "A compact electric concept car drives through a rain-soaked city at night. The camera tracks beside the car, then slowly pulls back to reveal neon reflections across the street.",
    "quality": "2k",
    "aspect_ratio": "16:9",
    "duration": 5
  }'

L'API renvoie une tâche asynchrone :

{
  "id": "task-unified-example",
  "status": "pending",
  "created": 1785470400
}

Étape 2 : Vérifiez la tâche

curl https://api.evolink.ai/v1/tasks/task-unified-example \
  -H "Authorization: Bearer $EVOLINK_API_KEY"

{
  "id": "task-unified-example",
  "status": "completed",
  "results": [
    "https://example-cdn.com/generated-video.mp4"
  ]
}

Téléchargez le résultat dans les 24 heures. Copiez-le sur votre propre stockage durable si votre application en a besoin ultérieurement.

7. Comprendre le flux de travail asynchrone

La génération vidéo prend plus de temps qu'une requête HTTP normale. L'appel de création renvoie donc une tâche au lieu de maintenir la connexion ouverte jusqu'à ce que la vidéo soit terminée.

Submit request
      ↓
Receive task ID
      ↓
pending → processing
      ↓
completed or failed
      ↓
Download completed result

Le statut de la tâche peut être :

• pending : la demande est mise en file d'attente.
• processing : La génération est en cours.
• completed : le tableau results contient la sortie.
• failed : inspectez les informations d'erreur et décidez si la demande doit être corrigée ou réessayée.

Polling ou callback ?

• Utilisez HTTPS.
• Ne pas dépasser 2 048 caractères.
• Résolvez vers une destination publique, pas une adresse IP privée.
• Répondez dans les 10 secondes.
• Renvoie une réponse 2xx une fois l'événement accepté.

Les livraisons ayant échoué sont réessayées trois fois avec des délais d'environ 1, 2 et 4 secondes. Votre gestionnaire devrait être en sécurité si le même événement est reçu plus d'une fois.

8. Exemple de texte vers vidéo

La synthèse texte-vidéo accepte un prompt sans aucune entrée multimédia.

{
  "model": "minimax-h3-text-to-video",
  "prompt": "A ceramic coffee cup sits on a wooden table beside a window. Morning steam curls upward while the camera makes a slow clockwise orbit. Natural light, realistic texture, quiet editorial mood.",
  "quality": "2k",
  "aspect_ratio": "4:3",
  "duration": 8,
  "callback_url": "https://api.example.com/webhooks/evolink"
}

Les formats d'image pris en charge incluent :

• 21:9
• 16:9
• 4:3
• 1:1
• 3:4
• 9:16
• Adaptatif

9. Exemples d'image en vidéo

Animer une image de départ

{
  "model": "minimax-h3-image-to-video",
  "prompt": "The camera slowly moves closer as the fabric responds to a soft breeze. Preserve the product shape, label, and lighting.",
  "image_start": "https://assets.example.com/product-start.webp",
  "quality": "2k",
  "duration": 6
}

Générer vers une image de fin

{
  "model": "minimax-h3-image-to-video",
  "prompt": "A wide landscape shot gradually resolves into the supplied final frame, with continuous forward camera movement and stable natural lighting.",
  "image_end": "https://assets.example.com/landscape-end.jpg",
  "quality": "2k",
  "duration": 10
}

Contrôlez à la fois la première et la dernière image

{
  "model": "minimax-h3-image-to-video",
  "prompt": "The sealed package opens smoothly and the product rises into the final display position. Keep the logo legible and avoid sudden camera cuts.",
  "image_start": "https://assets.example.com/package-closed.png",
  "image_end": "https://assets.example.com/package-open.png",
  "quality": "2k",
  "duration": 8
}

Les images d'entrée doivent :

• Utilisez JPG, JPEG, PNG, WEBP, HEIC ou HEIF.
• Ne dépasse pas 30 Mo.
• Avoir une largeur et une hauteur comprises entre 256 et 5 760 pixels.
• Avoir un rapport largeur/hauteur compris entre 0,4 et 2,5.
• Être disponible à partir d’une URL HTTP(S) publique.

10. Exemple de vidéo de référence

La vidéo de référence accepte des tableaux ordonnés d’images, de vidéos et d’audio en option. Ce mode est utile lorsqu’un prompt seul ne suffit pas à décrire précisément le sujet, le mouvement ou le rythme.

{
  "model": "minimax-h3-reference-to-video",
  "prompt": "Use Image 1 for the main character and Image 2 for the wardrobe. Follow the camera movement and walking rhythm from Video 1. Use Audio 1 only as a pacing reference. The character crosses a modern gallery and stops beside a large window.",
  "image_urls": [
    "https://assets.example.com/character.jpg",
    "https://assets.example.com/wardrobe.jpg"
  ],
  "video_urls": [
    "https://assets.example.com/camera-reference.mp4"
  ],
  "audio_urls": [
    "https://assets.example.com/pacing-reference.mp3"
  ],
  "quality": "2k",
  "duration": 10
}

Limites de référence

• Jusqu'à 9 articles dans image_urls.
• Jusqu'à 3 articles dans video_urls.
• Jusqu'à 3 articles dans audio_urls.
• Pas plus de 12 fichiers de référence au total : un ensemble complet 9 + 3 + 3 est refusé.
• Au moins une image ou une vidéo est requise.
• L'audio ne peut pas être le seul type de référence.
• Les clips vidéo et audio de référence doivent chacun durer de 2 à 15 secondes.
• La durée totale de la vidéo de référence ne doit pas dépasser 15 secondes.
• La durée totale de l’audio de référence ne doit pas dépasser 15 secondes.
• Les vidéos de référence doivent utiliser MP4 ou MOV avec une vidéo H.264 ou H.265 et peuvent contenir de l'audio AAC ou MP3.
• Chaque vidéo de référence peut atteindre 50 Mo.
• Les dimensions de la vidéo de référence doivent être comprises entre 256 et 5 760 pixels par côté, avec un rapport largeur/hauteur de 0,4 à 2,5 et une fréquence d'images de 23,976 à 60 FPS.
• L'audio de référence doit utiliser WAV ou MP3 et peut atteindre 15 Mo par clip.
• Le corps complet de la requête JSON doit rester inférieur à 64 Mo.

Les images de référence suivent les mêmes règles de format, de taille, de dimension et d'URL que l'image vers la vidéo.

Faire référence aux médias par ordre de tableau

La durée de la vidéo de référence contribue à une utilisation facturable, évitez donc de joindre des clips plus longs que ce dont la tâche a besoin.

11. Téléchargez des ressources locales

Les routes de génération nécessitent des URL de médias HTTP(S) publiques. Pour utiliser un fichier à partir d'un disque local ou d'une application privée, envoyez-le d'abord au service de fichiers EvoLink.

curl -X POST https://files-api.evolink.ai/api/v1/files/upload/stream \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -F "file=@./product-start.png"

12. Implémentation complète de TypeScript

Exécutez cet exemple dans un environnement de serveur approuvé sur Node.js 18 ou version ultérieure.

const API_BASE = "https://api.evolink.ai";

type TaskStatus = "pending" | "processing" | "completed" | "failed";

interface VideoTask {
  id: string;
  status: TaskStatus;
  results?: string[];
  error?: {
    code?: string;
    message?: string;
  };
}

interface BaseRequest {
  prompt: string;
  quality?: "2k";
  duration?: number;
  callback_url?: string;
}

type AspectRatio =
  | "adaptive"
  | "21:9"
  | "16:9"
  | "4:3"
  | "1:1"
  | "3:4"
  | "9:16";

// Un type par route, pour qu'une combinaison de champs invalide ne compile pas.
interface TextToVideoRequest extends BaseRequest {
  model: "minimax-h3-text-to-video";
  aspect_ratio?: AspectRatio;
}

interface ImageToVideoRequest extends BaseRequest {
  model: "minimax-h3-image-to-video";
  image_start?: string;
  image_end?: string;
  // Pas d'aspect_ratio : la route rejette le champ et déduit le ratio
  // à partir de l'image d'entrée.
}

interface ReferenceToVideoRequest extends BaseRequest {
  model: "minimax-h3-reference-to-video";
  aspect_ratio?: AspectRatio;
  image_urls?: string[];
  video_urls?: string[];
  audio_urls?: string[];
}

type VideoRequest =
  | TextToVideoRequest
  | ImageToVideoRequest
  | ReferenceToVideoRequest;

function getApiKey(): string {
  const apiKey = process.env.EVOLINK_API_KEY;

  if (!apiKey) {
    throw new Error("EVOLINK_API_KEY is not configured");
  }

  return apiKey;
}

async function requestJson<T>(
  path: string,
  init?: RequestInit,
): Promise<T> {
  const response = await fetch(`${API_BASE}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${getApiKey()}`,
      "Content-Type": "application/json",
      ...init?.headers,
    },
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`EvoLink request failed (${response.status}): ${body}`);
  }

  return response.json() as Promise<T>;
}

async function submitVideo(payload: VideoRequest): Promise<VideoTask> {
  return requestJson<VideoTask>("/v1/videos/generations", {
    method: "POST",
    body: JSON.stringify(payload),
  });
}

async function getTask(taskId: string): Promise<VideoTask> {
  return requestJson<VideoTask>(
    `/v1/tasks/${encodeURIComponent(taskId)}`,
  );
}

function wait(milliseconds: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, milliseconds));
}

async function waitForVideo(
  taskId: string,
  timeoutMs = 10 * 60 * 1000,
  pollIntervalMs = 5_000,
): Promise<string> {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const task = await getTask(taskId);

    if (task.status === "completed") {
      const resultUrl = task.results?.[0];

      if (!resultUrl) {
        throw new Error("Task completed without a result URL");
      }

      return resultUrl;
    }

    if (task.status === "failed") {
      throw new Error(task.error?.message ?? "Video generation failed");
    }

    await wait(pollIntervalMs);
  }

  throw new Error(`Timed out while waiting for task ${taskId}`);
}

async function main(): Promise<void> {
  const task = await submitVideo({
    model: "minimax-h3-text-to-video",
    prompt:
      "A slow aerial approach toward a coastal observatory at sunrise, " +
      "natural cloud movement, cinematic wide shot",
    quality: "2k",
    aspect_ratio: "16:9",
    duration: 6,
  });

  const videoUrl = await waitForVideo(task.id);
  console.log(videoUrl);
}

void main();

Pour les systèmes à volume élevé, remplacez les interrogations côté application par des callbacks et un enregistrement de tâche durable. Conservez l'ID de tâche comme lien principal entre votre demande, votre enregistrement de facturation, vos journaux et votre résultat.

13. Implémentation complète de Python

import os
import time
from typing import NotRequired, TypedDict, cast

import requests

API_BASE = "https://api.evolink.ai"
API_KEY = os.environ["EVOLINK_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


class VideoError(TypedDict):
    code: NotRequired[str]
    message: NotRequired[str]


class VideoTask(TypedDict):
    id: str
    status: str
    results: NotRequired[list[str]]
    error: NotRequired[VideoError]


class VideoPayload(TypedDict):
    model: str
    prompt: str
    image_start: NotRequired[str]
    quality: NotRequired[str]
    duration: NotRequired[int]


def submit_video(payload: VideoPayload) -> VideoTask:
    response = requests.post(
        f"{API_BASE}/v1/videos/generations",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return cast(VideoTask, response.json())


def get_task(task_id: str) -> VideoTask:
    response = requests.get(
        f"{API_BASE}/v1/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    return cast(VideoTask, response.json())


def wait_for_video(
    task_id: str,
    timeout_seconds: int = 600,
    poll_interval_seconds: int = 5,
) -> str:
    deadline = time.monotonic() + timeout_seconds

    while time.monotonic() < deadline:
        task = get_task(task_id)
        status = task["status"]

        if status == "completed":
            results = task.get("results", [])
            if not results:
                raise RuntimeError("Task completed without a result URL")
            return str(results[0])

        if status == "failed":
            error = task.get("error", {})
            message = error.get("message", "Video generation failed")
            raise RuntimeError(message)

        time.sleep(poll_interval_seconds)

    raise TimeoutError(f"Timed out while waiting for task {task_id}")


task = submit_video(
    {
        "model": "minimax-h3-image-to-video",
        "prompt": (
            "The camera slowly orbits the product while the background "
            "light shifts from warm to cool. Preserve the product design."
        ),
        "image_start": "https://assets.example.com/product.webp",
        "quality": "2k",
        "duration": 8,
    }
)

print(wait_for_video(task["id"]))

Cet exemple reste léger en matière de dépendance tout en déclarant les champs qu'il consomme. Dans un service Python plus grand, validez la réponse complète avec Pydantic avant de la stocker.

14. Référence rapide des paramètres et des prompts

Prise en charge des paramètres

Modèle de prompt : texte vers vidéo

[subject] + [action] + [environment] + [camera movement] +
[lighting] + [visual mood]

Exemple:

Un cycliste traverse un pont suspendu au-dessus d'une forêt brumeuse à l'aube. La caméra suit de dos, puis s'élève dans une large vue aérienne. Lumière naturelle douce et mouvement réaliste.

Modèle de prompt : image vers vidéo

[motion to add] + [camera movement] + [elements to preserve] +
[transition or ending state]

Exemple:

La caméra effectue un lent demi-cercle autour de la chaise tandis que la lumière du soleil se déplace sur le sol. Préservez la forme, le matériau et la couleur exacts de la chaise.

Modèle de prompt : vidéo de référence

Use [Image/Video/Audio number] for [specific purpose].
[Describe the new scene, action, camera, and final composition.]

Exemple:

Utilisez l'image 1 pour le personnage, l'image 2 pour le véhicule et la vidéo 1 pour le mouvement de la caméra. Le personnage sort du véhicule dans un désert calme au coucher du soleil tandis que la caméra réalise le même arc vers l'avant que la vidéo 1.

15. Erreurs et correctifs courants

Réessayez uniquement les erreurs qui peuvent aboutir sans modifier la demande, telles que des pannes de réseau temporaires ou des limites de débit. Les paramètres invalides et les médias non pris en charge doivent être corrigés avant une autre soumission.

16. Tarification et planification des coûts

À des fins de planification :

• Une durée de sortie plus longue augmente le travail demandé.
• La vidéo de référence peut également facturer la durée de la vidéo de référence d’entrée.
• Utilisez la durée utile la plus courte lors de la validation d’un prompt ou d’un flux de travail.
• Effectuez quelques générations de test et examinez les résultats avant de lancer un lot important.
• Enregistrez pour chaque tâche le mode, la durée de sortie, la durée de la vidéo de référence, le statut et le coût.
• Séparez les générations échouées des résultats utilisables lorsque vous calculez le coût par vidéo exploitable.

L'API unifiée d'EvoLink permet également à une équipe de production de comparer H3 avec d'autres modèles vidéo sans remplacer l'authentification, le suivi des tâches et l'intégration de la facturation.

17. Liste de contrôle de production

Avant l'expédition :

• Conservez la clé API sur le serveur.
• Validez tous les paramètres spécifiques au mode avant la soumission.
• Confirmez que les URL des médias sont publiques et restent disponibles pendant la génération.
• Définissez les délais d’expiration des requêtes.
• Fréquence d'interrogation liée et durée totale d'interrogation.
• Reculez après 429 et des erreurs de serveur transitoires.
• Enregistrez l'ID de la tâche avant de commencer l'interrogation.
• Ne présumez pas qu’une tâche H3 peut être annulée ; le contrat de tâche actuel rapporte can_cancel: false.
• Traitez les Callbacks comme des événements répétables.
• Renvoie une réponse de Callback 2xx uniquement après avoir accepté l'événement.
• Conservez les vidéos terminées avant l’expiration de leurs URL temporaires.
• Enregistrez l'ID du modèle, la durée, les références d'entrée, l'état et le résultat.
• Appliquez la simultanéité et les contrôles budgétaires au niveau du compte.
• Ne dépendez pas d’en-têtes ou de paramètres de sortie non documentés.

18. Cas d'utilisation pratiques

19. FAQ

Comment accéder à l'API MiniMax H3 ?

Quel identifiant de modèle MiniMax H3 dois-je utiliser ?

Le MiniMax H3 prend-il en charge la vidéo 2K ?

L'API prend-elle en charge la 4K ou 60 FPS ?

Ces contrôles ne font pas partie du contrat actuel de l'API H3. N'envoyez pas de paramètres de qualité, de fréquence d'images, de débit binaire ou de codec non documentés.

Quelle est la durée maximale d'une vidéo ?

La plage de durée actuelle est comprise entre 5 et 15 secondes, en utilisant une valeur entière.

Puis-je télécharger une image locale ?

L'API de génération accepte-t-elle les images Base64 ?

Non. Utilisez une URL HTTP(S) publique.

Combien de références puis-je utiliser ?

La vidéo de référence accepte jusqu'à 9 images, 3 vidéos et 3 fichiers audio, sous réserve des limites par fichier et de durée totale.

Puis-je générer une vidéo à partir d’une seule référence audio ?

Non. Une demande de référence doit inclure au moins une image ou une vidéo. L'audio peut être ajouté comme autre référence.

Comment puis-je vérifier l'état de la génération ?

Combien de temps l'URL de la vidéo générée est-elle disponible ?

L'URL du résultat est disponible pendant 24 heures. Téléchargez la vidéo ou déplacez-la vers votre propre stockage avant son expiration.

Puis-je utiliser MiniMax H3 à partir de JavaScript ou de Python ?

Oui. L'API est HTTPS standard et peut être appelée à partir de n'importe quel environnement côté serveur prenant en charge les requêtes JSON et l'authentification Bearer.

Dois-je interroger la tâche ou utiliser un callback ?

L'interrogation est pratique pour les tests et les scripts à faible volume. Les Callbacks sont généralement plus efficaces pour les files d’attente de production et les charges de travail plus importantes.

Commencer l’intégration

• Essayez MiniMax H3 et examinez les détails du modèle
• Créer une clé API EvoLink
• Consultez les prix actuels du MiniMax H3
• Ouvrez la référence de l'API texte-vidéo
• Ouvrez la référence de l'API image-vidéo
• Ouvrez la référence de l'API de vidéo de référence