튜토리얼
HiAPI API로 seedance-2.5-flash 텍스트-투-비디오를 호출하는 방법(curl 및 Python)
개발자용 실제 요청 실습: 엔드포인트, 파라미터, 비동기 작업 처리, 그리고 실행 가능한 curl 및 Python 예시
이 페이지에서
seedance-2.5-flash/text-to-video가 제공하는 것
seedance-2.5-flash/text-to-video는 HiAPI API의 텍스트-투-비디오 생성 엔드포인트입니다. 목표 장면을 설명하는 텍스트 프롬프트를 보내면 모델이 생성된 비디오를 반환합니다. 규약은 바로 이렇게 단순합니다. 텍스트를 입력하면 비디오가 출력됩니다.
비디오 생성은 일반적인 채팅 완성보다 오래 걸리기 때문에 이 엔드포인트는 비동기입니다. 단일 호출은 비디오가 준비될 때까지 차단 대기하지 않고 생성 작업을 만들며, 작업이 터미널 상태에 도달한 후에 결과를 가져옵니다. 장시간 실행되는 미디어 API를 통합해 본 적이 있다면 이 형태가 익숙할 것입니다. 제출하고, 작업 식별자를 저장하고, 결과를 가져옵니다.
따라서 여러분 쪽의 통합 작업은 세 가지로 나뉩니다. 유효한 제출 요청을 구성하고, 작업 ID를 영속화하고, 완료된 비디오를 안정적으로 가져오는 것입니다. 이 튜토리얼은 실행 가능한 curl 및 Python 코드로 이 세 단계를 따라가며, 그다음 파라미터 검증, 폴링과 콜백의 트레이드오프, 그리고 대다수 첫 통합에서 마주치는 실패 패턴을 설명합니다.
프로그래밍 방식으로 프롬프트를 짧은 비디오 클립으로 변환하는 파이프라인(콘텐츠 도구, 프로토타입 백엔드, 내부 생성 서비스)을 구축 중이라면 이 가이드가 적합합니다. 동기 응답이 필요하거나 비디오 생성이 아닌 이미지 생성을 찾고 있다면 다른 엔드포인트가 더 적합합니다. 이 내용이 여러분의 사용 사례에 맞다면 계속 읽으면서 사전 요구 사항을 확인하세요.
사전 요구 사항 및 API Key 발급
첫 요청을 보내기 전에 세 가지를 확인하세요.
HiAPI 계정과 API Key
이 엔드포인트에 대한 모든 요청은 HiAPI 계정에 연결된 API Key로 인증합니다. 계정 대시보드에서 Key를 만들고 소스 관리에 커밋하지 마세요. 아래 예시는 환경 변수에서 이를 읽으므로 터미널이나 스크립트에 바로 붙여넣을 수 있고 키를 인라인으로 편집할 필요가 없습니다:
export HIAPI_API_KEY="your_api_key_here"
HTTPS 요청을 보낼 수 있는 클라이언트
curl 부분에는 curl이 필요하며 macOS와 대부분의 Linux 배포판에 기본 포함되어 있습니다. Python 부분에는 Python 3와 requests 라이브러리가 필요합니다(pip install requests). 벤더 전용 SDK는 필요하지 않습니다. 이 엔드포인트는 JSON 요청 본문을 사용하는 일반 HTTPS이므로 Node의 fetch부터 Python의 httpx까지 어떤 HTTP 클라이언트든 사용할 수 있습니다.
요청 간 상태를 저장할 방법
생성이 비동기이므로 제출 호출이 반환하는 작업 식별자를 어딘가에 저장해야 합니다. 데이터베이스 행, 작업 큐, 테스트 중에는 JSON 파일이면 됩니다. 폴링 대신 콜백을 사용할 계획이라면 HiAPI가 접근할 수 있는 HTTPS 엔드포인트도 필요합니다.
Key와 사용 가능한 클라이언트가 준비되면 요청을 제출할 수 있습니다.
curl로 첫 번째로 실제 동작하는 요청 보내기
제출 호출은 JSON 요청 본문을 사용하는 POST입니다. 정확한 엔드포인트 경로와 인증 헤더 이름은 모델 페이지에 기록되어 있으니 다른 API에서 추론하지 말고 그 값을 그대로 사용하세요. 호출 구조는 다음과 같습니다:
curl -X POST "$HIAPI_BASE_URL/v1/models/seedance-2.5-flash/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
}'
각 부분에 대한 몇 가지 설명:
- 메서드와 경로.
POST는 새 생성 작업을 만듭니다. 경로는 모델을 식별하며, 자체 설정에 복사하기 전에 모델 페이지와 대조해 확인하세요. - 요청 헤더.
Authorization헤더는 Key를 담고,Content-Type: application/json은 서버에 요청 본문을 어떻게 파싱할지 알려줍니다. - 요청 본문.최소한
prompt문자열을 보내야 합니다. 프롬프트는 창의적 입력이며 모델이 렌더링하는 모든 것은 여기서 나오므로 주체, 움직임, 조명, 카메라 동작을 명확히 설명하세요.
요청이 수락되면 응답에 작업 객체가 포함됩니다. 비디오 URL을 즉시 받지는 않습니다. 응답에서 작업 식별자를 추출해 저장하세요. 정확한 필드 이름은 모델 페이지에 기록된 응답 스키마의 일부이므로 이를 유일한 기준으로 삼고, 실제 응답을 보기 전에 추측한 값을 클라이언트에 하드코딩하지 마세요.
먼저 curl로 원시 응답을 확인한 다음, 그 형태를 이해한 후 동일한 호출을 코드로 옮길 수 있습니다.
파라미터 선택: 프롬프트, 해상도, 길이
prompt만 엄격히 필수이지만, 출력 결과와 요청 비용을 결정하는 몇 가지 선택적 파라미터가 있습니다. 기본값을 무심코 받아들이지 말고 의식적으로 설정하세요.
프롬프트
프롬프트는 영향력이 가장 큰 파라미터입니다. 촬영 감독에게 브리핑하듯 작성하세요. 주체, 동작, 환경, 조명, 카메라 스타일입니다. "A cyclist weaving through a neon-lit Tokyo street at night, handheld camera, shallow depth of field"는 "a city"보다 모델에 훨씬 많은 정보를 줍니다. 프롬프트는 모델 페이지에 기록된 길이 제한 안에서 유지하세요.
해상도
해상도가 높을수록 디테일과 출력 파일이 커지고 생성 시간도 길어질 수 있습니다. 비디오 생성은 보통 출력 길이로 과금되지만, 현재의 과금 기준과 해상도 등급은 가정하지 말고 가격 패널과 모델 문서에서 확인하세요. 전달 목표를 충족하는 가장 낮은 해상도를 선택하세요. 후처리 업스케일이 보통 전부를 최고 품질로 생성하는 것보다 저렴합니다.
길이
길이는 모델이 몇 초의 비디오를 생성할지 제어하며 보통 지연과 비용 모두에 영향을 줍니다. 짧은 클립이 반복 작업에 더 적합합니다. 짧은 길이로 프롬프트를 다듬어 움직임이 올바르게 보일 때까지 조정한 다음 최종 길이로 다시 생성하세요.
전송 전 검증
값을 프로덕션 코드에 연결하기 전에 모델 페이지에서 각 파라미터의 허용 범위(허용 길이, 지원 해상도, 모든 열거 값)를 확인하세요. 그런 다음 클라이언트에서 검증하세요. 요청이 프로세스를 떠나기 전에 범위를 벗어난 길이와 알 수 없는 해상도 값을 거부하세요. 이렇게 하면 한 부류의 서버 측 검증 오류를 자체 로그에서 즉시, 저비용으로 실패하게 바꿀 수 있습니다.
같은 규칙이 파라미터 이름에도 적용됩니다. 문서에서 복사하세요. 길이 필드에 밑줄이 하나 더 들어가는 식의 오타는 보통 거부되거나 조용히 무시되는데, 조용한 무시는 발견하기 더 어려운 버그입니다.
Python으로 동일한 요청 보내기
다음은 Python의 동등한 제출 코드입니다. 환경 변수에서 Key를 읽고, JSON 본문을 보내고, 상태 코드를 확인하고, 문서에 기록된 응답 필드에서 작업 식별자를 반환합니다.
import os
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
def submit_video(prompt: str, **options) -> str:
payload = {
"prompt": prompt,
**options, # e.g. resolution="720p", duration=5
}
response = requests.post(
f"{BASE_URL}/v1/models/seedance-2.5-flash/text-to-video",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=30,
)
response.raise_for_status()
body = response.json()
task_id = body["id"] # confirm the field name on the model page
return task_id
if __name__ == "__main__":
task_id = submit_video(
"A slow aerial shot over a misty pine forest at sunrise, soft light, cinematic"
)
print("submitted task:", task_id)
이 코드에는 몇 가지 의도적인 선택이 있습니다:
- 타임아웃.제출 호출은 빠르게 반환되어야 하지만, 명시적
timeout은 멈춘 소켓이 워커 프로세스를 차단하는 것을 방지합니다. raise_for_status().오류 응답 본문을 성공 응답처럼 파싱하지 않고 HTTP 오류에서 즉시 실패합니다.- 키워드 옵션.
**options를 전달하면 호출 지점이 읽기 쉬운 상태로 유지되고, 모델 페이지에서 정확한 이름을 확인한 후resolution이나duration을 추가하는 것이 매우 간단해집니다. - ID 반환.함수의 책임은 제출에서 끝납니다. 해당 ID를 영속 저장소에 저장하세요. 다음 절에서 이를 사용해 결과를 가져옵니다.
실제 파이프라인에서는 submit_video를 큐 기반 워크플로의 한 단계로 취급하세요. 큐에 넣고, 반환된 작업 ID를 작업 레코드와 함께 저장하고, 별도의 워커 프로세스가 결과 가져오기를 담당하게 하세요.
비동기 결과 처리: 폴링과 콜백
제출 후에는 작업 ID가 있지만 비디오는 아직 없습니다. 이 간극을 메우는 방법은 두 가지입니다.
폴링
일정 간격으로 작업 상태 엔드포인트를 폴링하여 작업이 터미널 상태에 도달할 때까지 확인한 다음, 완료된 응답에서 출력 URL을 가져옵니다.
import time
import requests
def wait_for_video(task_id: str, timeout_s: int = 600) -> dict:
deadline = time.time() + timeout_s
delay = 2.0
while time.time() < deadline:
response = requests.get(
f"{BASE_URL}/v1/tasks/{task_id}", # confirm path on the model page
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
task = response.json()
state = task["status"]
if state == "completed":
return task
if state == "failed":
raise RuntimeError(task.get("error", "generation failed"))
time.sleep(delay)
delay = min(delay * 1.5, 15) # gentle backoff, capped
raise TimeoutError(f"task {task_id} did not finish in time")
폴링에 대한 세 가지 실용 규칙:
- 백오프.짧은 지연으로 시작해 점진적으로 늘리세요. 지속적으로 높은 빈도의 폴링은 이점 없이 할당량을 낭비하고 부하를 증가시킵니다.
- 상한 설정.모든 폴링 루프에는 마감 시간이 필요합니다. 비디오 생성은 시간이 걸릴 수 있지만, 무한 루프는 결국 멈춘 작업 하나 때문에 워커 프로세스를 영원히 매달리게 합니다.
- 상태 구분.
failed를 명시적으로 처리하여 나쁜 프롬프트가 조용히 타임아웃으로 처리되지 않게 하세요.
콜백
HTTPS 콜백 URL을 등록하면 HiAPI가 작업 완료 시 알려줄 수 있어 폴링을 완전히 피할 수 있습니다. 콜백을 안전하고 신뢰할 수 있게 만드는 두 가지 규칙:
- 검증 후 신뢰.플랫폼 문서에 기록된 메커니즘으로 서명이나 출처를 검증하기 전까지 콜백을 인증되지 않은 입력으로 취급하세요.
- 멱등성 유지.콜백은 여러 번 전달될 수 있습니다. 작업 ID를 핸들러의 키로 사용하고 중복 전달 처리를 무동작으로 설정하세요. 결과는 한 번만 저장하고 중복 전달에는 확인 응답만 하세요.
어느 방식을 선택하든 결과 가져오기는 멱등적입니다. 완료된 작업의 결과 URL을 가져오면 동일한 비디오가 반환되어야 하므로 네트워크 오류 후 재시도가 안전합니다.
흔한 오류와 해결 방법
대부분의 실패는 몇 가지 유형으로 귀결됩니다. 문서에 없는 동작을 가정하기 전에 이 체크리스트를 항목별로 확인하세요.
인증 실패
401 또는 403은 거의 항상 Key가 없거나, 형식이 잘못되었거나, 만료되었음을 의미합니다. Authorization 헤더가 있는지, 인증 방식이 문서와 정확히 일치하는지, 환경 변수에 실제로 Key가 들어 있는지 확인하세요. 빈 문자열은 혼란스럽지만 인증과 관련된 실패를 만듭니다.
검증 거부
검증 메시지와 함께 오는 4xx는 서버가 파라미터를 거부했음을 의미합니다. 모델 페이지의 허용 범위를 다시 읽고 파라미터 이름을 문자 단위로 확인하세요. 길이나 해상도가 범위를 벗어난 경우 해결책은 앞서 설명한 클라이언트 측 검증입니다. 서버와 왕복하지 않고 자체 코드에서 빠르게 실패하게 하세요.
작업이 터미널 상태에 멈춤
폴링이 계속 completed 또는 failed를 보지 못하면 작업이 아직 실행 중이거나 폴링 루프가 잘못된 작업 ID를 조회하고 있을 수 있습니다. 제출한 ID와 폴링한 ID를 기록하고 비교하세요. 루프는 마감 시간을 강제해야 하며, 마감이 발동하면 무작정 재시도하지 말고 작업 ID를 노출해야 합니다.
콜백 후 결과가 도착하지 않음
콜백에 의존한다면 엔드포인트가 HTTPS로 공개 접근 가능한지, 무거운 작업을 인라인으로 수행하지 않고 빠르게 성공 상태를 반환하는지, 중복 전달이 멱등적으로 처리되는지 확인하세요. 콜백 핸들러가 같은 작업의 두 번째 전달에서 오류를 내면 결과가 손실된 것처럼 보입니다.
동일한 작업을 중복 제출
워커 프로세스가 타임아웃 후 제출 호출을 재시도하면 중복 작업이 생성될 수 있습니다. 엔드포인트를 호출하기 전에 자체 데이터베이스에 클라이언트 요청 키나 작업 ID를 기록하고 재시도 전에 이를 확인하여 제출을 여러분 쪽에서 멱등적으로 유지하세요.
일반 원칙: 실패가 발생하면 코드를 수정하기 전에 오류 응답 본문과 모델 문서를 먼저 읽으세요. 어떤 값이나 필드가 문서화되지 않았다면 존재한다고 가정하지 말고 모델 페이지에서 검증하고 요청을 그에 맞게 조정하세요.