hiapi API로 seedance-2.0-fast 사용하는 방법: curl, Python 및 실행 가능한 요청

이 가이드는 seedance-2.0-fast로 비디오를 생성하기 위한 최소 요청, 이 모델이 실제로 허용하는 모든 입력 필드, 그리고 폴링 또는 콜백으로 결과를 기다리는 방법을 보여줍니다. 아래의 모든 요청 구조와 오류 메시지는 실제 API에서 실행 검증되었으므로, 코드를 그대로 복사해 사용할 수 있습니다.

무엇을 만들고 무엇을 준비해야 하나요

목표는 단 하나입니다: 텍스트 프롬프트를 보내고 다운로드 가능한 MP4 URL을 받아오기.seedance-2.0-fast는 Seedance 2.0의 속도 최적화 버전으로, 최고 해상도(720p 상한)를 희생해 더 빠른 생성 속도를 얻습니다. 따라서 미리보기, 반복 작업, 대량의 짧은 비디오 클립에 매우 적합합니다.

필요한 것은 단 하나, hiapi API 키입니다. 대시보드에서 받으세요. 형식은 sk-...와 같습니다. 모든 비디오 모델(이 모델 포함)은 통합 비동기 작업 엔드포인트로 제공됩니다. 먼저 POST /v1/tasks로 작업을 생성한 다음, 작업 ID로 결과를 가져옵니다. 비디오에는 동기 모드가 없습니다.

현재 단일 클립 가격은 가격 페이지에서 확인하세요(이 모델이 막 출시되었으므로 블로그 글의 숫자를 믿지 말고 해당 페이지를 기준으로 삼으세요).

최소 실행 예제(curl)

작업 생성:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "input": {
      "prompt": "A paper boat drifts down a rain-soaked street at dusk, cinematic, slow dolly-in",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

응답에서 작업 ID는 data.taskId에 있습니다:

{
  "data": {
    "taskId": "task_abc123..."
  }
}

상태가 종료 상태가 될 때까지 해당 작업을 폴링합니다:

curl "https://api.hiapi.ai/v1/tasks/task_abc123..." \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status가 "success"일 때 비디오 URL은 data.output[0].url에 있습니다. 이 URL은 서명되어 있으며 만료됩니다——즉시 파일을 다운로드하고 핫링크하지 마세요:

curl -o clip.mp4 "<the output url>"

모든 입력 필드(검증됨)

오직 prompt만 필수입니다. 이 표에 없는 필드는 400으로 거부됩니다——이 스키마는 추가 속성을 허용하지 않습니다.

필드	타입	필수	허용 값
prompt	string	예	최소 길이 3자
duration	정수	아니오	4–15(초)
resolution	string	아니오	480p, 720p
aspect_ratio	string	아니오	1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive

두 가지를 특히 짚고 넘어갈 만합니다:

• duration은 문자열이 아니라 정수입니다."duration": "5"를 보내면 검증 실패하며, 오류는 duration: got string, want integer입니다.
• 이미지 입력이 없습니다.seedance-2.0-fast는 텍스트-비디오만 지원하며, image_urls 같은 필드는 스키마에서 거부됩니다. 이미지-비디오가 필요하다면 이미지-비디오 API 워크플로 가이드에서 해당 기능을 지원하는 모델을 확인하세요.

Python에서의 동일한 흐름

SDK는 필요 없습니다——requests면 충분합니다:

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-YOUR_KEY",
    "Content-Type": "application/json",
}

def create_task(prompt: str, duration: int = 5,
                resolution: str = "720p", aspect_ratio: str = "16:9") -> str:
    payload = {
        "model": "seedance-2.0-fast",
        "input": {
            "prompt": prompt,
            "duration": duration,
            "resolution": resolution,
            "aspect_ratio": aspect_ratio,
        },
    }
    r = requests.post(API_BASE, json=payload, headers=HEADERS, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task(
    "A barista pours latte art in a sunlit cafe, shallow depth of field"
)
task = wait_task(task_id)
video_url = task["output"][0]["url"]

# The URL is signed and expires — persist the bytes immediately.
with open("clip.mp4", "wb") as f:
    f.write(requests.get(video_url, timeout=120).content)
print("saved clip.mp4")

success / fail 외의 모든 상태를 "아직 실행 중"으로 취급하세요——이렇게 하면 중간 상태 이름이 나중에 바뀌더라도 루프가 견고하게 작동합니다.

프로덕션 환경 고려 사항

폴링 대신 콜백 사용

스크립트 외의 모든 상황에서는 작업 생성 시 콜백을 등록하여 폴링을 완전히 건너뛰세요:

{
  "model": "seedance-2.0-fast",
  "input": { "prompt": "..." },
  "callback": { "url": "https://your-app.com/hooks/hiapi", "when": "final" }
}

"when": "final"을 사용하면 작업이 종료 상태에 도달했을 때 엔드포인트가 정확히 한 번 POST를 받습니다. 폴링은 CLI와 노트북에 적합하며, 대규모로 실행할 때는 콜백이 더 우수합니다(낭비되는 요청도 없고 폴링 간격으로 인한 지연도 없습니다). 훅이 발생하지 않는 것 같으면 콜백 문제 해결 가이드를 참고하세요——거의 항상 URL 접근성 문제이거나 핸들러가 2xx가 아닌 응답을 반환한 경우입니다.

멱등성

작업 생성은 무료가 아니므로, 중복 제출을 방지해야 합니다: 각 비즈니스 이벤트가 최대 한 번의 POST /v1/tasks 호출에 대응하도록 하세요(예: 재시도 전에 taskId를 주문/작업 행과 연결해 저장). 프로세스가 작업 생성 후 충돌하면, 저장된 taskId를 다시 읽고 GET /v1/tasks/<id>로 복구할 수 있습니다——폴링 여부와 관계없이 작업은 서버에서 계속 실행됩니다.

실제로 마주하게 될 오류

증상	의미	해결
400 및 error_code: "INVALID_REQUEST"	입력이 스키마 검증을 통과하지 못함; message가 구체적 필드를 지목합니다, 예: duration: maximum: got 20, want 15	해당 필드를 수정하세요; 위 표의 네 필드만 허용됩니다
401 및 error.code: "permission_denied"	키가 유효하지 않거나, 유효하지만 이 모델에 대해 활성화되지 않음	대시보드에서 키를 확인하세요; 모델 권한은 키별로 설정됩니다
GET 시 404 및 "task not found"	작업 ID가 잘못되었거나 해당 계정 소유가 아님	생성 시 반환된 taskId를 사용하고, 동일 계정인지 확인하세요
작업 상태가 "fail"이고 error 객체 포함	생성 자체가 실패함	error.code/error.message를 읽고; 프롬프트를 조정한 뒤 재시도하세요

두 가지 오류 래핑에 주의하세요: 검증 오류는 message를 최상위에 두고, 인증 오류는 error 아래에 중첩됩니다. 범용 미들웨어를 작성한다면 두 경우를 모두 처리해야 합니다.

seedance-2.0-fast의 적합한 사용 사례

1080p 또는 4K 출력이 필요하다면 전체 seedance-2.0을 사용하세요——동일한 엔드포인트, 동일한 흐름, 더 높은 해상도 상한(단, aspect_ratio를 명시적으로 지정해야 함). Seedance 시리즈와 플랫폼의 다른 비디오 모델 비교에 대한 보다 포괄적인 내용은 비디오 모델 비교를 참고하세요. 각 모델의 전체 매개변수 참조는 문서에서 확인할 수 있으며, 모델 페이지에서 현재 기능과 가격 상태를 추적합니다.

자주 묻는 질문

seedance-2.0-fast는 어떤 해상도를 지원하나요? 480p와 720p입니다. 이것이 속도를 위한 대가입니다——전체 seedance-2.0은 동일한 /v1/tasks 흐름에서 최대 1080p와 4k까지 지원합니다.

seedance-2.0-fast로 이미지-비디오를 할 수 있나요? 아니요. 입력 스키마는 prompt, duration, resolution, aspect_ratio만 허용하며, 이미지 필드는 검증 오류로 거부됩니다. hiapi의 이미지-비디오 옵션은 이미지-비디오 워크플로 가이드를 참고하세요.

생성된 비디오는 얼마나 길 수 있나요? duration은 4~15초의 정수를 허용합니다. 범위를 벗어난 값은 작업 생성 전에 검증 실패합니다(거부된 요청은 과금되지 않습니다).

폴링과 콜백 중 무엇을 사용해야 하나요? 스크립트와 낮은 동시성에서는 약 5초마다 폴링하면 충분합니다. 프로덕션 규모에서는 생성 시 callback: {"url": ..., "when": "final"}을 전달하여 hiapi가 종료 상태를 푸시하도록 하세요——수십 번의 요청 대신 한 번의 요청입니다.

다른 모델에서는 유효한 키가 여기서 401 permission_denied를 받는 이유는 무엇인가요? 모델 액세스 권한은 키별로 범위가 지정됩니다. 이 모델에서 401과 permission_denied가 발생하면 키는 존재하지만 seedance-2.0-fast에 대해 활성화되지 않은 것입니다——대시보드에서 해당 키의 모델 권한을 확인하세요.

출력 URL의 유효 기간은 얼마나 되나요? 서명된 URL이며 만료됩니다. 작업 성공 후 즉시 MP4를 다운로드하여 직접 저장하세요; 원본 출력 URL을 장기적으로 존재하는 어떤 곳에도 삽입하지 마세요.