소개
총 12개 항목 안에서 <Picture 1>, <Video 1>, <Audio 1>로 원본별 역할을 지정합니다. 16:9 또는 9:16을 선택하며 참조 영상의 움직임과 장면 단서가 강할 때는 인물 유지 여부를 세심히 확인합니다.
| 항목 | 값 |
|---|---|
| 입력 | 텍스트 |
| 출력 | 영상 |
| 모델 개발사 및 모델 | HeyGen — HeyGen Video 1.0, API 이름 heygen-video-1 |
| 공개 엔드포인트 이름 | heygen/video-1/text-to-video; heygen/video-1/image-to-video; heygen/video-1/reference-to-video |
| 요청 길이 | 세 엔드포인트 모두 5–15초 |
| 텍스트 생성 해상도 | 480p 또는 768p, 출력에 AAC 스테레오 오디오 포함 |
| 사진 애니메이션 해상도 | 480p, 768p, 1080p, 2k — 네이티브 해상도 등급 |
| 이미지 출력 크기 실측 | 480p에서 832×480, 1080p에서 1890×1080, 2k에서 2688×1536 |
| 참조 출력 설정 | 480p 또는 768p, 화면비 16:9 또는 9:16 |
| 참조 입력 한도 | 합계 최대 12개, 참조 영상은 총 15초까지 |
| 프롬프트 재작성 모드 | disabled, turbo, quality |
| 파일 길이 실측 | 5초 요청에서 5.18–5.26초 반환, 요청한 5초로 과금 |
| 청구 기준 | 요청 출력 초 수에 참조 영상 초 수를 더하며, 세 번째 이미지부터 장당 요금 추가 |
핵심 기능 및 하이라이트
장면 설명을 클립으로 만들기
text-to-video는 480p 또는 768p로 5–15초 장면을 만들고 오디오 트랙을 포함합니다. 480p·5초 실행에서는 약 10초 처리 후 AAC 스테레오 오디오가 있는 832×480·24fps 결과를 받았습니다. 이는 한 번의 실행 관찰이며 완료 시간을 약속하지는 않습니다.
원본 인물을 화면에 유지하기
image-to-video는 image_url과 동작 프롬프트로 제공한 사진을 움직입니다. 480p, 1080p, 2k 테스트에서 원본 인물과 구도를 유지했으며 2k 실행은 2688×1536픽셀을 반환했습니다. 특정 사진과의 연속성이 중요할 때 이 입력 방식을 선택합니다.
인물과 사물을 따로 지정하기
reference-to-video는 이미지, 영상, 오디오 클립을 총 12개 안에서 결합합니다. 인물과 병 이미지 2장 테스트는 남성이 제공한 병을 들고 있는 세로 장면을 만들었습니다. 별도의 혼합 참조 실행은 영상을 강하게 따르면서 사진의 얼굴을 잃었으므로 각 입력의 목적을 명확히 정합니다.
설정을 유지하며 프롬프트 바꾸기
seed와 prompt_optimization_mode로 수정 비교를 정리합니다. seed를 고정해 변경 한 가지를 비교하되 동일한 결과를 보장하지는 않습니다. 프롬프트 재작성을 피하려면 disabled를, 모델의 지시문 재작성을 허용하려면 turbo나 quality를 선택합니다.
요청 파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
prompt | 예 | 각 참조를 미디어 토큰으로 가리키고 맡을 역할을 설명합니다. 인물과 제품 쌍이라면 <Picture 1>의 인물이 <Picture 2>의 물체를 들도록 적습니다. 1자 이상 · 32000자 이하 |
reference_image_urls | 아니요 | 장면에 반영할 인물, 물체, 배경에 이미지 참조를 사용합니다. 총 12개 한도에 포함되며 세 번째 이미지부터 장당 요금이 추가됩니다. 1개 이상 · 9개 이하 |
reference_video_urls | 아니요 | 참조 영상 길이는 합계 15초 이내로 맞추고 각 클립을 총 12개 한도에 포함합니다. 영상 초 수도 과금하며 영향이 큰 클립은 이미지의 얼굴을 대체할 수 있습니다. 1개 이상 · 3개 이하 |
reference_audio_urls | 아니요 | <Audio 1> 같은 토큰으로 오디오의 용도를 지정하고 사용 권한이 있는 녹음을 활용합니다. 오디오 클립도 통합 참조 한도 12개에 포함됩니다. 1개 이상 · 3개 이하 |
aspect_ratio | 아니요 | 가로 장면은 16:9, 세로 장면은 9:16을 선택합니다. 제시된 남성과 병 참조 테스트는 9:16을 사용했으며 이미지 2장을 모두 반영했습니다. |
resolution | 아니요 | 참조 생성은 480p 또는 768p를 제공합니다. |
duration_seconds | 아니요 | 제공하는 참조 촬영본과 별도로 5–15초 출력을 요청합니다. 과금에는 출력 초 수와 참조 영상 초 수를 함께 반영합니다. |
prompt_optimization_mode | 아니요 | disabled는 지시문 재작성을 막고 turbo와 quality는 허용합니다. 각 참조가 장면에 미치는 영향을 확인할 때 모드를 고정합니다. |
seed | 아니요 | 비교를 위해 참조를 추가하거나 제거할 때 seed를 유지합니다. 같은 seed가 동일한 클립이나 특정 얼굴의 유지를 보장하지는 않습니다. |
요금
요청 출력 초 수와 참조 영상 초 수를 합쳐 표시 단가로 과금합니다. 참조 이미지 2장은 포함되며 세 번째부터 장당 요금이 추가됩니다.
| 사양 | 요금 |
|---|---|
| $0.102 / 초 |
| $0.144 / 초 |
활용 사례
촬영 전 장면 구상
햇빛이 드는 작업실에서 캔버스 앞치마를 두른 30대 도예가가 선반 쪽으로 돌아서는 장면을 텍스트로 보냅니다. 480p로 5초를 요청해 촬영 전에 검토할 오디오 포함 콘셉트 클립을 받습니다.
작은 몸짓을 더한 인물 사진
창가에서 이브닝드레스를 입은 30대 여성의 사용 허가 사진을 제공하고 고개 돌림과 느린 카메라 이동을 요청합니다. image-to-video가 사진을 바탕으로 짧은 애니메이션을 반환하면 인물과 구도를 원본과 비교합니다.
제공한 제품을 든 발표자
남성 인물 사진을 <Picture 1>, 스포이트 병 사진을 <Picture 2>로 첨부하고 병을 든 9:16 장면을 요청합니다. 이미지 2장 테스트는 두 참조를 모두 활용했으며 처리에 약 158초가 걸렸습니다.
움직임 중심 콘셉트
인물 사진, 4초 동작 클립, 오디오 참조를 제공하고 프롬프트에서 각각의 역할을 적습니다. 혼합 입력 실행은 영상의 움직임과 장면을 충실히 따랐지만 사진의 얼굴은 유지하지 않았습니다. 해당 얼굴보다 움직임이 중요할 때 이 방식을 활용합니다.
더 큰 사진 기반 결과물
원본 사진에 절제된 동작 프롬프트를 연결하고 image-to-video에서 1080p 또는 2k를 선택합니다. 5초 테스트에서는 원본 인물을 유지하며 네이티브 1890×1080 및 2688×1536 출력을 받았습니다.
프롬프트 가이드 및 실전 팁
입력에 맞는 엔드포인트 고르기
글로 쓴 장면은 text-to-video, 사진은 image-to-video, 여러 원본 자료는 reference-to-video를 선택합니다. 사진 애니메이션은 필요한 경우 1080p와 2k 등급을 제공합니다.
장면 지시를 구체화하기
인물, 의상, 배경, 조명과 눈에 보이는 동작 하나를 설명합니다. 참조를 쓸 때는 <Picture 1>, <Picture 2> 같은 토큰에 동작을 연결하고 사용 권한이 있는 텍스트, 목소리, 초상을 활용합니다.
영상 생성 작업 제출하기
Bearer 인증으로 https://api.spicyapi.ai/api/v1/jobs/createTask 에 POST 요청을 보냅니다. JSON 예시는 {"model":"heygen/video-1/text-to-video","input":{"prompt":"A potter in their thirties turns toward a shelf.","
duration_seconds":5,"resolution":"480p"}}입니다.클립을 받아 검토하기
data.taskId를 저장하고 GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID를 조회해 결과를 확인합니다. 반환 영상을 검토한 뒤 seed를 고정해 수정 한 가지를 시험합니다. 설정을 반복해도 동일한 결과를 보장하지 않습니다.
참조로 장면을 구성하는 HeyGen Video 1.0 API
HeyGen Video 1.0은 제공한 이미지, 영상, 오디오 참조를 결합해 480p 또는 768p의 5–15초 장면을 만듭니다. 참조 엔드포인트는 총 12개 항목과 16:9 또는 9:16을 지원하며, 참조 영상 길이는 합계 15초로 제한됩니다.
인물과 제품으로 호출하기
https://api.spicyapi.ai/api/v1/jobs/createTask에 POST 요청을 보내며 heygen/video-1/reference-to-video를 사용합니다. Authorization: Bearer YOUR_SPICY_API_KEY와 Content-Type: application/json을 추가하고 예시 이미지 URL 2개를 사용 권한이 있는 자료로 교체합니다.
{
"model": "heygen/video-1/reference-to-video",
"input": {
"prompt": "The man in his thirties from <Picture 1>, in a pale blue shirt, holds the dropper bottle from <Picture 2> beside his face in a softly lit bathroom. Vertical framing, static camera, warm light, composed mood.",
"reference_image_urls": [
"https://example.com/person.jpg",
"https://example.com/bottle.jpg"
],
"duration_seconds": 5,
"resolution": "480p",
"aspect_ratio": "9:16",
"prompt_optimization_mode": "disabled",
"seed": 21
}
}
이 제안 요청은 토큰 사용법을 보여주며 원래 테스트 본문은 아닙니다. 허가받은 텍스트, 목소리, 초상을 사용하고 실제 인물을 사칭하지 않아야 합니다.
생성 작업 결과 읽기
제출 후 data.taskId를 수집하고 GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID로 작업을 조회합니다. 아래 축약 JSON은 대기 작업과 성공 결과를 설명합니다. ID와 자산 링크는 예시입니다.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_references_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_references_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/reference-scene.mp4"}]
}
}
}
연동 세부 사항은 전체 작업 규격을 확인합니다. 성공한 작업이 모든 입력을 똑같이 유지한다고 가정하지 말고 각 참조가 의도대로 기여했는지 결과를 검토합니다.
모든 참조에 역할 부여하기
각 입력을 해당 토큰으로 가리키고 장면에 무엇을 제공할지 설명합니다. HeyGen 문서에 따르면 번호는 미디어 목록마다 독립적으로 매깁니다. 따라서 이미지는 <Picture 1>, 영상은 <Video 1>, 오디오는 <Audio 1>로 지정합니다.
| 파라미터 | 용도와 한도 |
|---|---|
prompt | 새 장면을 설명하고 제공한 항목을 토큰으로 가리킵니다. |
reference_image_urls | 인물, 제품, 배경 이미지이며 세 번째부터 장당 요금이 붙습니다. |
reference_video_urls | 움직임이나 장면 참조로 합계 15초까지이며 해당 초 수도 과금합니다. |
reference_audio_urls | <Audio 1> 같은 토큰으로 역할을 지정하는 오디오 클립입니다. |
| 통합 목록 | 세 미디어 종류를 합해 참조 항목 최대 12개입니다. |
duration_seconds | 요청 출력 길이는 5–15초입니다. |
resolution | 480p 또는 768p입니다. |
aspect_ratio | 16:9 또는 9:16입니다. |
prompt_optimization_mode | disabled, turbo, quality이며 뒤의 두 모드는 지시문을 재작성할 수 있습니다. |
seed | 수정 한 가지를 비교할 때 고정하며 동일한 렌더링은 보장하지 않습니다. |
참조 테스트 2건에서 배우기
이미지 2장 테스트는 남성과 스포이트 병을 모두 활용해 남성이 그 병을 들고 있는 9:16 결과를 만들었습니다. 처리에 약 158초가 걸렸습니다. 이는 실측 실행값이며 참조 생성 서비스의 목표 시간이 아닙니다.
혼합 참조 테스트는 영상을 충실히 따랐고 이미지의 얼굴은 가져오지 않았습니다. 입력은 이미지 1장, 4초 영상, 오디오였습니다. 특정 사진 속 인물이 중요하다면 영향이 강한 동작 클립을 피합니다. 이미지만 사용하거나 image-to-video로 시작하면 평가할 대상을 좁히기 좋습니다.
- 반드시 보여야 할 요소가 인물과 제품이라면 해당 이미지부터 준비합니다.
<Picture 1>과<Picture 2>로 역할을 명시합니다.- 움직임이나 장면이 실제로 필요할 때 영상을 추가하고 얼굴을 다시 확인합니다.
- 변경점을 비교할 때 seed와 프롬프트 재작성 설정을 유지합니다.
참조 과금 계산하기
참조 생성은 이 페이지의 표시 가격으로 요청 출력 초 수와 참조 영상 초 수를 합산해 과금합니다. 참조 이미지는 세 번째부터 장당 요금이 추가됩니다. 출력 5초를 요청하면서 참조 영상 4초를 넣었다면 두 길이를 모두 고려해 요청을 계획합니다. 참조 촬영본은 요청한 출력 시간을 대체하지 않습니다.
제시된 5초 테스트는 프레임 반올림 후 5.18–5.26초 파일을 반환했습니다. 출력 부분은 참조 영상 사용량과 별개로 요청한 5초만 과금합니다.
문제 확인과 엔드포인트 전환
참조 요청을 제출하기 전에 합산 항목 수, 영상 길이, 출력 설정을 확인합니다. 12개 초과 항목, 15초 초과 참조 영상, 16:9·9:16 이외의 화면비, 768p를 넘는 등급은 이 페이지의 지원 설정을 벗어납니다. 결과가 없다고 인물 정체성 문제로 단정하지 말고 거절되거나 실패한 작업의 반환 오류를 살펴봅니다.
특정 사진을 움직이거나 네이티브 1080p·2k 출력을 요청하려면 사진 기반 영상 생성을 사용합니다. 참조가 필요 없으면 텍스트 기반 영상 생성을 사용합니다. 말하는 사진 작업은 HeyGen Avatar IV, 번역은 관련 모델인 HeyGen Video Translate를 검토합니다.
API 빠른 시작
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "heygen/video-1/reference-to-video",
"input": {
"aspect_ratio": "16:9",
"duration_seconds": 5,
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"prompt_optimization_mode": "disabled",
"resolution": "768p",
"reference_image_urls": [
"https://example.com/reference.png"
]
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
인증, 전체 스키마, 폴링과 오류 처리는 API 레퍼런스에서 확인하세요.

