블로그

튜토리얼

HiAPI API로 seedance-2.5-flash 참조 기반 비디오 생성 호출하기(curl + Python)

사용 가능한 요청, 실행 가능한 Python 스크립트, 그리고 비동기 작업 폴링 처리 방법

Nov 19, 2026
미니멀 건축 스타일 커버 이미지: 따뜻한 회색 콘크리트 평면이 비스듬히 들어오는 햇빛 각도로 교차하고, 짙은 청회색 그림자 면과 가는 세이지 그린 이음매가 포인트를 이룹니다.
이 페이지에서

참조 기반 비디오 생성의 실제 의미

참조 기반 비디오 생성은 모델에 두 가지를 동시에 제공하는 생성 모드입니다. 운동과 장면을 설명하는 텍스트 프롬프트, 그리고 화면 콘텐츠를 고정하는 하나 이상의 참조 소재입니다. 프롬프트는 의도("천천히 다가가며, 캐릭터가 돌아보고 미소 짓는다")를 담고, 참조 소재는 정체성과 외형(캐릭터, 제품, 시각적 스타일)을 담습니다.

이 워크플로의 모델 엔드포인트는 seedance-2.5-flash/reference-to-video이며, HiAPI 통합 API를 통해 제공됩니다. model, prompt, 참조 소재를 하나의 요청 본문에 함께 담아 보냅니다. 별도로 오케스트레이션해야 할 업로드 단계도, 유지해야 할 소재별 레지스트리도 없습니다.

실질적인 결과는 이것입니다. 이는 장시간 실행되는 작업입니다. 짧은 비디오라도 렌더링 시간은 텍스트 완성보다 훨씬 길기 때문에 API는 이 호출을 비동기 작업으로 취급합니다. 요청은 작업을 생성하고, 두 번째 호출이 그 결과를 가져옵니다. 이 "먼저 제출하고 나중에 폴링"하는 형태가 설계에서 가장 중요한 점이며, 이 튜토리얼의 나머지 부분이 구축해 나갈 방향입니다.

아래의 모든 내용은 HiAPI 인터페이스 안에 머뭅니다. 하나의 기본 URL, 하나의 인증 헤더, 하나의 엔드포인트 패밀리입니다.

첫 요청을 보내기 전에

첫 호출 전에 세 가지를 준비해야 합니다.

1. API 키

HiAPI 콘솔에서 키를 생성하고 소스 코드 관리에서 멀리 떨어뜨려 두세요. 아래 예시는 환경 변수에서 이를 읽습니다:

export HIAPI_API_KEY="your_key_here"

현재 키 형식이나 헤더 규약이 확실하지 않다면 콘솔의 플랫폼 API 문서를 확인하세요. 추측하지 말고, 공유할 수 있는 스크립트에 키를 하드코딩하지도 마세요.

2. 기본 URL과 인증 헤더

모든 호출은 HiAPI 기본 URL로 전송되며 Authorization 헤더에 키를 담습니다. 한 번 변수로 설정하면 모든 요청이 일관되게 유지됩니다:

export HIAPI_BASE_URL="https://api.hiapi.ai"

계정 문서에 명시된 대로 기본 URL을 정확히 사용하세요. 끝의 슬래시 불일치는 혼란스러운 404의 흔한 원인입니다.

3. 모델 엔드포인트

목표는 seedance-2.5-flash/reference-to-video입니다. 이 식별자를 경로에 넣지 말고 요청 본문에서 참조하세요. 그래야 나중에 모델을 바꿀 때 한 줄만 수정하면 됩니다.

또한 참조 소재를 URL로 접근 가능하게 해야 합니다(또는 엔드포인트 문서가 지정한 다른 소재 형식을 사용해야 합니다). 시작하기 전에 호스팅하고 공개적으로 접근 가능하게 만드세요. 깨진 참조 URL은 작업 제출은 성공하지만 생성 중에 실패하는 가장 흔한 원인입니다.

이 세 가지가 준비되면 요청 본문을 구성할 수 있습니다.

참조 소재로 요청 본문 구성하기

요청 본문에는 세 가지 개념적 부분이 있습니다. 어떤 모델을 사용할지, 무엇을 원하는지, 무엇을 참조할지입니다.

모델

model을 seedance-2.5-flash/reference-to-video로 설정하세요. 일반 문자열 필드로 취급하면 됩니다. URL 인코딩도, 경로 세그먼트도 필요 없습니다.

프롬프트

프롬프트는 희망 목록이 아니라 샷 설명으로 작성하세요. 주체, 동작, 카메라 동작, 리듬을 명시하세요. "빨간 재킷을 입은 사람이 카메라를 향해 걸어오고, 미디엄 샷, 천천히 다가가며, 부드러운 햇빛"은 "멋진 사람 비디오"보다 모델에 훨씬 더 많은 정보를 줍니다. 프롬프트를 제공한 참조 소재와 일치시키세요. 두 참조 소재가 서로 다른 캐릭터를 보여 준다면 어느 쪽이 주된 것인지 명시하세요.

참조 소재

참조 소재는 이 엔드포인트가 일반 텍스트 기반 비디오 생성 호출과 다른 점입니다. 프레임 전반에서 일관되게 유지되어야 할 콘텐츠를 정의하는 하나 이상의 소재를 전달합니다. 반복을 줄여 주는 실용적 규칙:

  • 정체성을 결정하는 최소한의 참조 소재를 사용하세요. 강력한 참조 하나가 평범한 참조 네 개보다 나은 경우가 많습니다.
  • 참조 소재끼리 일관성을 유지하세요. 충돌하는 각도나 스타일은 출력의 흔들림을 초래합니다.
  • 깨끗하고 조명이 좋은 원본 소재를 우선하세요. 잘렸거나 흐릿하거나 과도한 필터가 적용된 참조 소재는 그 결함을 그대로 전파합니다.
  • 제출 전에 모든 URL이 해석되는지 확인하세요 — 직접 한 번 가져와 보세요.

참조 소재가 요청 본문에서 정확히 어떻게 키로 지정되는지(배열 필드 이름, 객체 구조, 지원되는 소재 유형)는 HiAPI 문서의 엔드포인트 요청 스키마에서 가져와야 합니다. 기억에 의존하지 말고 그 스키마에 따라 요청 본문을 구성하세요. 그 스키마가 필드 이름의 권위 있는 출처이며, 키가 맞지 않으면 조용히 실패합니다.

요청이 네트워크에 도달하기 전에 JSON을 로컬에서 검증하세요(python -m json.tool body.json). 잘못된 형식의 요청 본문은 가장 쉽게 잡을 수 있는 오류이자 스택 트레이스에서 디버깅하기 가장 번거로운 오류입니다.

사용 가능한 curl 요청

다음 명령은 먼저 제출하고 나중에 폴링하는 패턴을 따릅니다. 작업을 생성하고, 폴링에 사용할 작업 식별자가 포함된 JSON 응답을 출력합니다.

curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-flash/reference-to-video",
    "prompt": "빨간 재킷을 입은 사람이 카메라를 향해 걸어오고, 미디엄 샷, 천천히 다가가며, 부드러운 햇빛",
    "references": [
      "https://your-cdn.example.com/refs/character-front.png",
      "https://your-cdn.example.com/refs/character-side.png"
    ]
  }'

참조 URL을 직접 호스팅한 소재로 바꾸고, 프로덕션에서 이 코드에 의존하기 전에 HiAPI 문서의 모델 페이지에서 엔드포인트 경로와 필드 이름을 확인하세요. 스키마 세부 사항이 권위 있으며 이 스니펫은 설명용입니다.

응답에서 주목할 내용:

  • id(또는 task/job 식별자) — 캡처하세요. 모든 폴링에 필요합니다.
  • 작업이 접수되었음을 나타내는 status 필드.
  • 무시되거나 거부된 소재에 대한 경고.

읽기 쉽게 예쁘게 출력하세요:

curl -sS -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json | python -m json.tool

요청 본문을 body.json에 저장하는 것은 그 작은 추가 수고만큼의 가치가 있습니다. 깔끔하게 버전 관리되고, 읽기 쉽게 비교되며, 셸 인용 오류를 디버깅 범위에서 제거합니다.

Python에서의 동일한 호출

다음은 Python에서의 동등한 호출로, 환경 변수를 설정한 후 바로 실행할 수 있게 작성했습니다. 표준 라이브러리만 사용하므로 아무것도 설치할 필요가 없습니다.

import json
import os
import urllib.request

BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]


def submit_reference_video(prompt, references):
    body = {
        "model": "seedance-2.5-flash/reference-to-video",
        "prompt": prompt,
        "references": references,
    }
    req = urllib.request.Request(
        f"{BASE_URL}/v1/videos/generations",
        data=json.dumps(body).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=60) as resp:
        payload = json.loads(resp.read().decode("utf-8"))
    return payload


if __name__ == "__main__":
    result = submit_reference_video(
        prompt="빨간 재킷을 입은 사람이 카메라를 향해 걸어오고, 미디엄 샷, 천천히 다가가며, 부드러운 햇빛",
        references=[
            "https://your-cdn.example.com/refs/character-front.png",
            "https://your-cdn.example.com/refs/character-side.png",
        ],
    )
    print(json.dumps(result, indent=2))
    job_id = result.get("id")
    print("job id:", job_id)

두 가지 세부 사항이 보이는 것보다 중요합니다. 첫째, timeout=60 — 제출 호출은 빠르게 반환되어야 하지만, 멈춘 연결은 빠른 실패보다 나쁩니다. 둘째, result.get("id")는 응답 구조가 예상과 다를 때 정상 경로에서 KeyError를 던지는 대신 처리합니다.

requests나 httpx를 더 선호한다면 변환은 간단합니다. 같은 URL, 같은 헤더, 같은 JSON 요청 본문입니다. 요청 본문 구성이 복사할 가치가 있는 부분이며, HTTP 클라이언트는 교체 가능합니다.

완료될 때까지 비동기 작업 폴링하기

비디오 생성은 기다릴 수 있는 요청이 아닙니다. 제출하고, 식별자를 받고, 작업이 종료 상태에 도달할 때까지 주기적으로 상태를 확인합니다. 이를 안전하게 만드는 두 가지 특성이 있습니다. 폴링 오버헤드는 낮고, 제출 호출이 이미 비용이 큰 작업을 완료했습니다.

루프

import time

def wait_for_video(job_id, timeout_s=600, interval_s=5):
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        req = urllib.request.Request(
            f"{BASE_URL}/v1/videos/generations/{job_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        with urllib.request.urlopen(req, timeout=30) as resp:
            job = json.loads(resp.read().decode("utf-8"))

        status = job.get("status")
        if status in ("succeeded", "completed"):
            return job
        if status in ("failed", "error", "cancelled"):
            raise RuntimeError(f"job {job_id} ended with status {status}: {job.get('error')}")
        time.sleep(interval_s)

    raise TimeoutError(f"job {job_id} did not finish within {timeout_s}s")

더 촘촘한 루프가 더 빠르지는 않습니다. 단지 속도 제한을 소진할 뿐입니다. 비디오 작업에는 5초 간격이 합리적인 기본값입니다.

설계 참고 사항

  • 항상 마감 시간을 설정하세요. 종료되지 않는 작업이 요청 스레드를 영원히 매달아 두어서는 안 됩니다.
  • 알 수 없는 상태는 성공이 아니라 "계속 대기"로 취급하세요. 명확한 성공만이 성공입니다.
  • 웹 요청 처리기 안에서 폴링하지 마세요. 처리기에서는 제출만 하고 작업 id를 클라이언트에 반환한 뒤, 백그라운드 작업자 프로세스가 폴링하고 결과를 영속화하게 하세요.
  • 작업 id와 상태 전이를 영속화하세요 그래야 중단된 프로세스가 다시 제출해 렌더링 비용을 두 번 지불하지 않고 복구할 수 있습니다.

이렇게 먼저 제출하고 나중에 폴링하는 분리가 느린 비디오 파이프라인을 빠른 API 뒤에 둘 수 있게 하는 이유입니다.

흔한 오류와 해결 방법

첫 한 시간 동안의 거의 모든 실패는 네 가지 범주 중 하나에 속합니다. 이 순서대로 확인하세요.

1. 인증

증상: 작업이 생성되기 전에 권한 없음 또는 금지 응답이 나옵니다.

확인: 스크립트를 실행하는 셸이나 프로세스에서 HIAPI_API_KEY가 실제로 채워졌나요? 헤더가 정확히 Authorization: Bearer <key>인가요? 스크립트가 나중에 사용할 것으로 예상하는데 임포트 시점에 키를 로드하고 있나요? 파싱된 키의 처음 몇 글자(키 전체는 절대 출력하지 마세요)를 출력해 빈 문자열이 아님을 확인하세요.

2. 엔드포인트 경로

증상: 찾을 수 없음, 보통 즉시 나타납니다.

확인: 기본 URL과 경로 사이에 슬래시가 정확히 하나인지 — 이것이 Python 예제가 .rstrip("/")를 호출하는 이유입니다. 문서의 모델 페이지에서 생성 경로와 폴링 경로를 확인하세요. 작업 id 세그먼트가 빠진 폴링 URL은 매번 404가 납니다. 서버가 기대하지 않는 끝의 슬래시도 같은 증상을 일으킵니다.

3. 잘못된 형식의 요청 본문

증상: 검증 오류, 또는 작업이 접수된 직후 실패.

확인: json.dumps(body)를 실행해 검사하세요. model이 seedance-2.5-flash/reference-to-video와 정확히 일치하나요? 참조 필드가 배열이고 각 항목이 브라우저에서 해석 가능한 문자열 URL인가요? Content-Type: application/json을 보냈나요? 요청 본문을 python -m json.tool에 통과시켜 네트워크에 도달하기 전에 구문 오류를 배제하세요.

4. 작업 상태

증상: 제출 호출이 성공했지만 작업이 실패하거나 영원히 완료되지 않습니다.

확인: 상태 응답의 오류 필드를 읽으세요. 보통 원인을 지적하며, 가장 흔한 것은 접근 불가능하거나 지원되지 않는 참조 소재입니다. 작업이 그저 멈춰 있다면 올바른 id를 폴링하고 있는지, 루프의 상태 비교가 API가 실제로 반환하는 종료 상태를 포함하는지 확인하세요. 모든 상태 전이를 기록하세요. 실패 직전의 마지막 상태가 진단 근거입니다.

네 가지 범주의 문제 해결을 모두 단축하는 규칙 하나: 모든 호출에 대해 요청 id와 작업 id를 기록하세요. 장애가 발생하면 하나의 id가 모호한 오류 보고를 구체적인 조회로 바꿔 줍니다.

다음 단계

이제 전체 형태를 갖추었습니다. 프롬프트와 참조 소재로 요청 본문을 구성하고, 제출하고, 종료될 때까지 폴링하며, 네 가지 흔한 실패를 처리합니다. 여기서부터 자연스러운 다음 단계는 API 수준이 아니라 엔지니어링 수준입니다.

  • 일시적 네트워크 오류를 위해 지수 백오프를 적용한 재시도로 제출을 감싸세요, 하지만 이미 id가 있는 작업은 절대 재시도하지 마세요 — 그것은 중복 렌더링입니다.
  • 폴링을 작업자 프로세스나 큐로 옮기세요 그래야 HTTP 계층이 응답성을 유지하고 작업이 프로세스 재시작 후에도 살아남습니다.
  • 작업 id를 자체 요청 메타데이터(프롬프트, 참조 소재, 요청 사용자)와 함께 저장하세요 그래야 몇 달 후에도 결과를 추적할 수 있습니다.
  • 검증을 통과한 후에만 참조 소재를 허용하세요 — 사용자가 각 URL을 제공할 때 가져와 보고, 그다음에 작업 비용을 지출하세요.

권위 있는 요청 스키마, 지원되는 소재 형식, 최신 엔드포인트 세부 사항은 HiAPI의 seedance-2.5-flash 참조 기반 비디오 생성 모델 페이지를 참고하세요. 그 스키마에 기반해 구축하고 먼저 제출하고 나중에 폴링하는 분리를 유지하면, 통합은 평범하게 유지됩니다. 그것이 바로 비디오 파이프라인에서 바라는 것입니다.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기