블로그

튜토리얼

seedance-2.5 이미지-투-비디오 API 호출 방법: 사용 가능한 curl 및 Python 예제

Nov 12, 2026
추상 커버 아트: 겹겹이 포개진 반투명 유리 판이 옅은 회색 바탕 위로 서늘한 푸른 띠를 드리우며, 평면적이고 건축적인 느낌을 준다.
이 페이지에서

seedance-2.5 이미지-투-비디오 엔드포인트가 제공하는 것

seedance-2.5 이미지-투-비디오는 HiAPI의 비동기 모델 엔드포인트로, 한 장 또는 두 장의 정적 이미지를 짧은 비디오로 변환합니다. 이미지(또는 모션의 시작점과 끝점 역할을 하는 이미지 쌍)를 보내고 원하는 변화를 설명하면, 플랫폼은 작업을 반환하며 생성이 완료되면 해당 작업이 비디오 파일 URL로 해석됩니다.

일반적인 비디오 생성 기술 스택에서 이 엔드포인트는 "정적 이미지에 움직임을 부여하는" 계층에 위치합니다. 이미 소스 이미지—제품 사진, 캐릭터 렌더링, 스토리보드 프레임—는 있고, 새 이미지가 아니라 모션이 필요한 상황입니다. 호출이 비동기이므로 당신의 역할은 작업을 제출하고, 작업 식별자를 보관하고, 결과가 준비될 때까지 계속 폴링하는 것입니다. 이러한 제출 후 폴링 패턴은 HiAPI의 장시간 실행 생성 엔드포인트 전반에 공통되므로, 여기서 작성하는 클라이언트는 다른 모델로도 이전할 수 있습니다.

이 엔드포인트는 네이티브 오디오 옵션도 제공합니다. 처리 흐름이 나중에 사운드를 입히는 무음 소재가 아니라 소리가 포함된 비디오 클립을 필요로 한다면 이 점이 중요합니다. 프레임 단위로 정확한 카메라 무브먼트나 반복 재생 가능한 모션이 필요하다면, 명시적인 첫 프레임과 마지막 프레임을 사용한 이미지-투-비디오가 3D 장면을 구축하지 않고도 가장 제어하기 쉬운 선택인 경우가 많습니다.

사전 준비 사항과 인증

첫 호출 전에 세 가지를 준비하세요.

1. HiAPI API 키

모든 요청은 키로 인증하며, bearer token 형태로 Authorization 요청 헤더에 담아 전송합니다. 소스 관리에 커밋하지 말고 환경 변수에서 읽어 오세요. 그러면 같은 스크립트를 로컬에서도 CI에서도 실행할 수 있습니다.

export HIAPI_API_KEY="your_key_here"

2. API가 가져올 수 있는 소스 이미지

이미지 입력은 URL입니다. 이미지를 서비스가 접근할 수 있는 위치—서명 URL이 있는 오브젝트 스토리지, CDN, 또는 임의의 공개 HTTPS 주소—에 호스팅하세요. 이미지를 공개적으로 노출하고 싶지 않다면 버킷을 공개로 설정하는 대신 짧은 만료 시간의 서명 URL을 생성하세요.

첫 프레임/마지막 프레임 워크플로에서는 이미지 한 장(첫 프레임만) 또는 두 장(첫 프레임과 마지막 프레임)이 필요합니다.

3. HTTP 클라이언트

JSON을 보낼 수 있는 도구라면 무엇이든 됩니다. 빠른 스모크 테스트용 curl, Python의 requests 또는 httpx, Node의 fetch 등이 있습니다. 특별한 SDK는 필요하지 않습니다.

이 모델의 구체적인 기본 URL, 경로, 필드 이름은 HiAPI 콘솔의 모델 페이지에 있으니 아래 예제에서 해당 값들을 그대로 사용하세요. 키와 이미지 URL이 준비되면 제출할 수 있습니다.

첫 프레임 입력과 마지막 프레임 입력

두 이미지 입력은 비디오 클립의 서로 다른 끝점을 제어하며, 어느 쪽을 선택하느냐에 따라 모션 제어 수준이 달라집니다.

첫 프레임만. 이미지 한 장을 제공하면 모델이 그 이미지에서 앞으로 생성합니다. 모델이 스스로 모션을 창작하기를 원할 때 올바른 선택입니다. 천천히 돌아서는 인물 사진, 회전하는 제품, 구름이 흐르는 풍경 등이 그렇습니다. 클립이 끝나는 지점에 대한 확정성은 포기하지만 더 큰 창작 여지를 얻고 소재도 하나만 있으면 됩니다.

첫 프레임과 마지막 프레임. 이미지 두 장을 제공하면 모델이 그 사이의 경로를 생성합니다. 끝점이 중요할 때 올바른 선택입니다. 최종 합성 로고로 조립되는 로고, 포즈 A에서 포즈 B로 이동하는 캐릭터, 화면 왼쪽에서 오른쪽으로 미끄러지는 물체 등이 그렇습니다. 마지막 프레임을 제공하면 모션이 제약되므로 보통 예상 밖의 결과가 줄고, 클립을 반복 재생할 계획이라면 루프 품질도 좋아집니다.

실용적인 규칙 하나: 클립을 "이 이미지에 어떤 변화가 일어난다"로 설명할 수 있다면 첫 프레임만 사용하세요. "이 이미지가 저 이미지로 변한다"로 설명할 수 있다면 두 장을 제공하세요. 두 장을 제공할 때는 구도, 가로세로 비율, 조명이 일치하도록 유지하세요. 맞지 않는 이미지 쌍은 모델로 하여금 결함처럼 보이는 점프를 처리하게 만듭니다.

프롬프트는 이미지와 충돌하지 않고 보완해야 합니다. 모델이 이미 볼 수 있는 정적 내용이 아니라 모션을 설명하세요.

curl로 첫 요청 제출하기

다음 요청은 이미지-투-비디오 작업을 제출합니다. 엔드포인트 경로, 모델 식별자, 필드 이름을 HiAPI 콘솔의 seedance-2.5 이미지-투-비디오 모델 페이지에 표시된 값으로 바꾸고, 자신의 이미지 URL로 교체하세요.

curl -X POST "$HIAPI_BASE_URL/<image-to-video-path>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5/image-to-video",
    "prompt": "카메라가 천천히 푸시인하며 피사체가 빛을 향해 고개를 돌린다",
    "first_frame_image": "https://your-cdn.example.com/frame-01.jpg",
    "last_frame_image": "https://your-cdn.example.com/frame-02.jpg"
  }'

요청 구조에서 몇 가지 주의할 점이 있습니다:

  • prompt는 모션을 설명합니다. 짧고 구체적으로 유지하세요. 형용사 나열이 많으면 지시가 희석되는 경우가 많습니다.
  • first_frame_image는 이미지-투-비디오에 필수입니다. last_frame_image는 선택 사항이므로 첫 프레임만 생성할 때는 이 필드를 완전히 제거하세요.
  • 오디오 옵션이 필요하다면 같은 JSON 본문에 추가 필드로 넣습니다(아래에서 다룹니다).

응답은 식별자와 상태를 포함한 작업 객체입니다. 이 식별자를 저장하세요. 폴링할 때마다 필요합니다. 호출이 인증 또는 검증 오류를 반환하면 재시도하기 전에 먼저 요청 헤더와 이미지 URL을 확인하세요.

Python에서의 동일한 요청

다음은 Python에서의 동등한 제출 코드로, 작업 식별자를 쉽게 잡을 수 있도록 재구성한 것입니다.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<image-to-video-path>"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_video(first_frame, last_frame=None, prompt="", audio=False):
    payload = {
        "model": "seedance-2.5/image-to-video",
        "prompt": prompt,
        "first_frame_image": first_frame,
    }
    if last_frame:
        payload["last_frame_image"] = last_frame
    if audio:
        payload["audio"] = True

    resp = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    data = resp.json()
    return data["task_id"], data

task_id, raw = submit_video(
    first_frame="https://your-cdn.example.com/frame-01.jpg",
    last_frame="https://your-cdn.example.com/frame-02.jpg",
    prompt="카메라가 천천히 푸시인하며 피사체가 빛을 향해 고개를 돌린다",
)
print(task_id)

일찍 들여야 할 습관 두 가지가 있습니다. 첫째, 제출 호출에 명시적인 timeout을 설정하세요. 멈춘 요청은 워커를 막는 대신 빠르게 실패해야 합니다. 둘째, 개발 중에는 원시 응답을 보관하세요. 작업 식별자를 저장하는 필드는 엔드포인트 버전에 따라 task_id와 다를 수 있으므로, 원시 JSON을 한 번 출력해 두면 디버깅 순환을 한 번 줄일 수 있습니다.

비디오가 준비될 때까지 비동기 작업 폴링하기

이미지-투-비디오 생성은 하나의 HTTP 요청을 열어 두어야 하는 시간보다 오래 걸리므로, 플랫폼은 제출 후 폴링하는 생명주기를 사용합니다. 제출은 작업 식별자를 반환하고, 그다음 작업 엔드포인트를 주기적으로 조회하여 상태가 종료 상태에 도달할 때까지 기다립니다.

import time
import requests

def wait_for_video(task_id, interval=5, max_wait=600):
    url = f"{BASE_URL}/<task-path>/{task_id}"
    deadline = time.time() + max_wait
    while time.time() < deadline:
        resp = requests.get(url, headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()
        status = task.get("status")
        if status == "succeeded":
            return task["video_url"]
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"Task {task_id} ended as {status}: {task.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} not ready after {max_wait}s")

네 가지 규칙을 중심으로 폴링을 설계하세요:

  • 적당한 간격으로 폴링하세요. 5초가 합리적인 기본값입니다. 엔드포인트를 마구 두드려도 비디오가 더 빨리 렌더링되지는 않습니다.
  • 항상 마감 시간을 설정하세요. 작업이 실패하거나 예상보다 오래 대기열에 있을 수 있습니다. 무한 루프는 일시적 문제를 멈춘 워커로 바꿔 놓습니다.
  • failed와 cancelled를 종료 상태로 취급하세요. 같은 작업을 영원히 재시도하지 말고 오류 필드를 드러내세요.
  • 지속적인 폴링에는 백오프를 사용하세요. 많은 작업을 동시에 폴링한다면 간격을 점진적으로 늘려 트래픽 폭주를 피하세요.

프로덕션에서는 웹 요청 핸들러 내부가 아니라 백그라운드 워커나 큐에서 폴링하세요. 결과는 비디오 URL입니다. 생성된 리소스 URL은 보통 영구적이지 않으므로 즉시 다운로드하여 자신의 스토리지에 복사하세요.

네이티브 오디오 플래그 처리하기

seedance-2.5는 네이티브 오디오가 포함된 클립을 생성할 수 있으며, 이 제어 항목은 별도 엔드포인트가 아니라 이미지 입력 및 프롬프트와 나란한 요청 필드입니다. 정확한 필드 이름과 허용 값은 모델 페이지에 나열되어 있으며, 위의 Python 헬퍼는 audio 불리언 값을 전달하여 예시합니다.

활성화 여부는 클립이 어떻게 소비되는지에 달려 있습니다.

다음의 경우 오디오를 요청하세요: 출력이 수신자에게 직접 전달되는 경우—소셜 게시물, 미리보기, 데모—로, 클립이 2차 편집 없이도 완성된 느낌을 주기를 원할 때입니다. 네이티브 오디오는 소리가 모션 타이밍을 더 읽기 쉽게 만들어 주므로 리뷰어가 리듬을 판단하는 데도 도움이 됩니다.

다음의 경우 오디오를 생략하세요: 처리 흐름이 자체 사운드트랙을 입히는 경우, 클립이 합성 또는 편집 도구로 들어가는 경우, 또는 많은 변형을 생성하되 최종 선택된 버전에만 사운드를 입힐 계획인 경우입니다. 무음 생성은 소재를 중립적으로 유지하고 이후의 동기화 문제를 피합니다.

범위를 좁히는 실용적인 조언 하나: 오디오는 전역 설정이 아니라 요청별 결정으로 취급하세요. 위에서처럼 audio 플래그를 받는 단일 헬퍼를 두면 같은 코드 경로가 무음 백그라운드 배치 처리와 정교한 최종 렌더링 모두를 지원할 수 있습니다.

플래그는 있지만 결과가 무음이라면, 모델이 무시했다고 가정하기 전에 먼저 그 값이 의도대로 직렬화되었는지 확인하세요. 문자열 "true"와 불리언 true의 불일치가 흔한 원인입니다.

흔한 실패 지점과 다음 단계

대부분의 첫 통합 문제는 네 가지 범주에 속합니다.

서비스가 가져올 수 없는 입력

브라우저에서는 작동하는 URL이 서버 측에서는 실패할 수 있습니다. 비공개 버킷, 만료된 링크, 비브라우저 사용자 에이전트를 차단하는 호스트 등이 그렇습니다. 전체 생성 과정을 커버할 만큼 수명이 긴 서명 URL을 사용하고, 이미지가 당신의 네트워크 외부 머신에서 로드되는지 확인하세요.

맞지 않는 프레임

첫 프레임과 마지막 프레임의 가로세로 비율, 크롭, 색온도가 다르면 모델이 그 점프를 조화시켜야 합니다. 제출 전에 이미지 쌍을 같은 크기와 유사한 색조로 전처리하세요.

잘못된 필드 이름 또는 모델 식별자

여기의 예제는 모델 페이지의 요청 구조를 사용합니다. 기억이나 오래된 스니펫에 의존하지 말고 콘솔에서 필드 이름과 모델 문자열을 그대로 복사하세요. 필드 이름의 오타는 거부되지 않고 조용히 무시되는 경우가 많습니다.

끝나지 않는 폴링

루프가 계속 시간 초과된다면 관찰한 모든 상태 값을 기록하세요. 예상치 못한 상태 문자열을 보면 정체 원인이 설명되는 경우가 많습니다. 종료 상태 검사가 API가 반환하는 내용과 맞지 않을 수 있습니다.

단일 클립이 엔드투엔드로 작동하면, 자연스러운 다음 단계는 같은 제출 후 폴링 헬퍼로 여러 이미지를 배치 처리하고, 제출 주변에 백오프가 있는 재시도를 추가하고, 결과를 영구 스토리지에 쓰는 것입니다. 엔드포인트 세부 정보, 요청 필드, 파라미터 참조는 seedance-2.5 이미지-투-비디오 모델 페이지에서 찾아 위 코드를 자신의 이미지에 맞게 조정하세요.

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

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

API 문서 보기