튜토리얼
seedance-2.5-flash 이미지-투-비디오 API 튜토리얼: curl과 Python Requests
개발자를 위한 실전 연동 워크스루: 요청 구조, 첫 프레임/마지막 프레임 입력, 비동기 폴링, 오류 해결
이 페이지에서
이미지-투-비디오 호출이 실제로 하는 일
첫 줄의 코드를 작성하기 전에, API가 반대편에서 무엇을 하는지 이해하면 큰 도움이 됩니다. seedance-2.5-flash/image-to-video 호출은 비디오 파일이 반환될 때까지 블로킹되는 동기 요청이 아닙니다. 두 단계로 이루어진 비동기 워크플로입니다. 먼저 작업을 제출하고, 그다음 결과를 폴링합니다.
제출 단계
입력 이미지와 생성 설정을 담아 POST 요청을 보냅니다. API는 요청 본문을 검증하고, 작업을 큐에 넣은 뒤, 작업 식별자와 초기 상태가 담긴 응답을 즉시 반환합니다. 이 시점에는 아직 렌더링된 픽셀이 없기 때문에 이 과정은 매우 빠릅니다. 보통 순간적으로 끝납니다. 여러분의 역할은 그 식별자를 확보해 안전하게 보관하는 것입니다.
렌더링 단계
생성은 백그라운드에서 진행됩니다. 클립 길이와 설정에 따라 상당한 실제 시간이 걸릴 수 있습니다. 이 구간에서는 최종 비디오 URL이 이미 사용 가능하다고 기대하지 마세요. 대신 작업의 상태를 조회해야 합니다.
결과 단계
최종적으로 작업은 종료 상태에 도달합니다. 성공이면 다운로드 가능한 비디오 산출물과 함께, 실패면 진단에 쓸 수 있는 오류와 함께 도달합니다. 종료 상태에 도달하면 폴링을 중지해야 합니다.
왜 이것이 코드에 중요한가
모델이 비동기이기 때문에, 가장 흔한 연동 오류는 문법 문제가 아니라 아키텍처 문제입니다. 첫 응답에 비디오가 들어 있다고 가정하기, 상태 필드를 폴링하는 대신 일정 간격으로 대기하기, 일시적인 processing 상태와 영구적 실패를 구분하지 못하기 등이 그 예입니다. 이 튜토리얼의 모든 내용은 깔끔한 '제출 → 폴링 → 종료' 루프를 중심으로 전개되므로, 읽는 동안 이 세 단계를 기억해 두세요.
사전 요구 사항과 요청 구조
첫 호출 전에 준비해야 할 것
- API 자격 증명. 모든 요청과 함께 전송하는 HiAPI API 키입니다. 소스 코드 관리가 아니라 환경 변수(
HIAPI_API_KEY)에 보관하세요. 아래 예제는 그렇게 읽어옵니다. - 모델 식별자. 이 튜토리얼에서 해당 문자열은 고정입니다:
seedance-2.5-flash/image-to-video. 불투명한 상수로 취급하고, 각 부분을 조합해 만들지 마세요. - 원본 이미지. 공개 URL 또는 지원되는 인라인 이미지 참조입니다. 모델에는 최소한 첫 프레임 이미지가 필요합니다.
- HTTP 클라이언트. 스모크 테스트용
curl, 그리고 유지할 코드에는requests를 사용합니다.
요청 본문의 논리적 필드
어떤 언어를 쓰든 이미지-투-비디오 요청 본문은 몇 가지 개념 그룹으로 구성됩니다. 각 그룹을 따로 이해하면 JSON을 훨씬 쉽게 파악할 수 있습니다:
모델과 입력
- 모델 식별자.
- 첫 프레임 이미지와 선택적인 마지막 프레임 이미지를 담는 입력 객체. 4장에서 이 둘이 어떻게 상호작용하는지 설명합니다.
출력 설정
- 해상도와 길이에 관련된 스위치.
- 생성된 클립에 함께 오디오 트랙이 포함되는지를 결정하는 네이티브 오디오 스위치. 5장에서 언제 켜야 하는지 다룹니다.
반환되는 것
성공적인 제출은 작업 객체를 반환합니다. 실제로 필요한 필드는 작업 식별자와 현재 상태입니다. 나머지는 모두 기록하거나 무시할 수 있는 메타데이터입니다. 첫날부터 전체 응답을 타입화된 모델로 파싱하지 마세요. 먼저 기록하고 확인한 뒤 범위를 좁히세요.
계속하기 전에 간단한 현실 점검을 하세요. 요청 본문에 이름을 한 문장으로 설명할 수 없는 필드가 있다면 삭제하고 최소한의 형태부터 시작하세요. seedance-2.5-flash/image-to-video 모델 페이지가 정확히 허용되는 필드 이름의 기준입니다.
curl로 작업 제출하기
작동할 수 있는 최소 요청에서 시작한 뒤, 필드를 하나씩 추가하세요. 다음은 curl을 사용한 최소 제출 예시입니다:
curl -X POST "$HIAPI_BASE_URL/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash/image-to-video",
"input": {
"first_frame_image": "https://your-bucket.example.com/frame-001.jpg"
}
}'
필드별 주석
Authorization—— bearer 토큰으로 전달하는 API 키입니다. 여기서 틀리면 어떤 검증도 실행되기 전에 인증 오류가 발생하므로, 디버깅할 때는 이것부터 확인하세요.Content-Type: application/json—— 필수입니다. 생략하면 이해하기 어려운 하위 오류가 발생합니다.model—— 고정된 모델 식별자입니다. 여기서 오타가 나면 조용히 대체되지 않고 4xx가 반환됩니다.input.first_frame_image—— 클립의 시작 이미지입니다. 네트워크에서 실제로 접근 가능한 URL을 사용하세요. 비공개이거나 만료된 URL은 제출 시점이 아니라 가져오기 단계에서 실패합니다.
응답 읽기
응답은 작업 식별자와 상태를 담은 JSON입니다. 식별자를 즉시 저장하세요. 이것이 7장에서 폴링할 대상입니다. 셸에서 추출하는 빠른 방법은 다음과 같습니다:
# 위 curl 이후, jq를 통해 파이프로 처리
# {"job_id": "...", "status": "queued"}
마지막 프레임 추가하기
종료 프레임도 제어하려면 같은 input 객체 안에 두 번째 이미지를 추가하세요. 필드 이름과 허용 형식은 모델 문서를 따르세요. 대체 철자를 추측하지 마세요. API는 알 수 없는 키를 무시하지 않고 거부합니다.
최소 요청이 작동하면 문제가 생겼을 때 다시 실행할 수 있는 스모크 테스트가 생긴 것입니다. 이 테스트를 파일에 저장해 두세요. 새벽 2시에 서비스가 문제를 일으킬 때, 이 테스트가 어떤 긴 설명보다 훨씬 유용합니다.
첫 프레임과 마지막 프레임 입력
입력 이미지는 작업 성공 여부를 결정하는 가장 큰 요인입니다. 입력 이미지는 클립의 내용을 형성하는 동시에 요청이 거부되는 가장 흔한 원인이기도 합니다.
첫 프레임이 제어하는 것
첫 프레임 이미지는 생성된 클립의 시작 상태, 즉 구도, 피사체, 조명, 색상을 설정합니다. 모델은 그 시작점에서 움직임과 연속성을 생성하므로, 이미지는 시간 0에서 실제로 나타나길 원하는 프레임처럼 보여야 합니다. 흐리거나 잘렸거나 심하게 압축된 원본 이미지는 이후 단계에서 마법처럼 좋아지지 않습니다.
마지막 프레임이 제어하는 것
마지막 프레임 이미지를 제공하면 종료 상태가 고정됩니다. 클립이 특정 샷으로 끝나야 할 때 유용합니다. 제품 미리보기 프레임, 로고 공개, 편집에서의 매치 컷 같은 경우입니다. 생략하면 모델이 결말을 스스로 선택하는데, 탐색적 작업에는 괜찮지만 프로덕션에는 예측 불가능합니다.
둘이 상호작용하는 방식
둘 다 제공하면 모델은 두 프레임 사이를 보간합니다. 여기에는 실제적인 결과가 따릅니다:
- 연속성이 대비보다 중요합니다. 같은 장면에서 운동 폭이 적당한 두 프레임은 서로 무관한 두 이미지보다 더 일관된 클립을 만듭니다. 프레임 차이가 너무 크면 합리적인 전환 대신 눈에 띄는 왜곡이 나타날 것으로 예상하세요.
- 종횡비가 일치해야 합니다. 첫 프레임과 마지막 프레임의 종횡비가 맞지 않으면 모델이 어색하게 재구성해야 합니다. 제출 전에 둘을 같은 비율로 자르세요.
- 해상도가 비슷해야 합니다. 선명한 첫 프레임과 저해상도 마지막 프레임을 보내면 모델에 상충되는 신호를 주게 됩니다.
제출 전 체크리스트
보내기 전에 확인하세요. 두 이미지 URL 모두 공개적으로 접근 가능하고 작업 도중 만료되지 않는지, 둘 다 지원되는 형식인지, 종횡비가 같은지, 렌더링하고 싶지 않은 UI 요소가 포함된 스크린샷이 아닌지. 각 URL에 빠른 HEAD 요청을 보내면 실패한 생성 작업보다 저렴하게 이런 문제 대부분을 잡아낼 수 있습니다.
거부가 발생하면 오류 메시지가 보통 입력 객체를 가리킵니다. API를 의심하기 전에 이미지를 로컬에서 검증하세요. 크기, 형식, 접근 가능성을 확인하세요.
해상도와 네이티브 오디오 설정
출력 설정은 개발자들이 과하게 구성하기 쉬운 부분입니다. 좋은 소식은 기본값이 합리적이라는 것입니다. 위험은 다른 모델의 문서에서 값을 그대로 가져오는 것입니다.
해상도
해상도는 전달되는 비디오의 크기를 결정하고, 이어서 생성 시간과 출력 용량에 영향을 줍니다. 두 가지 경험 법칙이 있습니다:
- 숫자가 아니라 대상 목적지에 맞춰 선택하세요. 모바일 피드용 클립을 크게 렌더링한 뒤 다시 줄일 필요는 없습니다. 대상 플랫폼을 만족하는 최소 해상도를 선택하세요.
- 문서에 있는 프리셋 중 하나를 우선 사용하세요. 임의의 값이나 지원되지 않는 값을 전달하는 것은 요청이 거부되는 흔한 원인입니다. 특정 프레임이 필요하면 요청 검증기와 싸우지 말고 생성 후 자르거나 크기를 조정하세요.
네이티브 오디오
네이티브 오디오 스위치는 생성된 클립에 비디오와 함께 생성된 오디오 트랙이 포함되는지를 결정합니다. 필요한지 고려하세요:
- 켜세요 클립이 소리와 함께 시청되는 최종 산출물일 때입니다. 소셜 콘텐츠, 짧은 프로모션, 주변 오디오가 움직임을 강화하는 캐릭터 장면 같은 경우입니다.
- 끄세요 편집기에서 자체 음악이나 내레이션을 넣을 예정이거나, 클립이 중간 자산일 때입니다. 버릴 오디오를 생성하는 것은 낭비이며 하위 처리도 더 무거워집니다.
길이
길이는 다른 모든 것과 연결됩니다. 더 긴 클립은 생성 시간이 더 길고 피사체 일관성 드리프트가 나타나기 쉽습니다. 첫 연동에서는 짧게 시작하세요. 짧은 클립으로 파이프라인이 끝에서 끝까지 작동하는지 확인한 뒤, 파이프라인을 신뢰하게 되면 길이를 늘리세요.
설정 객체를 작게 유지하기
품질 문제를 고치기 위해 설정을 추가하고 있다면, 문제가 실제로 입력 이미지에 있는 것은 아닌지 먼저 확인하세요. 대부분의 실망스러운 출력은 어떤 손잡이가 빠져서가 아니라 4장으로 거슬러 올라갑니다. 의도적으로 설정하고, 정확한 설정 객체를 각 작업 식별자와 함께 기록하면 품질 변화를 특정 조정에 귀속시킬 수 있습니다.
Python으로 같은 요청하기
curl 요청은 Python으로 바로 옮길 수 있습니다. 여기서 목표는 프레임워크가 아니라 작업을 제출하고 식별자를 반환하는 작고 읽기 쉬운 클라이언트이며, 이렇게 하면 폴링 계층을 분리할 수 있습니다.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "seedance-2.5-flash/image-to-video"
def submit_job(first_frame_url: str, last_frame_url: str | None = None) -> dict:
payload = {
"model": MODEL,
"input": {"first_frame_image": first_frame_url},
}
if last_frame_url:
payload["input"]["last_frame_image"] = last_frame_url
response = requests.post(
f"{BASE_URL}/image-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()
이렇게 구조화한 이유
- 환경 변수로 구성. 기본 URL과 키가 코드 밖에 있으므로 같은 클라이언트를 서로 다른 환경에 맞춰 실행할 수 있습니다.
- 제출 시
timeout=30사용. 제출은 빠릅니다. 제출이 멈추면 네트워크나 인증 문제이므로, 워커를 무한정 차단하기보다 일찍 발견하고 싶을 것입니다. - 파싱 전에
raise_for_status()호출. 4xx 응답 본문은 보통 작업이 아니라 JSON 오류 객체입니다. 먼저 예외를 발생시키면 정상 경로가 깔끔하게 유지되고 호출자가 실패를 명시적으로 처리할 수 있습니다. - 제출과 폴링 분리.
submit_job은 한 가지 일만 합니다. 다음 장의 폴링 루프가 반환된 딕셔너리를 받아 대기를 담당합니다.
서비스로 이식하기
실제 서비스에서는 호출을 감싸서 실패가 상태 코드와 응답 본문을 담은 타입화된 예외로 나타나게 하세요. 프로덕션 디버깅에서는 원본 응답 본문이 필요합니다. 요청 본문을 반환된 작업 식별자와 함께 기록하세요. 동료가 왜 어떤 클립이 이상해 보이는지 물을 때, 그 로그 한 줄이 조사 전체가 됩니다.
필드 이름은 curl 예제와 완전히 같습니다. 하나를 읽을 수 있으면 다른 하나도 읽을 수 있습니다. curl부터 시작하는 데 5분을 투자할 가치가 있는 이유가 바로 이것입니다.
API를 과도하게 두드리지 않으면서 결과 폴링하기
이제 작업이 존재하고 식별자가 있습니다. 순진한 방법, 즉 60초 동안 대기하고 기도하는 방식은 두 가지 방식으로 실패합니다. 작업이 일찍 끝나면 시간을 낭비하고, 작업이 더 오래 걸리면 완전히 실패합니다.
시계가 아니라 상태 필드를 폴링하세요
작업의 현재 상태를 조회하고 그에 따라 분기하는 루프를 작성하세요:
import time
import requests
def wait_for_job(job_id: str, timeout_s: int = 600) -> dict:
deadline = time.monotonic() + timeout_s
delay = 2.0
while time.monotonic() < deadline:
r = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
r.raise_for_status()
job = r.json()
status = job.get("status")
if status == "succeeded":
return job
if status == "failed":
raise RuntimeError(f"job failed: {job.get('error')}")
time.sleep(delay)
delay = min(delay * 1.5, 15.0) # 상한이 있는 지수 백오프
raise TimeoutError(f"job {job_id} not terminal after {timeout_s}s")
중요한 특성
- 명시적 종료 상태.
succeeded와failed만 루프를 끝냅니다. 다른 모든 상태는 일시적입니다. 알 수 없는 상태를 실패로 취급하지 마세요. 시간이 지나면 새로운 중간 상태가 나타날 수 있으며, 루프는 이를 견뎌야 합니다. - 상한이 있는 백오프. 짧게 시작해(몇 초) 적당한 계수로 늘리되 약 10~15초에서 상한을 두세요. 이렇게 하면 긴 렌더링 동안 엔드포인트를 과도하게 두드리지 않으면서도 짧은 작업에는 민첩하게 대응할 수 있습니다.
- 엄격한 마감 시간. 항상 총 대기 시간을 제한하세요. 그렇지 않으면 멈춘 작업이 워커 하나를 영구히 점유합니다. 현실적으로 가장 긴 렌더링 시간에 여유를 더해 상한을 정하세요.
- 실패와 타임아웃을 구분하세요.
failed작업은 사용자에게 보고할 가치가 있는 생성 오류입니다. 타임아웃은 재시도하거나 별도로 조사할 가치가 있는 인프라 상황입니다. 둘을 혼동하면 사후 분석이 고통스러워집니다.
웹 서비스에서
사용자가 기다리는 요청 처리기 안에서 이 루프를 실행하지 마세요. 작업을 제출하고, 작업 식별자를 저장하고, 즉시 반환한 뒤, 백그라운드 워커가 폴링하여 결과를 전달하게 하세요. 웹훅, 큐, 또는 프런트엔드가 감시하는 행 업데이트 등 어떤 방식이든 됩니다. 위 루프는 HTTP가 아니라 워커의 관심사입니다.
흔한 실패 문제 해결
대부분의 실패는 세 가지 범주로 나뉩니다. 구체적인 원인보다 범주를 먼저 파악하세요.
범주 1: 입력 검증 실패
증상: 렌더링 전 제출 시점에 즉시 4xx가 발생합니다.
다음 순서로 진단하세요:
- 이미지 URL에 접근할 수 있나요? 같은 네트워크에서 직접 가져와 보세요. 만료된 서명 URL과 비공개 버킷이 가장 큰 원인입니다.
- 형식이 지원되나요? 논쟁하지 말고 표준 형식으로 다시 인코딩하세요.
- 첫 프레임과 마지막 프레임이 일치하나요? 종횡비 불일치나 너무 큰 장면 차이는 보통 검증 또는 품질 문제로 나타납니다.
- 이름이 잘못된 필드를 추가했나요? 알 수 없는 키는 보통 무시되지 않고 거부됩니다. 모델 참조와 대조하세요.
범주 2: 매개변수 불일치
증상: 어떤 설정 때문에 요청이 거부되거나, 출력이 구성 설정을 무시합니다.
- 지원되지 않는 해상도나 길이. 문서에 있는 값만 사용하세요. 임의의 숫자는 흔한 거부 원인입니다.
- 모델 식별자 오타. 고정 문자열입니다. 다시 입력하지 말고 복사하세요.
- 중첩 오류. 최상위에 있어야 할 설정을
input안에 넣거나 그 반대로 하면 혼란스러운 오류가 발생합니다. 3장의 요청 구조를 기준으로 삼으세요.
범주 3: 폴링 타임아웃과 작업 실패
증상: 작업이 수락되었지만 종료 성공 상태에 도달하지 않습니다.
- 올바른 식별자를 폴링하고 있는지 확인하세요. 배치 스크립트에서 작업 간 복사-붙여넣기 오류는 의외로 흔합니다.
- 상태가 실제로 진행되는지 확인하세요. 각 폴링의 상태를 기록하여 작업이 진행 중인지 정체되었는지 볼 수 있게 하세요.
- API 실패와 생성 실패를 구분하세요. 폴링 요청 자체가 오류를 내면 전송 문제입니다. 작업이
failed로 보고되면 오류 본문을 읽으세요. 보통 어떤 입력 때문인지 알려줍니다. - 최소
curl스모크 테스트를 다시 실행하세요. 스모크 테스트도 실패하면 자격 증명이나 서비스 문제입니다. 성공하면 요청 본문 문제입니다.
일반적인 디버깅 자세
모든 작업에 대해 세 가지를 기록하세요. 정확한 요청 본문, 반환된 작업 식별자, 그리고 오류 본문이 포함된 최종 상태입니다. 이 세 가지가 있으면 거의 모든 사건이 오후 전체가 아니라 5분 진단이 됩니다. 의문이 들면 요청을 3장의 최소 형태로 줄이고 필드를 하나씩 추가하다가 오류가 나는 지점을 찾으세요. 마지막으로 추가한 필드가 범인입니다.