Tạo video MiniMax H3 với Flatkey

URL cơ sở: https://router.flatkey.ai Sử dụng MiniMax-H3 khi bạn cần chuyển văn bản thành video, kiểm soát khung đầu và khung cuối, hoặc tham chiếu hình ảnh, video và âm thanh. Mọi yêu cầu đều theo cùng một quy trình bất đồng bộ: tạo tác vụ, kiểm tra trạng thái, rồi tải xuống file MP4 hoàn chỉnh.

Đầu vào linh hoạt

Tạo từ văn bản, hình ảnh khung, hoặc hình ảnh, video và âm thanh tham chiếu.

Một quy trình bất đồng bộ

Tạo bằng POST /v1/videos, kiểm tra bằng GET /v1/videos/{task_id}, và tải xuống từ metadata.url.

Sử dụng header này cho các yêu cầu tạo tác vụ và kiểm tra trạng thái:

Authorization: Bearer YOUR_FLATKEY_API_KEY

Giữ bí mật API key của bạn. Không dán nó vào nhật ký công khai, trang web hoặc phiếu hỗ trợ.

Tạo video H3 đầu tiên của bạn

1. Gửi tác vụ chuyển văn bản thành video

Gửi POST /v1/videos với model MiniMax-H3 và một prompt văn bản. Các yêu cầu chỉ có văn bản cần có tỷ lệ khung hình rõ ràng khác với adaptive.

curl --fail-with-body -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A paper boat crosses a rain puddle in a cinematic macro shot"
      }
    ],
    "resolution": "768P",
    "duration": 6,
    "ratio": "16:9",
    "aigc_watermark": false
  }'

curl.exe --fail-with-body -sS https://router.flatkey.ai/v1/videos `
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
  -H "Content-Type: application/json" `
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A paper boat crosses a rain puddle in a cinematic macro shot"
      }
    ],
    "resolution": "768P",
    "duration": 6,
    "ratio": "16:9",
    "aigc_watermark": false
  }'

Phản hồi chứa ID tác vụ công khai trong cả id và task_id:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "task_id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0
}

Lưu lại giá trị task_... được trả về. Bạn cần nó để kiểm tra tác vụ sau này.

2. Kiểm tra và tải xuống kết quả

Kiểm tra GET /v1/videos/{task_id} cho đến khi status trở thành completed hoặc failed. Khi là completed, đọc URL tải xuống tạm thời từ metadata.url.

TASK_ID="task_3f9a00000000000000000000000000e2"

curl --fail-with-body -sS \
  "https://router.flatkey.ai/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

# Run the status request again until status is completed.
# Then copy metadata.url from the response and paste it below.
VIDEO_URL="PASTE_METADATA_URL_HERE"
curl --fail --location "$VIDEO_URL" --output minimax-h3.mp4

$taskId = "task_3f9a00000000000000000000000000e2"

while ($true) {
  $result = curl.exe --fail-with-body -sS `
    "https://router.flatkey.ai/v1/videos/$taskId" `
    -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" | ConvertFrom-Json
  Write-Host "status: $($result.status)"

  if ($result.status -eq "completed") { break }
  if ($result.status -eq "failed") {
    $result | ConvertTo-Json -Depth 10
    exit 1
  }
  Start-Sleep -Seconds 5
}

curl.exe --fail --location $result.metadata.url --output minimax-h3.mp4

metadata.url là URL tải xuống tạm thời. Nó hoạt động mà không cần header xác thực Flatkey, vì vậy bất kỳ ai có nó đều có thể truy cập video đã tạo cho đến khi hết hạn. Hãy coi nó là thông tin riêng tư, và không ghi nhật ký, xuất bản hoặc chia sẻ nó. Tải xuống video ngay và lưu trữ trong bộ nhớ của riêng bạn. Việc lặp lại truy vấn tác vụ không làm mới URL đã hết hạn.

Chọn đầu vào của bạn

Mọi yêu cầu đều phải chứa một mục văn bản không rỗng. Bạn có thể thêm hình ảnh khung hoặc phương tiện tham chiếu để kiểm soát kết quả.

Đầu vào	`type`	`role` bắt buộc	Giới hạn
Prompt	`text`	Không đặt role	7.000 ký tự Unicode trên tất cả các mục văn bản
Khung đầu	`image_url`	`first_frame`, hoặc bỏ qua role	1 hình ảnh
Khung cuối	`image_url`	`last_frame`	1 hình ảnh
Hình ảnh tham chiếu	`image_url`	`reference_image`	9 hình ảnh
Video tham chiếu	`video_url`	`reference_video`	3 video
Âm thanh tham chiếu	`audio_url`	`reference_audio`	3 file âm thanh; cũng cần bao gồm hình ảnh hoặc video tham chiếu

Không kết hợp đầu vào khung đầu/khung cuối với đầu vào tham chiếu trong cùng một yêu cầu. Mỗi mục content phải chứa đúng một payload khớp với type của nó.

Kiểm soát khung đầu và khung cuối

Sử dụng first_frame và last_frame khi bạn muốn video nội suy giữa hai hình ảnh.

curl --fail-with-body -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "The camera slowly pulls back as morning fog crosses the valley"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/first.jpg" },
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/last.jpg" },
        "role": "last_frame"
      }
    ],
    "resolution": "2K",
    "duration": 8,
    "ratio": "adaptive"
  }'

Tạo với phương tiện tham chiếu

Đầu vào tham chiếu giúp giữ nguyên chủ thể, phong cách chuyển động hoặc âm thanh. Âm thanh tham chiếu không thể là đầu vào phương tiện duy nhất.

curl --fail-with-body -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "Keep the character and movement style consistent while crossing a snowy street"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/character.jpg" },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/motion.mp4" },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": { "url": "https://example.com/ambience.mp3" },
        "role": "reference_audio"
      }
    ],
    "resolution": "768P",
    "duration": 10,
    "ratio": "adaptive"
  }'

Cài đặt yêu cầu

Trường	Bắt buộc	Giá trị được hỗ trợ
`model`	Có	`MiniMax-H3`
`content`	Có	Văn bản cộng với phương tiện khung hoặc tham chiếu tùy chọn
`resolution`	Có	`768P` hoặc `2K`; giá trị phân biệt chữ hoa chữ thường
`duration`	Có	Một số nguyên từ `4` đến `15` giây
`ratio`	Đối với yêu cầu chỉ có văn bản	`21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, hoặc `adaptive` khi có phương tiện
`aigc_watermark`	Không	`true` hoặc `false`

Khi một yêu cầu chứa phương tiện và bỏ qua ratio, Flatkey sẽ sử dụng adaptive. Yêu cầu chỉ có văn bản phải sử dụng rõ ràng một tỷ lệ khác adaptive.

Hiểu kết quả tác vụ

`status`	Ý nghĩa
`queued`	Tác vụ đang chờ chạy.
`in_progress`	Video đang được tạo. Đọc `progress` để lấy giá trị từ 0 đến 100.
`completed`	Video đã sẵn sàng tại `metadata.url`.
`failed`	Quá trình tạo thất bại. Đọc `error.code` và `error.message`.

Đối với các phản hồi video H3, tên trường sử dụng chung biểu thị số giây:

usage.completion_tokens là thời lượng đầu ra được tạo.
usage.total_tokens là tổng thời lượng tính phí, bao gồm thời gian đầu vào video tham chiếu.

Các giá trị này là số giây, không phải token của mô hình ngôn ngữ. Kiểm tra Nhật ký sử dụng trong Flatkey Console để xem khoản phí cuối cùng.

Giới hạn hiện tại

callback_url không được hỗ trợ. Hãy kiểm tra trạng thái tác vụ thay thế.
Liệt kê tác vụ, hủy, xóa, tạo lại và remix không được hỗ trợ.
MiniMax-H3-Context-IR không được hỗ trợ.
URL phương tiện từ xa phải có thể truy cập trong khi tác vụ đang được xử lý.

Mã lỗi	Cần kiểm tra
`invalid_duration`	Đặt `duration` từ `4` đến `15`.
`invalid_resolution`	Sử dụng chính xác `768P` hoặc `2K`.
`invalid_ratio`	Sử dụng tỷ lệ được hỗ trợ. Yêu cầu chỉ có văn bản không thể bỏ qua hoặc sử dụng `adaptive`.
`invalid_content`	Kiểm tra prompt, role, giới hạn phương tiện và các tổ hợp đầu vào không tương thích.
`unsupported_callback_url`	Xóa `callback_url` và kiểm tra trạng thái tác vụ.

Bắt đầu nhanh

Mã nguồn

Công cụ AI phổ biến

Tạo nội dung đa phương tiện

Mô hình phổ biến

Bảng điều khiển

Tham chiếu

Tạo video MiniMax H3 với Flatkey

Đầu vào linh hoạt

Một quy trình bất đồng bộ

Tạo video H3 đầu tiên của bạn

1. Gửi tác vụ chuyển văn bản thành video

2. Kiểm tra và tải xuống kết quả

Chọn đầu vào của bạn

Kiểm soát khung đầu và khung cuối

Tạo với phương tiện tham chiếu

Cài đặt yêu cầu

Hiểu kết quả tác vụ

Giới hạn hiện tại

Đầu vào linh hoạt

Một quy trình bất đồng bộ

​Tạo video H3 đầu tiên của bạn

​1. Gửi tác vụ chuyển văn bản thành video

​2. Kiểm tra và tải xuống kết quả

​Chọn đầu vào của bạn

​Kiểm soát khung đầu và khung cuối

​Tạo với phương tiện tham chiếu

​Cài đặt yêu cầu

​Hiểu kết quả tác vụ

​Giới hạn hiện tại

Tạo video H3 đầu tiên của bạn

1. Gửi tác vụ chuyển văn bản thành video

2. Kiểm tra và tải xuống kết quả

Chọn đầu vào của bạn

Kiểm soát khung đầu và khung cuối

Tạo với phương tiện tham chiếu

Cài đặt yêu cầu

Hiểu kết quả tác vụ

Giới hạn hiện tại