Hy

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

Hy Video 1.5는 텍스트 또는 첫 프레임 이미지로 영상을 생성합니다.

기본 정보

버전별 지원 규격

입력 모드

호출 절차

동영상 생성은 시간이 오래 걸리는 작업이므로 API는 비동기 호출 방식을 사용하며, 다음 두 단계로 나뉩니다.

1. 작업 제출: 동영상 생성 API를 호출합니다. 성공하면 task_id(작업 ID)와 request_id가 반환됩니다.

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

참고: 이 API 시리즈의 응답은 통합 code / message / data 응답 구조를 사용하지 않습니다. 제출에 성공하면 {"task_id": "...", "created": ..., "request_id": "..."}가 반환되고, 조회 시 작업 객체(task_id / status / videos / usage 등의 필드 포함)가 반환됩니다. 작업 상태 값은 queued(스케줄링 대기) / running(생성 중) / succeeded(성공) / failed(실패)로 통일됩니다.

동영상 생성

API 설명

텍스트-동영상 또는 이미지-동영상 작업을 제출합니다. 이미지를 제공하지 않으면 텍스트-동영상 작업이고, image(Base64) 또는 image_url(이미지 URL)을 제공하면 이미지-동영상 작업입니다.

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

요청 파라미터

참고: 위 표에 나열된 필드 외에 인식되지 않는 다른 필드는 모델 서비스에 그대로 전달됩니다.

요청 예시

텍스트-동영상:

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "hy-video-v1.5",
  "prompt": "A puppy is running on the grass under bright sunshine."
  "negative_prompt": "blurry, distorted"
  "aspect_ratio": "16:9"
}'

이미지-동영상(이미지 URL):

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "hy-video-v1.5",
  "prompt": "Make the subject in the image turn its head naturally, with a gentle breeze blowing through its hair."
  "image_url": "https://example.com/start.jpg"
}'

이미지-동영상(이미지 Base64):

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/hunyuan-video/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "hy-video-v1.5",
  "prompt": "The camera slowly moves in",
  "image": "<BASE64_ENCODED_IMAGE>"
}'

응답 파라미터

제출에 성공하면 다음 항목이 반환됩니다.

제출에 실패하면 통합 오류 응답 구조가 반환됩니다.

응답 예시

제출 성공:

{
  "task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
  "created": 1787108411,
  "request_id": "835a268e-af02-4615-a30b-7e4b815e8839"
}

제출 실패:

{
  "task_id": "",
  "status": "failed",
  "error": {
    "code": "1300",
    "message": "Trigger the platform strategy"
  }
}

오류 코드

요청이 실패하면 {"task_id":"","status":"failed","error":{...}} 형식의 응답 구조가 반환됩니다. 구체적인 오류 코드와 처리 권장 사항은 부록: 통합 오류 코드를 참조합니다. 작업 제출에 성공한 후 생성 단계의 작업 상태는 작업 결과 조회 API를 통해 확인할 수 있습니다.

작업 결과 조회

API 설명

작업이 제출되고 작업 ID가 반환되면 작업 조회 엔드포인트를 통해 작업 상태를 폴링합니다. 성공하면 결과에서 동영상 URL을 가져옵니다.

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

참고: 경로의 {task_id}는 작업 제출 시 반환된 task_id입니다. 동영상 생성에는 약 몇 분이 걸리므로 3~5초마다 폴링하는 것이 좋습니다. 응답은 모델 측 반환 패킷을 그대로 전달하면서 플랫폼에서 정규화한 필드를 추가한 것이며, 다음 표에 나열되지 않은 원본 공급업체 필드가 포함될 수 있습니다. 실제 반환 응답을 기준으로 합니다.

요청 파라미터

요청 예시

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

응답 파라미터

응답 예시

생성 중(running):

{
  "created": 1787108411,
  "error": null,
  "task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
  "status": "running",
  "request_id": "252e94a8-dbce-4440-8747-e36f52e0fc29"
}

생성 성공:

{
  "created": 1787108411,
  "error": null,
  "task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
  "status": "succeeded",
  "videos": [
    {
      "audio_url": "",
      "generate_info": "",
      "url": "https://result.example.com/generated-image.png"
    }
  ],
  "tokenhub_usage": {
    "total_tokens": 150000
  },
  "request_id": "252e94a8-dbce-4440-8747-e36f52e0fc29"
}

생성 실패:

{
  "created": 1787108411,
  "task_id": "251435731-WandVideo-05c42d57d3a74c1fa39d56ff59b31e20",
  "status": "failed",
  "error": {
    "code": "InternalServiceError",
    "message": "generate video failed"
  },
  "request_id": "252e94a8-dbce-4440-8747-e36f52e0fc29"
}

오류 코드

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

부록

통합 오류 코드

FAQ

1. 텍스트-동영상과 이미지-동영상 간에 어떻게 전환합니까?

모드는 입력 파라미터에 따라 자동으로 결정됩니다. image / image_url 중 어느 것도 제공하지 않으면 텍스트-동영상이고, 이미지 파라미터 중 하나를 제공하면 이미지-동영상입니다. image와 image_url을 모두 제공하면 image(Base64)가 우선합니다.

2. 동영상 길이, 해상도 및 비율에는 어떤 값이 지원됩니까?

현재 버전에서 동영상 길이는 5초, 해상도는 720p로 고정됩니다. 비율 aspect_ratio는 텍스트-동영상에만 지정할 수 있으며(16:9 / 9:16 / 1:1 / 4:3 / 3:4), 이미지-동영상의 비율은 입력 이미지에 따라 결정됩니다.

3. 조회 API는 어떤 상태 값을 반환합니까?

queued(스케줄링 대기) / running(생성 중) / succeeded(성공) / failed(실패)입니다. 상태가 succeeded일 때만 videos[].url에 값이 있습니다. 상태가 failed이면 error 필드에서 실패 원인을 확인합니다.

4. 문서에 나열되지 않은 필드가 조회 응답에 표시됩니까?

조회 응답은 모델 측 응답을 그대로 전달하면서 플랫폼에서 정규화한 필드(예: usage.total_tokens 및 request_id)를 추가한 것입니다. 다른 공급업체별 필드도 포함될 수 있으며 이는 정상입니다. 실제 응답을 기준으로 합니다.