소개
추가할 움직임을 설명하는 프롬프트와 image_url을 보냅니다. 사진 테스트에서는 480p, 1080p, 2k에서 원본 인물과 구도를 유지했습니다. 결과물의 크기에 맞는 네이티브 등급을 고릅니다.
| 항목 | 값 |
|---|---|
| 입력 | 이미지 |
| 출력 | 영상 |
| 모델 개발사 및 모델 | 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 | 예 | 고개 돌림이나 시선 이동처럼 보고 싶은 변화를 지정하고 알아볼 수 있게 유지할 요소를 적습니다. 요청 길이 안에 검토할 수 있도록 동작을 좁혀 설명합니다. 1자 이상 · 32000자 이하 |
image_url | 예 | 움직일 인물과 구도를 담은 원본 사진을 제공합니다. 움직임을 설명하기 전에 사진의 프레이밍이 목표 장면에 맞는지 확인합니다. |
resolution | 아니요 | 480p, 768p, 1080p 또는 소문자 2k를 고릅니다. 테스트 출력은 480p에서 832×480, 1080p에서 1890×1080, 2k에서 2688×1536으로 측정됐습니다. |
duration_seconds | 아니요 | 요청 길이를 5–15초로 설정합니다. 정수 프레임 반올림으로 파일이 조금 길어져도 과금 단위는 요청 길이를 따릅니다. |
prompt_optimization_mode | 아니요 | 지시문 재작성을 막으려면 disabled를, 허용하려면 turbo 또는 quality를 사용합니다. 등급을 바꾸기 전에 한 모드를 유지하며 움직임을 비교합니다. |
seed | 아니요 | seed를 고정하면 동작 프롬프트의 변경 한 가지씩 평가하기 좋습니다. 비교를 돕는 설정이며 반환 클립의 동일성을 보장하지는 않습니다. |
요금
선택한 네이티브 해상도 등급의 표시 단가로 요청 출력 초마다 과금합니다. 프레임 반올림으로 늘어난 재생 시간은 청구 출력 초 수에 더하지 않습니다.
| 사양 | 요금 |
|---|---|
| $0.03 / 초 |
| $0.054 / 초 |
| $0.144 / 초 |
| $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은 제공한 사진에 5–15초 움직임을 더하며 네이티브 480p, 768p, 1080p, 2k 등급을 제공합니다. 이미지 테스트에서 원본 인물과 구도를 유지했으므로 사진에 이미 원하는 장면이 담겨 있다면 이 엔드포인트로 시작할 수 있습니다.
사진과 움직임 전달하기
아래 JSON으로 https://api.spicyapi.ai/api/v1/jobs/createTask에 heygen/video-1/image-to-video를 제출합니다. Authorization: Bearer YOUR_SPICY_API_KEY와 Content-Type: application/json을 설정하고 사진 URL을 자신의 이미지로 교체합니다.
{
"model": "heygen/video-1/image-to-video",
"input": {
"image_url": "https://example.com/portrait.jpg",
"prompt": "The woman in her thirties in the supplied portrait, wearing a cream blouse, turns gently toward the window. Retain the source person and composition, soft morning light, calm mood, static camera.",
"duration_seconds": 5,
"resolution": "1080p",
"prompt_optimization_mode": "disabled",
"seed": 7
}
}
이 예시는 제안한 인물 애니메이션을 설명하며 추가 테스트 결과가 아닙니다. 사진과 초상 모두 사용 권한을 확보합니다.
반환 영상 수집하기
제출 시 받은 작업 ID로 GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID를 호출해 결과를 가져옵니다. 다음 축약 응답 예시는 관련 필드에 설명용 값을 넣은 것으로 새로운 실행 결과가 아닙니다.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_photo_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_photo_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/animated-portrait.mp4"}]
}
}
}
전체 응답 구조는 SpicyAPI 작업 문서에 설명돼 있습니다. 반환 자산을 저장하고 움직이는 인물과 프레이밍을 입력 사진과 비교합니다.
애니메이션 파라미터 정하기
프롬프트와 함께 image_url을 전달한 뒤 길이와 네이티브 해상도 등급을 고릅니다. 아래 설정에서는 입력 사진과 모델이 더할 움직임을 구분합니다.
| 파라미터 | 제공할 내용 |
|---|---|
image_url | 인물과 구도를 정하는 원본 사진입니다. |
prompt | 동작, 카메라 움직임, 조명, 장면 연출을 적습니다. |
duration_seconds | 요청 출력 길이를 5–15초로 지정합니다. |
resolution | 480p, 768p, 1080p, 2k 중 고릅니다. JSON에서는 소문자 2k를 씁니다. |
prompt_optimization_mode | disabled는 재작성을 막고 turbo와 quality는 허용합니다. |
seed | 수정본 비교용 설정이며 동일한 결과를 약속하지 않습니다. |
사진이 정한 요소 유지하기
장면 전체를 글로 다시 구성하기보다 원본 자세에서 작은 변화를 설명합니다. 고개 돌림이나 시선 이동은 사진과 인물·프레이밍을 비교하면서 판단할 수 있는 분명한 동작을 제공합니다.
HeyGen은 image-to-video가 제공한 사진에서 시작한다고 설명합니다. 프롬프트 안내에서는 절제된 카메라 움직임과 명확한 몸짓 접촉 지점을 권장합니다. 이는 모델 개발사의 설명입니다. 여기서 확보한 근거는 제시된 테스트에 기록된 사진 연속성과 네이티브 크기입니다.
- 유지하고 싶은 인물과 배경이 담긴 사진을 고릅니다.
- 동작 지시 하나를 적고 중요한 시각 요소를 명시합니다.
- 480p 시험 결과에서 인물 외형과 동작을 검토합니다.
- 장면 방향이 쓸 만해지면 seed를 고정해 비교하며 1080p나 2k를 시험합니다.
측정한 크기 비교하기
5초 사진 테스트는 요청한 등급에서 네이티브 출력을 만들고 원본 인물을 유지했습니다. 다음 수치는 테스트한 원본 구도에 관한 것으로 모든 사진에 공통으로 적용되는 픽셀 대응표는 아닙니다.
| 요청 등급 | 실측 출력 |
|---|---|
480p | 832×480 |
1080p | 1890×1080 |
2k | 2688×1536 |
768p도 지원하지만 해당 등급의 이미지 테스트 크기는 보고할 측정값이 없습니다. 이미지 전용 처리 시간도 측정하지 않았으므로 텍스트 실행의 약 10초를 이 엔드포인트의 예상 시간으로 보면 안 됩니다.
과금 계획과 길이 검토
사진 애니메이션은 이 페이지에서 선택한 등급의 표시 단가로 요청 출력 초 수를 과금합니다. 테스트 전반의 5초 파일은 정수 프레임 반올림으로 5.18–5.26초였지만 청구 출력 길이는 5초로 유지됐습니다. 픽셀 수 확대는 결과물의 크기를 위한 것이므로 다음 렌더링을 결정하기 전에 움직임은 별도로 검토합니다.
입력 문제와 대안 살펴보기
요청이 거절되면 image_url, 프롬프트, 해상도 표기를 확인합니다. 길이는 5–15초로 유지하고 해당 등급에는 2k를 사용합니다. 필드를 바꾸기 전에 현재 스키마와 반환된 작업 오류를 참고합니다. 작업이 성공했더라도 중요한 몸짓이 바뀌었다면 시각적 검토가 필요합니다.
원본 사진 없이 글로 장면을 만들려면 텍스트 영상 생성을 선택합니다. 인물과 제품에 별도 역할을 주려면 참조 영상 생성을 선택하되 영상 입력이 인물 정체성에 더 강하게 작용할 수 있음을 고려합니다. 사진을 말하는 아바타로 만들려면 HeyGen Avatar IV를 검토합니다.
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/image-to-video",
"input": {
"duration_seconds": 5,
"image_url": "https://example.com/reference.png",
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"prompt_optimization_mode": "disabled",
"resolution": "768p"
}
}'
# 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 레퍼런스에서 확인하세요.

