Seedance 2.5 텍스트-투-비디오 API 사용법은? curl과 Python으로 바로 실행

TL;DR

• seedance-2.5/text-to-video는 프롬프트 하나만으로 영상을 생성하며, 단일 4–30초, 사운드 포함입니다. 모델 페이지 열기에서 온라인으로 생성할 수 있고, 신규 가입 시 200 크레딧을 증정합니다.
• 초 단위 과금: 720p 초당 $0.204, 1080p 초당 $0.516. 5초 720p는 $1.02입니다.
• API는 두 단계: POST /v1/tasks로 제출하고 taskId로 결과를 조회합니다. 아래 curl과 Python은 복사해서 바로 실행할 수 있습니다.

먼저 실제 결과물 보기

아래 8초 720p 영상은 프롬프트 하나, 요청 한 번으로 생성되었으며 우유 스티밍 소리, 컵 부딪히는 소리, 매장 내 사람 소리는 모두 모델이 직접 생성한 것입니다:

A barista in a small morning cafe pours steamed milk into a cup, drawing a latte art leaf.
The camera starts on her hands and slowly pulls back to reveal the counter and a sign on the wall that reads 'OPEN'.
Warm window light, realistic, smooth motion. Sound: milk steaming, cups clinking, quiet cafe chatter.

이 프롬프트로 생성하기 →(8초, 720p)

seedance-2.5/text-to-video, 720p, 8초, 사운드 포함, $1.632.

두 가지 시작 방법

온라인 체험(코딩 불필요)

1. Seedance 2.5 텍스트-투-비디오 모델 페이지를 열고 회원가입 또는 로그인합니다.
2. 프롬프트를 붙여넣고 길이, 해상도, 화면 비율을 선택합니다.
3. 생성을 클릭하고, 완성되면 바로 다운로드합니다.

API 호출

1. 콘솔에서 API Key를 생성합니다.
2. POST https://api.hiapi.ai/v1/tasks로 작업을 제출하고 taskId를 받습니다.
3. GET /v1/tasks/{taskId}로 상태를 조회하고, status가 success이면 output[0].url에서 영상을 다운로드합니다.

curl: 첫 영상

먼저 5초 720p, $1.02를 실행합니다:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5/text-to-video",
    "input": {
      "prompt": "一架纸飞机滑过洒满阳光的办公室，灰尘在光里漂浮，镜头跟着纸飞机缓慢移动",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

응답:

{"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

결과 조회:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

생성 중에는 status가 handling이고, 완료되면 success로 바뀌며 영상 주소는 output[0].url에 있습니다.

Python: 제출, 폴링, 다운로드

# pip install requests；先 export HIAPI_KEY=你的 Key
import os, time, uuid, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}

def generate(prompt, model="seedance-2.5/text-to-video", timeout_s=900, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    # 重试提交同一个任务时带同一个 Idempotency-Key，避免重复扣费
    headers = {**H, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post("https://api.hiapi.ai/v1/tasks", json=body, headers=headers, timeout=30)
    r.raise_for_status()
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate(
    "一架纸飞机滑过洒满阳光的办公室，灰尘在光里漂浮，镜头跟着纸飞机缓慢移动",
    duration=5, resolution="720p", aspect_ratio="16:9",
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

파라미터 일람

파라미터	값	설명
prompt	문자열, 필수	중국어와 영어 모두 가능
duration	4–30 정수, 기본값 5	단위 초, 초 단위 과금
resolution	720p / 1080p, 기본값 720p	1080p 단가는 720p의 약 2.5배
aspect_ratio	16:9 4:3 1:1 3:4 9:16 21:9 adaptive, 기본값 adaptive	세로형 숏폼 영상은 9:16 사용
generate_audio	기본값 true	사운드와 화면을 함께 생성
output_format	mp4 / mov

텍스트-투-비디오는 어떤 이미지나 영상 주소도 받지 않습니다. 한 장의 이미지에서 시작하려면 Seedance 2.5 이미지-투-비디오로, 기존 영상의 동작과 카메라 워크를 참고하려면 Seedance 2.5 레퍼런스-투-비디오로 전환하세요.

비용 계산

길이	720p($0.204/초)	1080p($0.516/초)
5초	$1.02	$2.58
10초	$2.04	$5.16
15초	$3.06	$7.74
30초	$6.12	$15.48

$10으로 720p 기준 약 49초를 생성할 수 있습니다. 먼저 720p 짧은 길이로 프롬프트를 다듬은 뒤 1080p 최종본을 만드는 것을 권장합니다. 더 자세한 계산은 Seedance 2.5 API 가격을 참고하세요.

출시 전 유의사항

• 폴링 대신 콜백 사용: 요청 최상위(input과 같은 레벨)에 "callback": {"url": "https://你的域名/hiapi/callback"}를 추가하면 작업 종료 시 HiAPI가 능동적으로 알리며, taskId로 중복을 제거합니다.
• 즉시 전송: output[0].url은 임시 링크(기본 보관 약 7일)이므로 받은 즉시 자체 스토리지에 저장하세요.
• 재시도 시 멱등 키 사용: 요청 헤더에 Idempotency-Key를 추가하면 같은 키로 재시도해도 작업이 한 번만 생성되어 중복 과금이 없습니다.
• 파라미터 전부 기재: duration, resolution, aspect_ratio를 명시해야 비용과 화면 비율이 예산과 맞습니다.
• 실패 시 자동 환불: 성공적으로 생성된 영상에만 과금됩니다.

자주 묻는 질문

프롬프트를 중국어로 써도 되나요?

됩니다. 카메라가 어떻게 움직이는지, 피사체가 어떻게 움직이는지, 어떤 사운드가 있는지를 문장으로 나눠 쓰면 가장 안정적입니다.

최대 길이는 얼마인가요?

단일 4–30초입니다. Seedance 2.0의 15초 상한보다 두 배 길어 원테이크 롱숏에 적합합니다.

사운드를 끄면 비용이 절약되나요?

generate_audio를 false로 설정하면 사운드를 끌 수 있지만, 가격은 해상도와 초 수 기준이라 저렴해지지 않습니다.

Seedance 2.0과 어떻게 선택하나요?

더 긴 단일 영상과 더 많은 레퍼런스 소재가 필요하면 2.5를, 예산 우선이거나 4K가 필요하면 2.0의 ext 라인(720p 초당 $0.134)을 선택하세요. 자세한 비교는 Seedance 2.5와 2.0의 차이를 참고하세요.

더 많은 예시 프롬프트는 Seedance 2.5 사용 매뉴얼을 참고하거나, 위의 라떼 아트 프롬프트를 복사해 모델 페이지에서 생성하기를 이용하세요.