Seedance 2.5 API 사용법：빠른 가이드

API 키에서 완성된 MP4까지 네 단계로 갈 수 있습니다: 인증된 POST 요청을 보내고, request_id를 저장하고, 결과 엔드포인트를 10초에서 20초마다 폴링한 다음, 링크가 만료되기 전에 영상을 다운로드하세요. 링크는 흔히 24시간 이내에 만료됩니다.

짧은 버전을 원한다면, 제가 염두에 둘 것은 이렇습니다:

• 올바른 엔드포인트 사용
  • 텍스트 프롬프트에는 seedance-2.5-text-to-video
  • 공개 이미지 URL을 애니메이션화할 때는 seedance-2.5-image-to-video
• 올바른 헤더 전송
  • Authorization: Bearer <API_KEY>
  • Content-Type: application/json
• 주요 출력 설정 선택
  • resolution: 480p에서 4K
  • aspect_ratio: 16:9나 9:16 같은 것
  • duration: 최대 16초
  • generate_audio: 사운드와 음성 대사를 위해 true
• 재제출 대신 폴링
  • predictions/{request_id}/result 확인
  • queued, running, succeeded, 또는 failed 주시
• 비용 제어
  • 480p나 720p에서 시작
  • 동일한 seed 유지
  • 샷이 제대로 보일 때만 1080p나 4K로 재실행

또한 가장 흔한 실패 지점을 주시하겠습니다: 잘못된 인증 헤더로 인한 401, 크레딧 없음으로 인한 402, 활성 작업이 너무 많아서 발생하는 429, 그리고 잘못된 JSON이나 누락된 필드로 인한 400입니다. APIMart에서는 작업이 시작될 때 크레딧이 예약되고 완료될 때만 청구되며, 실패한 작업은 환불됩니다.

모델 중에서 고른다면, Seedance 2.5는 이 라인업에서 최상위 옵션입니다: 최대 16초, 최대 3,840 × 2,160, 그리고 최대 50개 레퍼런스 입력. Seedance 2.0은 중간에 위치하고, Seedance 2 Mini는 저비용 초안에 더 좋습니다.

결론: 유효한 POST 요청을 보내고 하나의 ID를 저장할 수 있다면, 전체 워크플로를 실행할 수 있습니다. 나머지는 프롬프트 튜닝, 인내심 있는 폴링, 그리고 URL이 시간 초과되기 전에 파일을 다운로드하는 것입니다. 후처리를 위해서는 AI Canvas를 사용해 생성된 클립을 업스케일하거나 편집할 수 있습니다.

1단계: APIMart 접근 설정 및 요청 인증

모든 Seedance 2.5 요청에는 유효한 API 키와 올바른 헤더가 필요합니다. 거기서 시작하세요. 그것이 갖춰지면 영상 생성 페이로드와 작업 추적으로 넘어갈 수 있습니다.

API 키를 안전하게 생성하고 저장하기

계정 대시보드의 Settings 또는 API Keys에서 키를 생성하세요. 그런 다음 소스 관리가 아니라 .env 파일이나 환경 변수에 저장하세요 ^[6][8].

export APIMART_API_KEY="sk_live_xxxxxx"

키를 분실하면 폐기하고 새로 만드세요 ^[3]. 통합 테스트에는 프로덕션 사용량을 건드리지 않도록 별도의 sk_test_ 키를 사용하세요 ^[3].

다음으로, 모든 요청에 Authorization 헤더로 그 키를 포함하세요.

Authorization 헤더를 올바르게 추가하기

https://muapi.ai/api/v1/로 다음 헤더와 함께 요청을 보내세요:

• Authorization: Bearer sk_live_xxxxxx
• Content-Type: application/json

작은 형식 실수 하나가 요청을 망칠 수 있습니다. 가장 흔한 것은 Bearer 접두사를 빼먹거나, 키 앞의 공백을 누락하는 것입니다 ^[3][7]. 그러면 보통 401 Unauthorized 응답으로 이어집니다. Content-Type: application/json을 빼먹어도 요청이 실패할 수 있습니다 ^[3][7].

인증이 설정되면 영상 요청 페이로드로 넘어갈 수 있습니다.

2단계: Seedance 2.5 영상 생성 요청 만들기

API 키가 설정되면, 다음 단계는 유효한 요청 본문을 만드는 것입니다. 모든 Seedance 2.5 작업은 무엇으로 시작하는지에 따라 두 엔드포인트 중 하나로 POST 요청을 보내면서 시작됩니다. 프롬프트만으로 생성할 때는 https://muapi.ai/api/v1/seedance-2.5-text-to-video를, 소스 이미지를 애니메이션화할 때는 https://muapi.ai/api/v1/seedance-2.5-image-to-video를 사용하세요 ^[1].

올바른 입력 모드와 파라미터 선택하기

입력 모드가 페이로드 형태를 결정합니다. 텍스트-비디오는 prompt만 필요합니다. 이미지-비디오는 10 MB 미만의 공개적으로 접근 가능한 JPG, PNG, 또는 WEBP 파일을 가리키는 image_url도 필요합니다 ^[1].

거기서부터 몇 가지 주요 필드로 출력을 제어합니다:

• resolution: 480p, 720p, 1080p, 또는 4K
• aspect_ratio: 16:9, 9:16, 1:1, 4:3, 3:4, 또는 21:9
• duration: Muapi에서 최대 16초
• generate_audio: true로 설정하면 동기화된 앰비언트 사운드, 효과, 대사를 켜는 불리언 ^[1]

똑똑한 작업 방식은 고정된 seed와 함께 480p에서 시작하는 것입니다. 모션, 페이싱, 프레이밍이 제대로 보이면, 동일한 seed를 1080p나 4K에서 다시 실행해 최종 버전을 만드세요.

프롬프트의 경우 이 흐름을 사용하세요: Subject → Action → Camera → Setting → Mood ^[4]. 모션, 카메라 방향, 무드를 prompt 자체 안에 두고, 변형을 테스트하는 동안 seed는 변경하지 않은 채로 두세요. 립싱크가 필요하면, 프롬프트 문자열 바로 안에 말하는 대사를 큰따옴표로 넣으세요. 예를 들면: she turns and says "We launch at dawn." 그 경우 generate_audio가 true로 설정되어 있는지 확인하세요 ^[1].

페이로드가 괜찮아 보이면, 작업을 제출하고 반환된 request ID를 저장하세요. 폴링에 필요합니다.

cURL, Postman, Python, JavaScript의 샘플 요청

아래는 네 가지 흔한 도구로 보여주는 동일한 텍스트-비디오 페이로드입니다.

cURL

curl -X POST https://muapi.ai/api/v1/seedance-2.5-text-to-video \
  -H "Authorization: Bearer $APIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": true,
    "seed": 42
  }'

Postman - 새 POST 요청을 만들고, 엔드포인트 URL을 붙여넣고, Headers 탭에 Authorization: Bearer <your_key>와 Content-Type: application/json을 추가한 다음, 위의 JSON을 Body → raw → JSON에 붙여넣으세요. Send를 클릭하고 응답에서 request_id를 저장하세요.

Python

import os, requests

payload = {
    "prompt": "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": True,
    "seed": 42
}

response = requests.post(
    "https://muapi.ai/api/v1/seedance-2.5-text-to-video",
    headers={
        "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
        "Content-Type": "application/json"
    },
    json=payload
)

print(response.json())  # save request_id here

JavaScript (fetch)

const response = await fetch("https://muapi.ai/api/v1/seedance-2.5-text-to-video", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.APIMART_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A barista steams milk, then pours a latte art heart. Close-up, warm café lighting, cinematic.",
    aspect_ratio: "16:9",
    resolution: "1080p",
    duration: 8,
    generate_audio: true,
    seed: 42
  })
});

const data = await response.json();
console.log(data.request_id); // use this to poll for results

몇 가지 실수가 당신을 빠르게 넘어뜨릴 수 있습니다. 공개적으로 접근 불가능한 image_url을 보내지 마세요. 동일한 프롬프트에서 서로 충돌하는 카메라 방향을 쌓지 마세요. 그리고 이미지-비디오 모드에서는, 소스 이미지가 이미 피사체를 정의하고 있다면 피사체를 다시 묘사하지 마세요 ^[1].

제출 후에는 MP4 URL이 준비될 때까지 작업 상태를 폴링하세요.

APIMart의 영상 모델 라인업에서 Seedance 2.5를 언제 쓸 것인가

이 빠른 비교는 프롬프트를 손보거나 해상도를 올리기 전에 올바른 모델을 고르는 데 도움을 줍니다. Seedance 2.5는 네이티브 4K, 최대 50개 레퍼런스 입력, 그리고 더 긴 클립 지원을 제공합니다. Seedance 2 Mini는 가벼운 초안에 더 좋고, Seedance 2.0은 범용 옵션으로 중간에 위치합니다 ^[1][9][4].

프로젝트가 제품 출시 영상, 브랜드 시네마틱 시퀀스, 또는 방송용으로 향하는 것처럼 최종 결과물이라면, Seedance 2.5가 더 나은 선택입니다. 고품질 음성 포함 AI 영상 생성이 필요한 프로젝트의 경우, Google의 Veo 3.1이 또 다른 강력한 경쟁자입니다. 아직 아이디어를 테스트하는 중이라면, Mini로 시작해 더 낮은 비용으로 모션을 확인하고 프레이밍을 고정한 다음, 최종 렌더를 위해 2.5로 올라가세요.

3단계: 작업 제출, 상태 추적, 응답 읽기

POST 요청을 보내면 API가 request_id를 반환합니다. 저장하세요. 생성이 비동기로 실행되기 때문에 나중에 작업을 확인하는 데 그 ID를 사용합니다.

생성부터 완료까지 비동기 작업 처리하기

작업을 제출한 후 다음 단계는 단순합니다: 최종 영상이 준비될 때까지 폴링하세요.

https://muapi.ai/api/v1/predictions/{request_id}/result로 GET 요청을 보내세요. 첫 폴링 전에 제출 후 약 10초를 기다린 다음, 10–20초마다 다시 확인하세요. 5초보다 더 자주 폴링하면 속도 제한에 걸릴 수 있습니다 ^[1][3].

각 응답에는 status 필드가 포함됩니다. 그 필드는 무슨 일이 일어나고 있는지, 그리고 다음에 무엇을 해야 하는지 알려줍니다:

작업이 succeeded에 도달하면, 만료되기 전에 출력 URL을 확보하세요.

출력 필드 읽기 및 결과 저장하기

상태가 succeeded로 바뀌면, 출력 페이로드를 읽고 결과를 저장하세요.

성공 응답에는 video_url이 포함됩니다. 요청했다면 last_frame_url도 포함될 수 있습니다. video_url, 선택적 last_frame_url, 그리고 seed, duration, resolution, aspect_ratio, usage 같은 메타데이터를 저장하세요. 그 데이터는 청구와 나중에 동일한 실행을 재현하는 데 중요합니다 ^[11][13].

출력 URL은 흔히 24시간 이내에 만료되므로, 파일을 즉시 자신의 저장소로 다운로드하세요 ^[11][12][13]. 작업이 실패하면 error.code와 error.message를 기록하세요. 그리고 실패가 안전 검사와 연결되어 있다면, 자동으로 재시도하지 마세요 ^[2][11][12].

4단계: 오류 해결, 비용 제어, 마무리

인증, 검증, 속도 제한 오류 수정하기

작업을 제출하고 결과를 폴링한 후, 몇 가지 간단한 확인으로 프로덕션 실행이 탈선하는 것을 막을 수 있습니다. 대부분의 Seedance 실패는 동일한 몇 가지 방식으로 나타나는 경향이 있습니다.

레퍼런스 에셋의 경우, URL이 공개인지, 파일이 JPG, PNG, 또는 WEBP인지, 그리고 명시된 크기 제한 이하인지 확인하세요 ^[12][4].

비용 절감 및 신뢰성 향상

오류 처리가 설정되면, 다음 단계는 단순합니다: 저렴하게 테스트한 다음, 크게 렌더링하세요.

프롬프트를 480p나 720p에서 시작하세요. 그러면 프레이밍, 모션, 그리고 프롬프트가 원하는 대로 작동하는지 저비용으로 확인할 수 있습니다. 샷이 제대로 보이면, 동일한 seed 값을 4K에서 다시 실행해 최종 출력을 만드세요 ^[1][4].

클립 길이도 중요합니다. 더 짧은 영상은 비용이 덜 드니, 여전히 목적을 달성하는 최소한으로 길이를 유지하세요 ^[1][10].

팀이 돈을 태우는 은근한 방식도 있습니다: 네트워크 시간 초과 후 중복 제출입니다. 한 가지 깔끔한 수정은 각 POST 요청 전에 프롬프트, 모델 ID, 미디어 URL을 해시하는 것입니다. 그 해시가 이미 작업 ID에 매핑되어 있다면, 새 제출을 아예 건너뛰세요 ^[11]. 그리고 작업이 succeeded에 도달하면, 나중에 작업 기록에 의존하지 않도록 완성된 파일을 영구 저장소에 저장하세요 ^[12][11].

결론: API 문서에서 작동하는 영상 생성까지

인증, 페이로드, 폴링, 오류 처리가 갖춰지면, 이제 APIMart에서 완전한 Seedance 2.5 워크플로를 갖추게 됩니다.

FAQ

::: faq

Seedance 2.5가 영상 하나를 완성하는 데 얼마나 걸리나요?

Seedance 2.5는 최대 30초 길이의 연속된 영상 클립 하나를 생성할 수 있습니다. 다만 문서에는 정확한 완료 시간이 나와 있지 않습니다.

API는 비동기로 실행됩니다. 작업을 제출하고, 작업 ID를 받은 다음, 상태 엔드포인트를 폴링하거나 웹훅을 기다려 완성된 영상을 받습니다.

처리 시간은 해상도와 장면 복잡도 같은 요소에 따라 달라질 수 있습니다. :::

::: faq

다운로드하기 전에 영상 URL이 만료되면 어떻게 해야 하나요?

다운로드하기 전에 영상 URL이 만료되면, 그 링크에서 파일을 받을 수 없습니다. Seedance는 이 임시 URL을 24시간 동안 활성 상태로 유지합니다.

안전한 방법은 단순합니다: 작업이 완료로 표시되는 즉시 영상을 자신의 안전한 오브젝트 스토리지로 복사하세요. API가 비동기로 실행되고 출력을 영원히 보관하지 않기 때문에, 앱은 영상을 즉시 가져와 장기 저장소로 옮겨야 합니다. :::

::: faq

실패한 요청을 재시도할 때 중복 청구를 어떻게 피할 수 있나요?

HTTP 클라이언트만이 아니라 자신의 영구 작업 기록에 연결된 멱등 요청 처리를 사용하세요.

무언가를 제출하기 전에, 프롬프트, 모델 ID, 에셋 ID, 사용자 식별자 같은 입력으로부터 결정론적 요청 해시를 만드세요. 그런 다음 그 해시를 submitting 상태로 자신의 데이터베이스에 저장하세요.

동일한 해시가 다시 나타나면, 새 작업을 생성하는 대신 기존 작업을 반환하세요.

제공자 작업 ID를 저장했다면, 요청을 다시 제출하지 마세요. 그냥 그 작업 ID로 폴링을 재개하세요. :::