Vidu

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

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

기본 정보

버전별 지원 규격

호출 절차

이미지 생성은 시간이 소요되는 작업이므로 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

요청 파라미터

요청 예시

참조 이미지 기반 생성

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": "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초마다 폴링하는 것이 좋습니다.

요청 파라미터

요청 예시

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

응답 파라미터

응답 예시

생성 성공:

{
  "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
  }
}

오류 코드

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

부록

통합 오류 코드

이미지 자산 일반 제한

형식: 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는 출력 화면 비율을 첫 번째 입력 이미지와 동일하게 유지함을 나타냅니다. 이 설정은 참조 이미지 기반 생성 모드에서만 의미가 있습니다.