MiniMax H3 API 使用指南

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

EVOLINK_API_KEY=your_api_key

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": "一辆紧凑型电动概念车驶过雨夜城市。镜头在车旁跟随，随后缓慢拉远，展示街道上的霓虹倒影。",
    "quality": "2k",
    "aspect_ratio": "16:9",
    "duration": 5
  }'

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

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"
  ]
}

提交请求
   ↓
取得任务 ID
   ↓
pending → processing
   ↓
completed 或 failed
   ↓
下载已完成的结果

{
  "model": "minimax-h3-text-to-video",
  "prompt": "一个陶瓷咖啡杯放在窗边的木桌上。晨光中蒸汽缓慢上升，镜头围绕杯子顺时针移动。自然光、真实材质、安静的编辑风格。",
  "quality": "2k",
  "aspect_ratio": "4:3",
  "duration": 8,
  "callback_url": "https://api.example.com/webhooks/evolink"
}

{
  "model": "minimax-h3-image-to-video",
  "prompt": "镜头缓慢靠近，布料在微风中自然摆动。保持产品形状、标签和光线不变。",
  "image_start": "https://assets.example.com/product-start.webp",
  "quality": "2k",
  "duration": 6
}

{
  "model": "minimax-h3-image-to-video",
  "prompt": "从远景开始，镜头持续向前移动，画面逐渐过渡到提供的最终帧，并保持自然光线稳定。",
  "image_end": "https://assets.example.com/landscape-end.jpg",
  "quality": "2k",
  "duration": 10
}

{
  "model": "minimax-h3-image-to-video",
  "prompt": "密封包装平稳打开，产品升起到最终展示位置。保持 Logo 清晰，避免突然切换镜头。",
  "image_start": "https://assets.example.com/package-closed.png",
  "image_end": "https://assets.example.com/package-open.png",
  "quality": "2k",
  "duration": 8
}

{
  "model": "minimax-h3-reference-to-video",
  "prompt": "使用 Image 1 作为主角，使用 Image 2 作为服装参考。沿用 Video 1 的运镜和行走节奏，Audio 1 仅作为节奏参考。角色走过现代美术馆，停在一扇落地窗旁。",
  "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
}

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

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";

// 每个路由对应一个类型，非法的字段组合无法通过编译。
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;
  // 没有 aspect_ratio：该路由会拒绝此字段，并根据输入图片
  // 推导画面比例。
}

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();

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"]))

[主体] + [动作] + [环境] + [镜头运动] + [光线] + [视觉氛围]

[需要增加的运动] + [镜头运动] + [必须保留的元素] + [转场或结束状态]

使用 [Image/Video/Audio 编号] 作为 [具体用途]。
[描述新场景、动作、镜头和最终构图。]