개발자 API

SeeDanceE2.ai 기반으로 구축하세요.

기반이 되는 Seedance 2.0 모델을 바탕으로 상위 제공업체의 기능을 통합해 캡슐화하고, 표준화된 공개 API로 제공합니다.

model: promodel: fastmodel: mini
안정적인 API 계약

`pro`, `fast`, `mini`를 한 번만 통합하면 상위 제공업체의 변경 사항은 동일한 공개 계약 뒤에서 흡수됩니다.

텍스트 및 이미지 워크플로

프롬프트 우선 및 이미지 우선 비디오 생성을 하나의 API 표면에서 실행하고, 상위 제공업체별 차이를 고객에게 노출하지 않습니다.

비동기 작업, 폴링, 웹훅

생성 요청을 제출하고 작업 상태를 폴링하거나, 비디오가 준비되면 깔끔한 SeeDanceE2 응답 형태로 웹훅을 받을 수 있습니다.

공개 계약

비디오 생성을 위한 단일 API 표면

공개 API는 상위 제공업체를 감춥니다. 개발자는 3개의 공개 모델명, 하나의 인증 방식, 하나의 비동기 작업 라이프사이클만 다루면 됩니다.

인증

베어러 API 키

모든 요청에 `Authorization: Bearer sk_seedancee2_live_xxxxx`를 함께 보냅니다.

작업 라이프사이클

제출, 폴링, 웹훅

비동기 생성 작업을 만들고 ID로 폴링하거나 완료 콜백을 받습니다.

사용량과 크레딧

예약 및 차감

응답에는 예약, 차감, 환불 크레딧이 포함되어 과금을 감사할 수 있습니다.

공개 모델 이름

`pro`, `fast`, `mini`만 사용

pro

실사용 품질

고객에게 노출되는 클립과 표준 실무 작업에 사용합니다.

480p, 720p, 1080p
fast

빠른 반복

미리보기 워크플로와 반복적인 프롬프트 실험에 사용합니다.

480p, 720p
mini

저비용 테스트

가벼운 초안과 예산이 중요한 생성에 사용합니다.

480p, 720p
API 질문

자주 묻는 질문

비디오 생성 API 요청은 어떻게 인증하나요?

워크스페이스에서 API 키를 만들고 모든 요청에 베어러 토큰으로 보냅니다: Authorization: Bearer sk_seedancee2_live_xxxxx.

API는 동기식인가요, 비동기식인가요?

생성은 비동기식입니다. 작업을 제출해 작업 ID를 받은 뒤 상태 엔드포인트를 폴링하거나 웹훅을 등록해 비디오 준비 완료를 받습니다.

어떤 모델 이름을 요청할 수 있나요?

공개된 pro, fast, mini 세 가지뿐입니다. 플랫폼이 각 요청을 사용 가능한 최적의 기반 비디오 모델로 라우팅하므로 제공업체가 바뀌어도 연동이 깨지지 않습니다.

API 과금은 어떻게 되나요?

API 사용량은 웹 앱과 동일한 크레딧 잔액에서 차감됩니다. 응답에는 credits_reserved, credits_charged, credits_refunded가 포함되어 모든 호출을 감사할 수 있습니다.

API로 텍스트 투 비디오뿐 아니라 이미지 투 비디오도 가능한가요?

가능합니다. 텍스트 프롬프트를 보내면 텍스트 투 비디오, 참조 이미지 URL을 첨부하면 이미지 투 비디오가 됩니다. 이미지 구도는 유지되고 설명한 움직임만 생성됩니다.

SeeDanceE2 공개 비디오 API

SeeDanceE2는 비디오 생성을 위한 안정적인 공개 API를 제공합니다. 연동 시에는 공개 모델명 pro, fast, mini만 사용해야 하며, 상위 제공업체의 세부 정보는 SeeDanceE2 계약 뒤에 감춰집니다.

베이스 URL

https://api.SeeDanceE2.ai

빠른 시작

  1. SeeDanceE2 팀에서 API 키를 발급받습니다.
  2. 비디오 생성 작업을 만듭니다.
  3. 작업 상태를 폴링하거나, 완료 시 웹훅을 받습니다.

최소 curl 예시:

curl -X POST "https://api.SeeDanceE2.ai/v1/videos/generations" \
  -H "Authorization: Bearer sk_seedancee2_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mini",
    "input": {
      "prompt": "A cinematic drone shot of waves breaking against black volcanic rocks",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    },
    "metadata": {
      "customer_job_id": "job_123"
    }
  }'

최소 JavaScript 예시:

const response = await fetch("https://api.SeeDanceE2.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_seedancee2_live_xxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "mini",
    input: {
      prompt: "A cinematic drone shot of waves breaking against black volcanic rocks",
      duration: 5,
      resolution: "720p",
      aspect_ratio: "16:9",
    },
    metadata: {
      customer_job_id: "job_123",
    },
  }),
});

const result = await response.json();
console.log(result);

최소 Python 예시:

import requests

response = requests.post(
    "https://api.SeeDanceE2.ai/v1/videos/generations",
    headers={
        "Authorization": "Bearer sk_seedancee2_live_xxxxx",
        "Content-Type": "application/json",
    },
    json={
        "model": "mini",
        "input": {
            "prompt": "A cinematic drone shot of waves breaking against black volcanic rocks",
            "duration": 5,
            "resolution": "720p",
            "aspect_ratio": "16:9",
        },
        "metadata": {
            "customer_job_id": "job_123",
        },
    },
    timeout=60,
)

print(response.json())

인증

모든 요청은 베어러 토큰 인증을 사용합니다.

Authorization: Bearer sk_seedancee2_live_xxxxx
Content-Type: application/json

x-api-key로도 키를 보낼 수 있지만, Authorization: Bearer ... 방식을 권장합니다.

API 키와 모델 접근

  • SeeDanceE2 API 키는 SeeDanceE2 팀에서 또는 프로필 화면에서 발급됩니다.
  • 동일한 API 키가 공개 모델 pro, fast, mini 모두에서 동작합니다.
  • Mini, Fast, Pro용으로 별도의 API 키를 만들 필요가 없습니다.
  • 상위 제공업체의 자격 증명은 SeeDanceE2가 관리하며, 고객 요청에 포함할 필요가 없습니다.

이미 사용 가능한 SeeDanceE2 API 키가 있다면 모델 전환은 요청의 model 필드만 바꾸면 됩니다. 예시:

{
  "model": "mini"
}

다음으로 변경:

{
  "model": "fast"
}

또는:

{
  "model": "pro"
}

공개 모델

연동에서 사용해야 하는 공개 모델명은 다음과 같습니다.

모델포지셔닝길이해상도
pro표준 품질의 실사용 생성4-15초480p, 720p, 1080p
fast빠른 반복과 미리보기4-15초480p, 720p
mini저비용 생성4-15초480p, 720p

새로운 연동에는 pro, fast, mini를 사용하세요.

지원 화면 비율:

16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive

크레딧

공개 API 크레딧은 SeeDanceE2 제품과 동일한 차감 규칙을 따릅니다.

계산식:

credits = duration_seconds * per_second_rate * number_of_outputs

참조 이미지, 참조 비디오, 참조 오디오에는 현재 고객 대상 추가 과금이 없습니다. 작업별 정확한 값은 API 응답의 예약 크레딧과 차감 크레딧을 기준으로 합니다.

현재 초당 단가는 SeeDanceE2 제품의 과금 규칙과 일치합니다:

모델480p720p1080p
pro10 크레딧/초20 크레딧/초50 크레딧/초
fast8 크레딧/초16 크레딧/초지원 안 함
mini5 크레딧/초10 크레딧/초지원 안 함

예시:

시나리오크레딧
mini, 5초, 720p50
pro, 4초, 480p40
fast, 10초, 720p160
pro, 5초, 720p, 참조 이미지 2장100

작업이 실패해 환불 대상이 되면, 반환되는 상태 페이로드에 환불 크레딧이 표시됩니다.

작업 라이프사이클

공개 API가 반환하는 작업 상태:

상태의미
pending접수되어 시작 대기 중
processing실행 중
completed정상 완료
failed사용 가능한 출력 없이 종료

비디오 작업 생성

POST /v1/videos/generations

최상위 요청 필드:

필드타입필수설명
modelstring예공개 모델명: pro, fast, mini
inputobject예생성 파라미터
callback_urlstring아니오완료 또는 실패를 받을 공개 웹훅 URL
metadataobject아니오고객이 정의하는 메타데이터로, 폴링과 웹훅 응답에 그대로 반환됩니다

입력 필드:

필드타입필수설명
promptstring예텍스트 프롬프트
generation_typestring아니오omni_reference 또는 first_and_last_frames, 기본값 omni_reference
image_urlsstring[]아니오참조 이미지 URL
video_urlstring아니오참조 비디오 URL 1개
video_urlsstring[]아니오참조 비디오 URL. video_url과 함께 보내지 마세요
audio_urlsstring[]아니오참조 오디오 URL
start_image_urlstring아니오first_and_last_frames용 시작 프레임 이미지
end_image_urlstring아니오first_and_last_frames용 종료 프레임 이미지
durationinteger아니오출력 길이(초), 4-15, 기본값 5
resolutionstring아니오480p, 720p, 1080p. 사용 가능한 해상도는 선택한 모델에 따라 다릅니다
aspect_ratiostring아니오16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive
generate_audioboolean아니오지원되는 경우 동기화된 오디오를 생성합니다
watermarkboolean아니오워터마크가 포함된 출력을 요청합니다
seedinteger아니오재현성을 위한 시드 값
return_last_frameboolean아니오출력 페이로드에 마지막 프레임 이미지를 포함합니다

전체 예시:

curl -X POST "https://api.SeeDanceE2.ai/v1/videos/generations" \
  -H "Authorization: Bearer sk_seedancee2_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pro",
    "callback_url": "https://example.com/webhooks/seedancee2",
    "input": {
      "prompt": "A cinematic tracking shot through a rain-soaked neon market at night",
      "image_urls": [
        "https://example-cdn.com/reference-1.png",
        "https://example-cdn.com/reference-2.png"
      ],
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true,
      "return_last_frame": true
    },
    "metadata": {
      "customer_job_id": "job_123",
      "campaign": "launch_week"
    }
  }'

성공 응답:

{
  "data": {
    "id": "vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
    "status": "pending",
    "model": "pro",
    "credits_reserved": 100,
    "created_at": "2026-06-29T10:00:00.000Z"
  }
}

비디오 작업 조회

GET /v1/videos/generations/{id}

폴링 예시:

const response = await fetch(
  "https://api.SeeDanceE2.ai/v1/videos/generations/vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
  {
    headers: {
      Authorization: "Bearer sk_seedancee2_live_xxxxx",
    },
  }
);

const result = await response.json();
console.log(result);

처리 중 응답:

{
  "data": {
    "id": "vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
    "status": "processing",
    "model": "pro",
    "created_at": "2026-06-29T10:00:00.000Z",
    "metadata": {
      "customer_job_id": "job_123",
      "campaign": "launch_week"
    }
  }
}

완료 응답:

{
  "data": {
    "id": "vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
    "status": "completed",
    "model": "pro",
    "created_at": "2026-06-29T10:00:00.000Z",
    "completed_at": "2026-06-29T10:06:20.000Z",
    "credits_charged": 100,
    "output": {
      "video_url": "https://media.SeeDanceE2.ai/videos/2026/06/29/vid_01jz8b7q4x8k2p9w3m5c6n7r8s.mp4",
      "thumbnail_url": "https://media.SeeDanceE2.ai/video-posters/2026/06/29/vid_01jz8b7q4x8k2p9w3m5c6n7r8s.jpg",
      "last_frame_url": "https://media.SeeDanceE2.ai/video-posters/2026/06/29/vid_01jz8b7q4x8k2p9w3m5c6n7r8s.jpg"
    },
    "metadata": {
      "customer_job_id": "job_123",
      "campaign": "launch_week"
    }
  }
}

실패 응답:

{
  "data": {
    "id": "vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
    "status": "failed",
    "model": "pro",
    "created_at": "2026-06-29T10:00:00.000Z",
    "credits_charged": 0,
    "credits_refunded": 100,
    "error": {
      "code": "generation_failed",
      "message": "The video could not be generated. Please try again with a different prompt.",
      "type": "generation_error"
    },
    "metadata": {
      "customer_job_id": "job_123",
      "campaign": "launch_week"
    }
  }
}

비디오 작업 목록

GET /v1/videos/generations

지원하는 쿼리 파라미터:

필드타입설명
statusstringpending, processing, completed, failed로 필터링합니다
limitinteger최대 결과 수. 기본값 20, 최대 100

예시:

curl "https://api.SeeDanceE2.ai/v1/videos/generations?status=completed&limit=10" \
  -H "Authorization: Bearer sk_seedancee2_live_xxxxx"

모델 목록

GET /v1/models

응답 예시:

{
  "data": [
    {
      "id": "pro",
      "status": "active",
      "resolutions": ["480p", "720p", "1080p"],
      "duration": {
        "min": 4,
        "max": 15
      }
    }
  ]
}

사용량 요약

GET /v1/usage

지원하는 쿼리 파라미터:

필드타입설명
startstring선택 사항. ISO 8601 형식의 시작 일시 필터
endstring선택 사항. ISO 8601 형식의 종료 일시 필터
limitinteger반환할 일별 타임라인 최대 행 수. 기본값 30, 최대 365

예시:

curl "https://api.SeeDanceE2.ai/v1/usage?start=2026-07-01T00:00:00.000Z&end=2026-07-31T23:59:59.999Z&limit=7" \
  -H "Authorization: Bearer sk_seedancee2_live_xxxxx"

응답 예시:

{
  "data": {
    "range": {
      "start": "2026-07-01T00:00:00.000Z",
      "end": "2026-07-31T23:59:59.999Z"
    },
    "summary": {
      "total_jobs": 12,
      "pending_jobs": 1,
      "processing_jobs": 2,
      "completed_jobs": 8,
      "failed_jobs": 1,
      "credits_charged": 280,
      "credits_refunded": 40,
      "net_credits": 240
    },
    "by_model": [
      {
        "model": "mini",
        "total_jobs": 7,
        "pending_jobs": 0,
        "processing_jobs": 1,
        "completed_jobs": 5,
        "failed_jobs": 1,
        "credits_charged": 120,
        "credits_refunded": 20,
        "net_credits": 100
      },
      {
        "model": "pro",
        "total_jobs": 5,
        "pending_jobs": 1,
        "processing_jobs": 1,
        "completed_jobs": 3,
        "failed_jobs": 0,
        "credits_charged": 160,
        "credits_refunded": 20,
        "net_credits": 140
      }
    ],
    "timeline": [
      {
        "date": "2026-07-01",
        "total_jobs": 4,
        "pending_jobs": 0,
        "processing_jobs": 1,
        "completed_jobs": 3,
        "failed_jobs": 0,
        "credits_charged": 100,
        "credits_refunded": 0,
        "net_credits": 100
      }
    ]
  }
}

웹훅

callback_url을 지정하면 작업이 completed 또는 failed에 도달할 때 SeeDanceE2가 POST 요청을 보냅니다.

확인해야 할 권장 헤더:

X-Seedancee2-Event: video.generation.completed
X-Seedancee2-Signature: t=1770000000,v1=...

계정에서 웹훅 서명이 활성화되어 있으면 본문은 다음과 같이 서명됩니다:

payload_to_sign = "{timestamp}.{raw_json_body}"
signature = hex(hmac_sha256(webhook_secret, payload_to_sign))

완료 웹훅 페이로드:

{
  "data": {
    "id": "vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
    "status": "completed",
    "model": "pro",
    "created_at": "2026-06-29T10:00:00.000Z",
    "completed_at": "2026-06-29T10:06:20.000Z",
    "credits_charged": 100,
    "output": {
      "video_url": "https://media.SeeDanceE2.ai/videos/2026/06/29/vid_01jz8b7q4x8k2p9w3m5c6n7r8s.mp4",
      "thumbnail_url": "https://media.SeeDanceE2.ai/video-posters/2026/06/29/vid_01jz8b7q4x8k2p9w3m5c6n7r8s.jpg"
    },
    "metadata": {
      "customer_job_id": "job_123",
      "campaign": "launch_week"
    }
  }
}

실패 웹훅 페이로드:

{
  "data": {
    "id": "vid_01jz8b7q4x8k2p9w3m5c6n7r8s",
    "status": "failed",
    "model": "pro",
    "created_at": "2026-06-29T10:00:00.000Z",
    "credits_charged": 0,
    "credits_refunded": 100,
    "error": {
      "code": "generation_failed",
      "message": "The video could not be generated. Please try again with a different prompt.",
      "type": "generation_error"
    },
    "metadata": {
      "customer_job_id": "job_123",
      "campaign": "launch_week"
    }
  }
}

입력 가이드라인

이미지:

요구 사항값
형식JPEG, PNG, WebP, BMP, TIFF, GIF
개수참조 이미지 최대 9장
first_and_last_frames정확히 2장

비디오:

요구 사항값
video_url1개
video_urls최대 3개

오디오:

요구 사항값
audio_urls최대 3개

오류

오류 형식:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

현재 공개 오류 코드:

HTTP 상태코드유형설명
400invalid_requestinvalid_request_error파라미터 누락 또는 잘못된 값
401invalid_api_keyauthentication_errorAPI 키가 없거나, 유효하지 않거나, 비활성화됨
402insufficient_creditsbilling_error크레딧 잔액 부족
404model_not_foundinvalid_request_error모델이 없거나 비활성 상태
404task_not_foundinvalid_request_error작업 ID가 존재하지 않음
500internal_errorapi_error예기치 않은 서버 오류

연동 시 유의사항

  • pro, fast, mini 등 공개 모델명만 사용하세요.
  • 내부 제공업체 이름, 내부 작업 ID, 내부 미디어 호스트에 의존하는 로직을 만들지 마세요.
  • metadata를 직접 저장해 콜백과 폴링 결과를 사내 업무 기록과 연결할 수 있게 하세요.
  • 운영 환경에서는 완료 알림에 웹훅을 사용하고, 폴링은 대체 수단으로 남겨 두세요.