Vidu

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

Vidu Image q2는 텍스트 생성, 참조 이미지 생성, 이미지 편집을 지원합니다.

기본 정보

항목	값
호출 경로	Tokenhub API
가드레일 해제 지원	지원

버전별 지원 규격

버전	해상도	비율	참조 이미지
vidu-image-q2	1080p / 2K / 4K	16:9 / 9:16 / 1:1 / 3:4 / 4:3 / 21:9 / 2:3 / 3:2 / auto	최대 7장

호출 절차

이미지 생성은 시간이 소요되는 작업이므로 API는 비동기 호출 방식을 사용하며, 다음 두 단계로 구성됩니다.

1. 작업 제출: 이미지 생성 API를 호출합니다. 성공하면 task_id와 초기 상태 created가 반환됩니다.
2. 결과 폴링: task_id로 작업 결과 조회 API를 state = success가 될 때까지 호출하고 결과에서 이미지 URL을 가져옵니다. callback_url로 콜백을 구성하면 작업 상태가 변경될 때 서버가 알림을 전송하도록 설정할 수 있습니다.

참고: 작업 상태: created(생성 완료) / queueing(대기열에 있음) / processing(처리 중) / success(성공) / failed(실패). 모든 API 응답에는 문제 해결에 사용되는 최상위 request_id가 포함됩니다. 조회 API는 사용량을 나타내는 usage도 반환합니다.

이미지 생성

API 설명

Vidu 이미지 생성(참조 이미지 기반 생성) API는 참조 이미지 기반 생성, 텍스트 기반 이미지 생성, 이미지 편집을 지원합니다. 참조 이미지 0~7개와 텍스트 프롬프트로 이미지를 생성하거나, 참조 이미지를 제공하지 않고 텍스트 기반 이미지를 생성할 수 있습니다.

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/generation

요청 파라미터

파라미터	필수	타입	설명
model	필수	string	모델 ID. 값: vidu-image-q2
prompt	필수	string	텍스트 프롬프트이며 최대 길이는 2000자입니다. images를 전달하지 않으면 이 텍스트를 기반으로 텍스트 기반 이미지 생성이 수행됩니다.
images	선택	array[string]	참조 이미지 0~7개. 이미지 URL 또는 Base64를 지원하며, Base64에는 data:image/png;base64, 접두사가 필요합니다. 형식: png/jpeg/jpg/webp. 픽셀 크기: 128×128 이상. 화면 비율: 1:4 미만 또는 4:1 초과여야 합니다. 이미지 1개당 최대 50 MB, POST 본문은 최대 20 MB입니다.
aspect_ratio	선택	string	화면 비율. 옵션: 16:9 / 9:16 / 1:1 / 3:4 / 4:3 / 21:9 / 2:3 / 3:2 / auto(첫 번째 입력 이미지의 화면 비율과 동일). 기본값: 16:9.
resolution	선택	string	해상도. 옵션: 1080p / 2K / 4K. 기본값: 1080p.
seed	선택	integer	무작위 시드. 지정하지 않거나 0으로 설정하면 무작위 숫자가 사용됩니다.
callback_url	선택	string	작업 상태 변경 콜백 URL(POST). 콜백 본문은 작업 조회 응답 본문과 동일하며, 콜백 서명 알고리즘으로 인증합니다.

요청 예시

참조 이미지 기반 생성

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "vidu-image-q2",
  "images": [
    "https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png"
  ],
  "prompt": "a cat sitting on a windowsill at sunset",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}'

텍스트 기반 이미지 생성(images 없음)

curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu-image/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "vidu-image-q2",
  "prompt": "a cat sitting on a windowsill at sunset",
  "aspect_ratio": "16:9",
  "resolution": "1080p"
}'

응답 파라미터

필드	타입	설명
task_id	string	Vidu가 생성한 작업 ID로, 이후 작업 조회 및 콜백 일치 확인에 사용됩니다.
state	string	처리 상태: created / queueing / processing / success / failed.
prompt	string	이 호출의 프롬프트 파라미터입니다.
created_at	string	작업 생성 시간(ISO 8601).
request_id	string	문제 해결에 사용되는 고유 요청 식별자입니다.

응답 예시

{
  "task_id": "1374200352-WandImage-a457a7b042694f8aad4deeff8c7f7ef3",
  "state": "created",
  "prompt": "a cat sitting on a windowsill at sunset",
  "created_at": "2026-08-20T07:31:07.277Z",
  "request_id": "26eb0d62-1c52-4f3a-9b5e-7e8fb2524d8f"
}

오류 코드

요청이 실패하면 오류 코드가 반환됩니다. 자세한 내용은 ErrMsg/오류 메시지를 참조합니다. 일반적인 오류 코드는 부록: 통합 오류 코드를 참조합니다.

작업 결과 조회

API 설명

이미지 생성 작업의 상태와 결과를 조회합니다. 작업을 제출하고 task_id가 반환되면 이 API를 폴링하여 결과를 가져옵니다.

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

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

요청 파라미터

파라미터	필수	타입	설명
task_id	필수	string	작업 제출 시 반환된 task_id인 작업 ID(경로 파라미터)입니다.

요청 예시

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

응답 파라미터

필드	타입	설명
state	string	처리 상태: created / queueing / processing / success / failed.
model	string	이 호출에서 사용된 모델 이름입니다.
aspect_ratio	string	이 호출의 화면 비율 파라미터입니다.
resolution	string	이 호출의 해상도 파라미터입니다.
creations	array[object]	생성 결과 목록이며 성공 시 반환됩니다.
creations[].url	string	생성된 이미지의 다운로드 URL은 12시간 동안 유효한 임시 주소입니다. 즉시 다운로드하여 저장합니다.
request_id	string	문제 해결에 사용되는 고유 요청 식별자입니다.
tokenhub_usage	object	사용량입니다.
tokenhub_usage.total_tokens	integer	이 작업에서 사용한 토큰 수이며 청구/정산에 사용됩니다.

응답 예시

생성 성공:

{
  "state": "success",
  "model": "vidu-image-q2",
  "prompt": "a cat sitting on a windowsill at sunset",
  "creations": [
    {
      "url": "https://aigc-image.cos.myqcloud.com/xxx/result.png"
    }
  ],
  "aspect_ratio": "16:9",
  "resolution": "2K",
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2",
  "tokenhub_usage": {
    "total_tokens": 1024
  }
}

오류 코드

state	설명	권장 처리 방법
success	생성 성공	creations.url에서 결과 이미지를 가져옵니다.
processing / queueing	처리 중 / 대기열에 있음	상태가 success로 변경될 때까지 3~5초마다 한 번 폴링합니다.
failed	생성 실패	실패 원인을 확인하고 수정한 후 재시도합니다. 실패가 지속되면 기술 지원에 문의하고 request_id를 제공합니다.

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

부록

통합 오류 코드

오류 코드	오류 메시지	설명
BadRequest	잘못된 요청	유효하지 않은 요청
FieldLacking	필드 누락 또는 비어 있음	필수 필드 누락
FieldUnwanted	원하지 않는 필드	허용되지 않는 필드가 전달되었습니다.
FieldInvalid	유효하지 않은 필드	입력 파라미터가 유효성 검사를 통과하지 못했습니다.
FieldItemCountOutOfRange	필드 항목 수가 범위를 벗어남	필드 항목 수가 제한을 초과했습니다(예: 이미지 수가 제한을 초과함).
PageSizeOutOfRange	페이지 크기가 범위를 벗어남	이미지 크기/파라미터가 제한을 초과했습니다.
ImageFormatInvalid	유효하지 않은 이미지 형식	이미지 형식이 요구 사항을 충족하지 않습니다.
ImageSizeInvalid	유효하지 않은 이미지 크기	이미지 크기가 너무 크거나 작습니다.
ImageDownloadFailure	이미지 다운로드 실패	URL에서 이미지를 다운로드하지 못했습니다. 링크를 확인합니다.
TaskPromptPolicyViolation	프롬프트 정책 위반	프롬프트가 보안 검토 및 위험 제어를 트리거했습니다.
CreationPolicyViolation	생성 정책 위반	생성된 콘텐츠가 위험 제어를 트리거했습니다.
AuditSubmitIllegal	제출이 유효하지 않음	입력이 보안 검토를 통과하지 못했습니다.
CreditInsufficient	크레딧 부족	크레딧이 부족합니다.
ModelUnavailable	모델 사용 불가	모델을 사용할 수 없습니다.
Unauthorized	인증되지 않음	인증되지 않았습니다(Authorization 확인).
Forbidden	금지됨	요청 권한이 없습니다.
TaskNotFound	작업을 찾을 수 없음	task_id를 찾을 수 없습니다.
QuotaExceeded	할당량 초과	동시 실행 제한을 초과했습니다.
TooManyRequests	요청이 너무 많음	요청 빈도가 너무 높습니다.
InternalServiceFailure	내부 서비스 오류	내부 서버 오류

이미지 자산 일반 제한

형식: png / jpeg / jpg / webp. 해상도: 최소 128×128픽셀. 화면 비율: 1:4 미만 또는 4:1 초과여야 합니다. 이미지 1개 크기: 최대 50 MB. POST 본문 크기: 최대 20 MB. 이미지 URL 또는 Base64를 지원하며, Base64에는 data:image/png;base64, 접두사가 포함되어야 합니다.

FAQ

1. 텍스트 기반 이미지 생성과 이미지 기반 이미지 생성을 어떻게 구분합니까?

동일한 API가 두 모드를 모두 지원합니다. images를 전달하면 이미지 내 참조 대상을 참조하는 참조 이미지 기반 생성이 활성화되고, images를 생략하면 프롬프트만으로 생성하는 텍스트 기반 이미지 생성이 활성화됩니다. vidu-image-q2는 두 모드를 모두 지원합니다.

2. 생성된 이미지 링크는 만료됩니까?

생성 결과는 12시간 후 만료되는 임시 주소입니다. 작업 성공 후 즉시 creations.url에서 이미지를 다운로드하여 자체 스토리지에 저장합니다. 이 링크를 장기간 사용하지 마십시오.

3. auto 화면 비율이란 무엇입니까?

aspect_ratio: auto는 출력 화면 비율을 첫 번째 입력 이미지와 동일하게 유지함을 나타냅니다. 이 설정은 참조 이미지 기반 생성 모드에서만 의미가 있습니다.