소개
prompt에 피사체, 배경, 동작, 원하는 소리를 설명한 뒤 duration_seconds와 해상도를 고릅니다. seed로 수정본을 비교하고 prompt_optimization_mode로 지시문의 재작성 허용 여부를 정합니다.
| 항목 | 값 |
|---|---|
| 입력 | 텍스트 |
| 출력 | 영상 |
| 모델 개발사 및 모델 | 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자 이하 |
aspect_ratio | 아니요 | 제출 전에 이 엔드포인트의 현재 선택지에서 화면 형태를 고릅니다. 장면 설명으로 화면비가 정해지길 기대하기보다 사용처에 맞게 구도를 계획합니다. |
resolution | 아니요 | 텍스트 생성에는 480p 또는 768p를 고릅니다. 480p 테스트는 832×480을 반환했습니다. |
duration_seconds | 아니요 | 5–15초를 요청합니다. 테스트의 5초 파일은 프레임 반올림 후 5.18–5.26초였지만 과금은 출력 5초로 계산됐습니다. |
prompt_optimization_mode | 아니요 | 프롬프트 재작성을 피하려면 disabled로 설정합니다. turbo와 quality는 모두 모델의 지시문 재작성을 허용하므로 프롬프트를 비교할 때 이 선택을 일정하게 유지합니다. |
seed | 아니요 | seed를 고정한 채 장면 세부 사항 하나를 바꾸면 비교하기 쉽습니다. seed가 같아도 동일한 결과를 보장하지 않습니다. |
요금
480p 또는 768p의 표시 단가로 요청 출력 초마다 과금합니다. 정수 프레임 반올림으로 길어져도 청구되는 요청 길이는 늘어나지 않습니다.
| 사양 | 요금 |
|---|---|
| $0.03 / 초 |
| $0.054 / 초 |
활용 사례
촬영 전 장면 구상
햇빛이 드는 작업실에서 캔버스 앞치마를 두른 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은 글로 쓴 장면을 AAC 스테레오 오디오가 있는 480p 또는 768p의 5–15초 클립으로 만듭니다. 이 엔드포인트는 이미지 대신 프롬프트를 받으므로 사진이나 촬영본을 확보하기 전 콘셉트 장면에 적합합니다.
장면 생성 요청 보내기
다음 JSON을 https://api.spicyapi.ai/api/v1/jobs/createTask로 POST해 heygen/video-1/text-to-video를 호출합니다. Authorization: Bearer YOUR_SPICY_API_KEY와 Content-Type: application/json을 제공합니다. 아래 장면은 제안용 요청이며 실측 테스트를 재현한 내용은 아닙니다.
{
"model": "heygen/video-1/text-to-video",
"input": {
"prompt": "A potter in their thirties, wearing a blue work shirt, turns toward a shelf in a sunlit studio. Static medium shot, warm side light, thoughtful mood. Sound: quiet studio ambience, no music.",
"duration_seconds": 5,
"resolution": "480p",
"prompt_optimization_mode": "disabled",
"seed": 42
}
}
작업 응답 조회하기
제출 응답의 data.taskId를 읽고 Bearer 키로 GET /api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID를 조회합니다. 성공 결과에는 생성 자산 URL이 나타납니다. 다음 예시는 관련 없는 응답 필드를 생략하고 예시 ID와 URL을 사용합니다.
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_text_example",
"state": "queued"
}
}
{
"code": 200,
"msg": "success",
"data": {
"taskId": "job_text_example",
"state": "succeeded",
"output": {
"assets": [{"url": "https://example.com/generated-scene.mp4"}]
}
}
}
전체 요청·응답 규격은 작업 API 안내에서 확인합니다. 자산 URL을 열어 화면을 검토하고 생성된 트랙을 들어봅니다.
장면 설정 선택하기
다음 설정으로 길이, 화면 크기, 프롬프트 처리 방식을 지정합니다. 결과물의 형식이 중요하면 엔드포인트의 현재 선택지에서 화면비를 고릅니다.
| 파라미터 | 용도와 지원 설정 |
|---|---|
prompt | 피사체, 눈에 보이는 동작, 배경, 빛, 원하는 소리를 설명합니다. |
duration_seconds | 5–15초 출력을 요청합니다. |
resolution | 480p 또는 768p를 고릅니다. 이 엔드포인트에는 1080p 등급이 없습니다. |
aspect_ratio | 현재 엔드포인트 설정에서 지원하는 화면 형태를 선택합니다. |
prompt_optimization_mode | disabled, turbo, quality 중 선택하며 뒤의 두 모드는 재작성을 허용합니다. |
seed | 프롬프트 수정 한 가지를 비교할 때 고정합니다. 동일한 출력은 보장하지 않습니다. |
한 장면에 집중해 연출하기
카메라 지시를 더하기 전에 눈에 보이는 동작 하나에 명확한 배경을 부여합니다. 예를 들어 짧은 클립 하나에 방 구경, 몸짓, 장면 전환을 모두 요청하기보다 사람이 선반 쪽으로 돌아서는 모습을 설명합니다.
HeyGen은 지시문에 카메라 구성, 조명, 소리의 출처를 적도록 안내합니다. 범위를 좁힌 장면을 권장하고 복잡한 손동작과 긴 화면 문구의 한계를 설명합니다. 이를 모델 개발사의 안내로 참고하고 해당 세부 사항은 직접 결과를 살펴봅니다.
- 인물, 의상, 장소, 동작 순서로 적습니다.
- 창가 빛을 받는 고정 미디엄 숏처럼 구체적인 시점을 더합니다.
- 원하는 소리를 묘사하고 필요하면 음악 없음을 명시합니다.
- 다른 설정을 바꾸기 전에 같은 seed와 재작성 모드로 수정본을 비교합니다.
실측 결과 살펴보기
중립적인 텍스트 테스트에서는 480p로 5초를 요청하고 AAC 스테레오 오디오가 있는 832×480·24fps 영상을 받았습니다. 해당 실행의 처리 시간은 약 10초였습니다. 모든 장면의 일반적인 완료 시간을 뜻하지는 않습니다.
제시된 테스트 전반에서 5초 요청은 정수 프레임 반올림 후 5.18–5.26초 파일로 나왔습니다. 타임라인에 정확한 편집점이 필요하면 파일 길이를 확인하고 편집기에서 자릅니다.
청구 단위 이해하기
텍스트 생성은 이 페이지에서 선택한 등급의 현재 표시 단가로 요청 출력 초마다 과금합니다. 프레임 반올림으로 재생 시간이 조금 늘어도 5초 요청은 출력 5초로 계산합니다. 구도 시험에는 480p를 선택하고 이후 필요한 결과물에 맞춰 768p를 검토합니다. 이는 작업 흐름 제안이며 실측 품질 순위는 아닙니다.
제한 확인과 다른 작업 선택
제출 전에 요청을 5–15초로 맞추고 480p 또는 768p를 고릅니다. 입력 오류라면 필드 이름과 해상도를 표 및 현재 스키마와 비교합니다. 작업이 실패했다면 미완료 작업을 완성 영상으로 간주하지 말고 errorCode와 errorMessage를 확인합니다.
특정 사진으로 인물과 구도를 정하거나 네이티브 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/text-to-video",
"input": {
"prompt": "A slow aerial shot drifting over a misty pine forest at sunrise",
"resolution": "768p",
"aspect_ratio": "16:9",
"duration_seconds": 5,
"prompt_optimization_mode": "disabled"
}
}'
# 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 레퍼런스에서 확인하세요.

