MiniMax

Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation
인증: Tokenhub API Key / Bearer

MiniMax H3는 텍스트, 이미지, 영상, 오디오 참조로 영상을 생성합니다. H3 Max는 텍스트와 첫 프레임 / 끝 프레임 입력을 지원합니다.

기본 정보

버전별 지원 규격

입력 모드

해상도 변환

H3 Max는 중간 프레임과 멀티모달 참조 입력을 지원하지 않습니다.

호출 절차

동영상 생성은 시간이 오래 걸리는 작업(일반적으로 1~3분)이므로 API는 비동기 호출 방식을 사용하며, 다음 두 단계로 구성됩니다.

1. 작업 제출: POST /v1/wand/minimax-video-v2/generation을 호출하며, 성공하면 task_id가 반환됩니다.

2. 결과 폴링: task.status = succeeded가 될 때까지 task_id로 작업 결과 조회 API를 호출하고 task.content.url에서 동영상 URL을 가져옵니다.

참고: 모든 API 응답에는 문제 해결에 사용되는 최상위 request_id가 포함됩니다. 조회 API는 사용량(tokenhub_usage.total_tokens 포함)을 나타내는 tokenhub_usage도 반환합니다. 작업 상태 열거형은 queued / running / succeeded / failed / cancelled이며 실제 응답을 기준으로 합니다.

텍스트-동영상

API 설명

텍스트 프롬프트만 사용하여 동영상을 생성하려면 프롬프트에서 카메라 움직임 등의 카메라 표현을 자연어로 직접 설명합니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation

요청 파라미터

요청 예시

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-video-h3",
  "content": [
    {
      "type": "text",
      "text": "An orange kitten on the windowsill looks toward the camera"
    }
  ],
  "resolution": "2K",
  "duration": 6,
  "ratio": "16:9"
}'

참고: 고속 버전을 호출하려면 예시의 model을 minimax-video-h3-max로 바꾸십시오. h3-max는 2K 또는 4초 길이를 지원하지 않습니다.

응답 파라미터

참고: 제출 응답에는 base_resp가 포함되지 않습니다. 제출 성공 여부는 HTTP 상태 코드와 task_id 반환 여부로 판단합니다.

응답 예시

{
  "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}

오류 코드

요청이 실패하면 오류 코드가 반환됩니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다. 작업이 성공적으로 제출된 후 생성 단계의 작업 상태는 "작업 결과 조회" API를 통해 확인할 수 있습니다.

이미지-동영상(첫 프레임 / 첫 프레임과 마지막 프레임)

API 설명

이미지를 첫 프레임으로 사용하고 선택적으로 마지막 프레임으로도 지정한 후 텍스트 프롬프트와 결합하여 동영상을 생성합니다. 출력 종횡비는 입력 이미지를 따릅니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation

요청 파라미터

참고: minimax-video-h3-max는 첫 프레임과 마지막 프레임을 지원하지만 중간 프레임은 지원하지 않습니다.

요청 예시

첫 프레임과 마지막 프레임 생성:

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-video-h3",
  "content": [
    {
      "type": "text",
      "text": "Transition naturally from the first frame to the last frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/start.jpg"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/end.jpg"
      },
      "role": "last_frame"
    }
  ],
  "resolution": "768P",
  "duration": 6
}'

응답 파라미터

"텍스트-동영상"의 출력 파라미터와 동일합니다.

응답 예시

{
  "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}

오류 코드

요청이 실패하면 오류 코드가 반환됩니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다. 작업 상태 설명은 "텍스트-동영상"과 동일합니다.

멀티모달 참조-동영상(H3 전용)

API 설명

텍스트와 참조 이미지, 참조 동영상 또는 참조 오디오를 조합하여 동영상을 생성합니다. 이 기능은 minimax-video-h3만 지원합니다. minimax-video-h3-max는 멀티모달 참조 입력을 지원하지 않으며 content에 reference_image, reference_video 또는 reference_audio가 있으면 파라미터 오류가 즉시 반환됩니다. 오디오만 입력할 수 없습니다. 참조 동영상 또는 이미지가 하나 이상 포함되어야 합니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation

요청 파라미터

content 배열 요소의 하위 필드:

참고: 이미지-동영상과 멀티모달 참조 생성은 상호 배타적입니다. content에 reference_image / reference_video / reference_audio 역할 중 하나라도 있으면 first_frame / last_frame을 사용할 수 없으며 그 반대도 마찬가지입니다. 참조 동영상: MP4 / MOV(H.264 / H.265), 50 MB 이하, 최대 3개 세그먼트, 각 세그먼트 2~15초이면서 총길이 15초 이하, 너비와 높이 해상도 256~5760 px, 프레임 속도 23.976~60 fps. 참조 오디오: WAV / MP3, 15 MB 이하, 최대 3개 세그먼트, 각 세그먼트 2~15초이면서 총길이 15초 이하. 오디오만 입력할 수 없습니다. 전체 요청 본문 크기는 64 MB를 초과할 수 없습니다. 큰 파일에는 Base64 대신 공개 네트워크 URL을 사용합니다.

요청 예시

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-video-h3",
  "content": [
    {
      "type": "text",
      "text": "The character in the reference image moves naturally within the scene of the reference video"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/character.jpg"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/scene.mp4"
      },
      "role": "reference_video"
    }
  ],
  "resolution": "768P",
  "duration": 6,
  "ratio": "16:9"
}'

응답 파라미터

"텍스트-동영상"의 출력 파라미터와 동일합니다.

응답 예시

{
  "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}

오류 코드

요청이 실패하면 오류 코드가 반환됩니다. 구체적인 오류 코드와 처리 권장 사항은 "부록: 통합 오류 코드"를 참조합니다. 작업 상태 설명은 "텍스트-동영상"과 동일합니다.

작업 결과 조회

API 설명

모든 생성 기능이 공유하는 작업 조회 방식입니다. 작업을 제출하여 task_id가 반환되면 통합 작업 조회 엔드포인트를 통해 작업 상태를 폴링합니다. 성공하면 결과에서 동영상 URL을 가져옵니다.

API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/tasks/{task_id}

참고: 경로의 {task_id}는 작업 제출 시 반환된 task_id이며 예시에서는 YOUR_TASK_ID로 표시됩니다. 동영상 생성에는 약 1~3분이 걸리므로 3~5초마다 폴링하는 것이 좋습니다.

요청 파라미터

요청 예시

curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/tasks/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

응답 파라미터

참고: 조회 응답은 base_resp 또는 최상위 status가 없는 task 객체입니다. 작업 식별자와 상태는 task.id / task.status에 있습니다.

응답 예시

생성 성공:

{
  "task": {
    "id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
    "model": "MiniMax-H3-Max",
    "task_type": "generation",
    "status": "succeeded",
    "created_at": 1772345678,
    "updated_at": 1772345810,
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
    "content": {
      "url": "https://example.com/output-video.mp4"
    },
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    }
  },
  "tokenhub_usage": {
    "total_tokens": 102655
  },
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}

오류 코드

요청 수준 오류 코드는 "부록: 통합 오류 코드"를 참조합니다.

부록

통합 오류 코드

일반 자료 제약 조건

이미지: JPG / JPEG / PNG / WEBP / HEIC / HEIF, 30 MB 이하, 너비와 높이 256~5760 px, 종횡비 0.4~2.5, 첫 프레임 최대 1개, 마지막 프레임 최대 1개, 참조 이미지 최대 9개.

동영상(참조 동영상, h3 전용): MP4 / MOV(H.264 / H.265, 오디오 AAC / MP3), 50 MB 이하, 최대 3개 세그먼트, 각 세그먼트 2~15초이면서 총길이 15초 이하, 너비와 높이 256~5760 px, 종횡비 0.4~2.5, 프레임 속도 23.976~60 fps.

오디오(참조 오디오, h3 전용): WAV / MP3, 15 MB 이하, 최대 3개 세그먼트, 각 세그먼트 2~15초이면서 총길이 15초 이하.

참고: 전체 요청 본문 크기는 64 MB를 초과할 수 없습니다. 큰 파일에는 Base64 대신 공개 네트워크 URL을 사용합니다.

FAQ

1. 두 모델 중 어떤 모델을 선택해야 합니까?

• 2K 직접 출력, 멀티모달 참조(참조 이미지/동영상/오디오), 최소 길이 4초가 필요한 경우: minimax-video-h3.

• 멀티모달 참조 없이 H3 화질과 더 빠른 생성 및 더 낮은 비용이 필요한 경우: minimax-video-h3-max.

2. 길이와 해상도 제한은 무엇입니까?

• h3: 길이 4~15초, 해상도 768P / 2K(1080P 입력은 768P로 다운그레이드되고 4K는 2K로 다운그레이드됨).

• h3-max: 길이 5~15초(4초는 지원되지 않음), 해상도는 480P / 768P만 지원하며 1080P / 2K / 4K 입력은 별도 알림 없이 768P로 다운그레이드됩니다.

3. 카메라 움직임은 어떻게 제어합니까?

프롬프트에서 "카메라가 천천히 줌인한다" 또는 "카메라가 왼쪽으로 패닝한다"와 같이 카메라 움직임을 자연어로 설명합니다. 특별한 명령 구문은 필요하지 않습니다.

4. 생성된 동영상 링크는 만료됩니까?

링크는 만료됩니다. 생성 결과는 12시간 동안 유효한 임시 주소입니다. 작업이 성공하면 동영상 파일을 즉시 다운로드하여 자체 스토리지로 전송하십시오. 장기간 사용을 위해 이 링크에 의존하지 마십시오.