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": "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
  }'

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

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

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

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

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

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

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

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

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

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

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