Tokenhub API Reference
Base URL: https://tokenhub-intl.tencentcloudmaas.com인증: Tokenhub API Key / Bearer
이미지와 영상 생성에 필요한 인증, 요청 방식, 결과 처리 규격입니다. 모델별 파라미터와 예시는 아래 모델 문서에서 확인할 수 있습니다.
호출 규격
API 키와 인증
Tokenhub 콘솔의 API Key Management에서 키를 발급합니다. 모든 생성·조회 요청의 Authorization 헤더에 같은 키를 전달합니다.
Authorization: Bearer $TOKENHUB_API_KEY
Content-Type: application/jsonAPI 키는 서버 환경 변수로 관리합니다. JSON 본문에는 모델별 문서에 정의된 필드만 전달합니다.
엔드포인트와 리전
모든 예시는 국제 게이트웨이 tokenhub-intl.tencentcloudmaas.com을 사용합니다. 생성 방식에 따라 URL 경로가 달라지므로 모델별 문서의 경로를 사용합니다. 별도 Region 파라미터는 전달하지 않습니다.
참조 파일 예시는 Singapore COS(ap-singapore)에 저장합니다. 결과 파일은 API 응답에 반환된 URL에서 다운로드합니다.
API 목록과 요청 파라미터
모델별 생성·조회 API와 입력 필드는 아래 엔진 카탈로그의 문서를 참조하십시오. 엔진마다 작업 ID와 결과 필드가 다를 수 있습니다.
응답과 실행 흐름
동기 요청
Hy Image와 Seedream Image는 생성 요청의 응답에서 결과를 반환합니다. 응답 필드와 이미지 전달 형식은 각 모델의 응답 규격을 따릅니다.
비동기 작업
- 생성 요청을 전송하고 반환된 작업 ID를 저장합니다.
- 해당 모델의 조회 경로로 상태를 확인합니다.
- 완료 상태에서 결과 URL을 읽고 파일을 다운로드합니다.
작업 ID 필드와 완료 상태는 모델마다 다릅니다. 조회 응답을 처리할 때 아래 값을 구분합니다.
| 모델 | 생성 응답의 작업 ID | 조회 응답의 성공 상태 |
|---|---|---|
| WAND-Vega-Image | task_id | status=completed |
| WAND-Vega-Video | id | status=succeeded |
| Vidu Image | task_id | state=success |
| PixVerse Video | Resp.video_id | Resp.status=1 |
| Kling Video | data.id | data.status=succeeded |
| MiniMax Video | task_id | task.status=succeeded |
| Hy Video | task_id | status=succeeded |
폴링 간격과 실패 상태는 모델별 조회 규격을 따릅니다. 생성 요청이 접수된 뒤에는 같은 요청을 다시 제출하지 않고 작업 ID로 결과를 조회합니다.
오류와 호출 제한
오류 처리
| HTTP 상태 | 확인 항목 |
|---|---|
400 | 모델 ID, 필수 필드, 파라미터 형식과 입력 제한 |
401 | API 키 유효 여부와 Authorization: Bearer 헤더 |
429 | 호출 빈도와 사용 한도 |
5xx | 서비스 오류. 비동기 작업 ID를 받은 경우 먼저 작업 상태 조회 |
오류 응답의 요청 식별자와 오류 코드는 문제 확인에 사용합니다. 모델별 오류 구조는 해당 문서의 오류 코드 절을 참조합니다.
요청 예제
호출할 모델 또는 프로토콜의 요청 예제를 사용하십시오. 서로 다른 경로의 인증 방식과 요청 필드를 한 요청에 혼합하지 마십시오. 아래 엔진 문서와 프로토콜별 파라미터를 함께 확인하십시오.
결과·리소스 관리
참조 파일과 결과 저장
참조 URL은 API 서버가 접근할 수 있어야 합니다. 파일 형식, 크기, 개수와 영상 길이 제한은 각 모델의 입력 조건을 따릅니다. 서명된 결과 URL은 유효 기간 안에 다운로드하여 저장합니다.
엔진 카탈로그·관련 문서
Image
| 모델 | 모델 ID | 호출 방식 |
|---|---|---|
| Hy | hy-image-v3.5-preview / hy-image-v3 | 동기 |
| WAND-Vega-Image | wand-vega-image-pro / wand-vega-image-flash / wand-vega-image-lite | 비동기 |
| Vidu | vidu-image-q2 | 비동기 |
| Seedream | seedream-image-v5.0-pro / seedream-image-v5.0-lite | 동기 |
Video
| 모델 | 모델 ID | 호출 방식 |
|---|---|---|
| WAND-Vega-Video | wand-vega-video-1.5-pro / wand-vega-video-1.0-pro / wand-vega-video-1.0-lite | 비동기 |
| PixVerse | pixverse-video-v6.0 / pixverse-video-c1 | 비동기 |
| Kling | kling-video-v3 / kling-video-v3-omni / kling-video-v3-turbo | 비동기 |
| MiniMax | minimax-video-h3 / minimax-video-h3-max | 비동기 |
| Hy | hy-video-v1.5 | 비동기 |
요금과 공식 가이드
| 구분 | 공식 가이드 |
|---|---|
| Image | 개요 / Vega / Hy / Vidu / Seedream |
| Video | 개요 / PixVerse / Kling / MiniMax / Hy |