ClipMixAI 개발자 API 출시: 영상 번역, AI 음악, 페이스스왑을 단일 REST API로

오늘부터 ClipMixAI 웹 앱을 구동하는 핵심 엔진을 모든 개발자에게 공개합니다. api.clipmixai.com/api/v1의 새로운 개발자 API는 영상 번역·메모리 영상·페이스스왑 및 아바타·AI 음악, 총 네 가지 서비스를 단일 Bearer 토큰 REST 방식으로 제공합니다. 동일한 모델, 동일한 품질, 동일한 크레딧. 구독 불필요, 최소 사용량 없음.

설명을 건너뛰고 싶다면: /api에서 서비스 소개를, /api/docs에서 레퍼런스 문서를, /dashboard/api-keys에서 키를 생성하세요.

개발 배경

지난 1년간 유료 사용자들이 반복하는 패턴을 계속 목격했습니다. 대시보드를 열고, 사진 30장을 업로드하고, 생성 버튼을 누르고, 음악이 완성되길 기다린 뒤, 결과물을 수동으로 별도 편집 도구에 옮기는 과정이었습니다. 크리에이터 콘텐츠를 10개 언어로 번역하는 창업자들, 주당 브랜드 영상 100편을 제작하는 대행사들, 프로토타입 임시 음악을 만드는 인디 게임 스튜디오들 — 이들 모두가 결국 같은 질문을 했습니다: "API 없나요?"

이제 있습니다. 그 모든 워크플로를 지탱했던 네 가지 서비스를 코드에서 직접 호출할 수 있습니다. 대시보드 없이, 각 공급업체의 세부 사항을 익힐 필요 없이, 이미 웹 앱에서 익숙한 크레딧당 요금 그대로. 한 시간짜리 수작업이 백그라운드 CRON 작업으로 돌아간다면, 그게 바로 이 API의 가치입니다.

빠른 시작

대시보드에서 키를 생성한 후:

curl -X POST https://api.clipmixai.com/api/v1/music \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: my-fresh-key-1" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt":   "Uplifting synthwave with female vocals",
    "lyrics":   "[verse]\nRunning through neon lights...",
    "duration_seconds": 60
  }'

job-id와 status: "processing"이 즉시 반환됩니다. GET /v1/music/{id}를 폴링해서 상태가 completed로 바뀔 때까지 기다리거나 — 더 좋은 방법으로 — 키 생성 시 웹훅을 등록하면 완료된 결과를 엔드포인트로 직접 전달받을 수 있습니다. 전달 데이터는 HMAC-SHA256으로 서명되어 실제로 ClipMixAI에서 보낸 것인지 검증할 수 있습니다.

개발자들이 요청했지만 이전에는 제공하지 않았던 세 가지

1. 샌드박스 키

모든 API 키에는 모드가 있습니다. sk_live_는 크레딧을 차감하고 실제 공급업체를 호출하며, sk_test_는 크레딧을 차감하지 않고 공급업체도 호출하지 않은 채 본문에 test: true가 포함된 가상의 completed 작업을 반환합니다. CI 환경에서 크레딧 소모 없이 연동을 검증하고, 실제 결과가 필요할 때 라이브 키로 전환하세요.

샌드박스 키는 무료 티어 계정을 포함해 모든 사용자에게 무료입니다. 라이브 키 사용의 유일한 조건은 사전 크레딧 구매 이력으로, 웹 앱과 동일한 결제 신호로 API 접근을 관리합니다.

2. 모든 POST 요청의 멱등성 키

네트워크 재시도는 결제 연동 API의 고질적인 문제입니다. Stripe의 방식을 차용했습니다. 모든 생성 요청에 Idempotency-Key: <문자열>을 전달하면 서버가 24시간 동안 응답을 캐시합니다. 같은 키와 같은 본문으로 재시도하면 원래 응답이 그대로 반환되어 이중 과금이 발생하지 않습니다. 같은 키지만 다른 본문으로 재시도하면 422 idempotency_key_reuse를 반환하여 잘못된 작업이 조용히 생성되는 대신 버그를 바로 발견할 수 있습니다.

두 공식 SDK 모두 단일 키워드 인수로 이를 지원합니다:

# Python
c.music.create(prompt=..., lyrics=..., idempotency_key="order-42")

// JS
await c.music.create({ prompt, lyrics, idempotencyKey: "order-42" });

3. 테스트 발송 버튼이 있는 웹훅

키에 콜백 URL을 설정하면 작업 완료 시 job.completed / job.failed 이벤트를 POST로 전달합니다. 각 전달에는 X-ClipMix-Signature: sha256=<hex> 헤더에 HMAC 서명이 포함되며 SDK 헬퍼 함수 하나로 검증할 수 있습니다. 전달 실패 시 지수 백오프 방식으로 재시도합니다(0초 → 30초 → 5분 → 1시간, 총 4회).

대시보드의 테스트 발송 버튼을 누르면 실제 작업 없이 가상의 webhook.test 이벤트를 전송해 엔드포인트의 서명 파싱을 검증할 수 있습니다. 같은 패널에 키별 최근 100건의 전달 로그가 표시되어 문제 발생 시 어디서 실패했는지 바로 확인할 수 있습니다.

이미 목격하고 있는 세 가지 활용 사례

크리에이터를 위한 대량 영상 번역

영상 하나를 업로드하면 10개 언어로 더빙된 10개 버전을 받을 수 있으며, 화자의 톤을 그대로 살리는 음성 클로닝도 선택 가능합니다. 한 YouTube 크리에이터는 매주 팟캐스트를 자동으로 9개 언어로 번역하고 있습니다. 기존 게시 훅이 API 호출을 트리거하고, 웹훅이 더빙된 파일을 CMS에 바로 저장합니다.

고객별 맞춤 브랜드 영상

사진→영상 메모리 기능 덕분에 이커머스 스토어는 상품 사진 하나로 해당 상품에 맞게 개인화된 짧은 시네마틱 광고를 생성할 수 있습니다. family-videos 엔드포인트는 소비자 UI용으로 개발한 네 가지 모드(Moment, Story, Album, Chronicle)를 제공하며, 에이전시들이 화이트레이블 도구의 엔진으로 활용하고 있습니다.

게임 오디오 프로토타이핑

인디 스튜디오들이 내부 에셋 파이프라인에서 /v1/music 엔드포인트를 호출하고 있습니다. 게임 디자이너가 분위기와 임시 가사 몇 줄을 입력하면 10분 뒤 60초 트랙이 프로젝트 오디오 폴더에 저장됩니다. 사운드 디자이너를 기다릴 필요 없이 순식간에 임시 음악을 반복 수정할 수 있습니다.

버전 관리 및 약속

v1은 안정 버전입니다. /api/v1/ 내에서 호환성을 깨는 변경은 도입하지 않습니다 — 새 필드와 새 엔드포인트는 추가만 가능하고 기존 구조는 그대로 유지됩니다. 불가피한 변경이 있을 경우(드물게) 공지 전환 기간을 두고 /api/v2/로 출시합니다. changelog가 공식 기록입니다.

운영 상태는 /api/status에서 실시간으로 확인할 수 있습니다 — 최근 5분간의 실제 트래픽을 기반으로 서비스별 상태를 보여주며, 60초마다 업데이트됩니다. 온콜 담당자와 동일한 화면입니다.

요금

웹 앱과 동일한 지갑을 사용합니다. $1 = 100 크레딧, 충전 시 기존 볼륨 보너스 적용. 60초 음악은 60 크레딧($0.60). 30초 토킹헤드 아바타(밸런스드 티어)는 450 크레딧. 1분 영상의 프리미엄 티어 번역은 약 190 크레딧. 샌드박스 키는 무료입니다.

대량 할인율과 우선 처리 워커가 포함된 티어별 API 플랜(Pro / Business / Enterprise)이 출시 예정입니다. 지금 당장 필요하시면 /contact?topic=api-tiers에 이메일을 남겨주세요. 출시 시 안내해 드리겠습니다.

시작하기

• /api — 5분 소개
• /api/docs — 레퍼런스 문서 (인증, 멱등성, 웹훅, 샌드박스, 오류, SDK)
• /api/status — 실시간 서비스 상태
• /api/changelog — 릴리즈 내역 및 로드맵
• /dashboard/api-keys — 첫 번째 키 생성

버그 리포트 및 기능 요청: GitHub Issues. 기타 문의: support@clipmixai.com.