본문으로 건너뛰기

ByteDance Lip Sync는 ByteDance 영상 번역 도구에 포함된 영상 립싱크 서비스입니다. 정면의 단일 화자 영상에는 Lite, 복잡한 단일 화자 장면에는 Basic을 사용합니다. 음성 타이밍을 따르는 25fps MP4를 반환합니다.

최저가 $0.048/초

플레이그라운드

요청 보내기

빠른 시작

예시는 선택한 엔드포인트의 공개 파라미터 정의를 사용합니다. API 키와 예시 미디어를 바꾼 뒤 서버에서 요청하세요.

SDK 및 연동
POSThttps://api.spicyapi.ai/api/v1/jobs/createTask

API 인증

API 키는 서버 환경 변수 SPICY_API_KEY에 보관하세요. Bearer 인증을 사용하고 JSON 요청에는 Content-Type: application/json을 지정하세요.

Authorization: Bearer $SPICY_API_KEY
샘플 결과이 예시 쓰기
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -d '{
  "model": "bytedance/lip-sync/lip-sync",
  "input": {
    "audio_url": "https://example.com/reference.mp3",
    "generation_mode": "lite",
    "video_url": "https://example.com/reference.mp4"
  }
}'

# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

이 모델의 입력 스키마에서 뽑아낸 예시입니다. API도 모든 요청을 같은 스키마로 검증합니다.

입력 파라미터

이 필드들은 요청 본문의 input 객체 안에 넣습니다. 이름과 타입은 API와 동일합니다. 기본값이 적혀 있지 않은 필드는 임의로 가정하지 마세요.

audio_urlstring필수요금에 영향

두 모드에서 필수이며 기본값은 없습니다. MP3, WAV, AAC, M4A, OGG 형식의 깨끗한 사람 음성을 최대 10MB까지 받습니다. 길이는 1초를 초과하고 Lite는 240초, Basic은 210초 이내여야 합니다. 이 길이를 올림해 과금 초 수를 계산하며 목표 출력 길이도 이 녹음에 맞춥니다.

기본값
지정되지 않음
제약 조건
minLength:1
format:"uri"
contentMediaType:["audio/mpeg","audio/wav"]
video_urlstring필수

Lite와 Basic에서 모두 필수이며 기본값은 없습니다. MOV, MP4, MKV 형식의 360p–1080p, 24–60fps, 1–30Mbps 영상을 제공합니다. H.264를 권장합니다. 1080p 초과 영상은 1080p로 축소하고 360p 미만 입력은 거절합니다. 청구할 초 수는 해당 영상의 재생 시간으로 계산하지 않습니다.

기본값
지정되지 않음
제약 조건
minLength:1
format:"uri"
contentMediaType:["video/mp4","video/webm","video/quicktime"]
video_start_secondsnumber선택

Lite에서 선택하는 원본 위치 숫자이며 기본값은 0초입니다. 제공한 영상 안에서 시작 지점을 고르고 Basic에서는 이 필드를 제외합니다. 시작 위치를 뒤로 옮기면 사용할 화면이 바뀌지만 과금 초 수는 여전히 업로드한 전체 녹음으로 정합니다.

기본값
0
제약 조건
minimum:0
maximum:3600
loop_reverseboolean선택

Lite의 선택적 불리언이며 기본값은 false입니다. loop_video를 활성화한 경우에 적용할 수 있습니다. 반복 영상의 정방향과 역방향 재생을 번갈아 적용합니다. Basic에서는 제외합니다. 방향을 바꿔도 과금 오디오 길이는 달라지지 않습니다.

기본값
false
loop_videoboolean선택

Lite의 선택적 불리언이며 기본값은 true입니다. 음성이 영상보다 길면 촬영본을 반복해 채웁니다. Lite 요청의 설정을 가져온 경우에도 Basic에서는 이 필드를 제외합니다. 과금 기준은 계속 업로드한 오디오입니다.

기본값
true
scene_detectionboolean선택

Basic의 선택적 불리언이며 기본값은 false입니다. 단일 화자 작업에서 장면 감지와 화자 인식을 켭니다. Lite에서 켜면 처리 전에 조합을 거절하므로 사용하지 않습니다. 오디오 초당 단가는 바뀌지 않습니다.

기본값
false
remove_background_noiseboolean선택

Lite의 선택적 불리언이며 기본값은 false입니다. 입 움직임을 맞추기 전에 녹음에서 배경음을 분리합니다. Basic 테스트 3건이 실패한 결과를 반영해 이 조합은 접수 단계에서 거절하므로 Basic에서는 필드를 제외합니다. 오디오 초 단위 과금은 그대로 적용합니다.

기본값
false
generation_modestring선택

lite 또는 basic을 받는 선택 항목이며 기본값은 lite입니다. Lite는 정면의 단일 화자 영상, Basic은 복잡한 단일 화자 장면을 대상으로 합니다. Basic을 선택하면 사용 가능한 설정과 오디오 상한이 바뀌며 단가 차이는 없습니다.

기본값
"lite"
허용 값
"lite""basic"

작업 추적

HTTP 202는 접수되었다는 뜻이며 생성 완료가 아닙니다. 반환된 taskId를 저장하고 같은 작업을 조회하세요. 결과를 기다리는 동안 작업을 다시 생성하지 마세요.

접수 응답
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3

{
  "code": 200,
  "msg": "success",
  "request_id": "req_example_create",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued",
    "estimatedCost": "0.750000"
  }
}

접수 응답에 이번 예상 비용이 포함되므로 앱의 작업 기록과 청구 화면에 같은 금액을 표시할 수 있습니다.

작업 조회
curl --get "https://api.spicyapi.ai/api/v1/jobs/recordInfo" \
  --data-urlencode "taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

약 2초 간격으로 시작해서 점점 간격을 넓히세요. 종료 상태가 나오면 멈추고, 연결이 끊겼더라도 원래 taskId를 그대로 조회하세요. 다시 생성할 때는 처음에 쓴 Idempotency-Key와 본문을 그대로 써야 합니다.

아니면 콜백이 찾아오게 하세요
import { verifyWebhook } from "@spicyapi/sdk";

// express.raw keeps the bytes we signed; express.json never matches.
app.post("/hooks/spicy", express.raw({ type: "application/json" }), (req, res) => {
  const { payload } = verifyWebhook({
    rawBody: req.body,
    timestamp: req.header("X-Webhook-Timestamp"),
    signature: req.header("X-Webhook-Signature"),
    payloadVersion: Number(req.header("X-Webhook-Payload-Version")),
    secret: process.env.SPICY_WEBHOOK_SECRET,
  });
  res.status(200).end();
  void handleFinishedTask(payload);
});

작업을 만들 때 callBackUrl을 넘기면 완료된 레코드가 POST로 전달됩니다 — 폴링 루프가 아예 필요 없습니다. 모든 전달에는 X-Webhook-Timestamp, X-Webhook-Signature, X-Webhook-Payload-Version이 함께 옵니다. 서명은 taskId.timestamp.sha256(body)에 대한 base64 HMAC-SHA256이므로 반드시 원본 바이트로 검증해야 합니다. JSON을 파싱했다가 다시 직렬화하면 바이트가 달라져 검증이 실패합니다. 실패한 전달은 재시도되므로 같은 taskId가 두 번 올 수 있습니다. 핸들러를 멱등하게 만드세요. 먼저 2xx로 답하고 처리는 그다음에 — 응답이 느리면 전달 실패로 간주됩니다.

결과 읽기

state가 succeeded일 때만 output을 사용하세요. 실패 시 errorCode, errorMessage, request_id로 원인을 확인하세요. 예시 비용과 상태는 실제 청구 내역이 아닙니다.

완료 응답 예시
{
  "code": 200,
  "msg": "success",
  "request_id": "req_example_record",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "model": "bytedance/lip-sync/lip-sync",
    "state": "succeeded",
    "output": {
      "assets": [
        {
          "key": "tasks/2026/08/28/job_01k3m8x9q2z4v7n5p6r8s0t1w3/3f7a1c9e5b2d48f0a6c1e3d5b7f9a1c3.mp4",
          "mime": "video/mp4",
          "url": "https://example.r2.cloudflarestorage.com/results/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4?X-Amz-Signature=SIGNATURE_FROM_RESPONSE",
          "expiresAt": "2026-08-28T12:20:08.000Z"
        }
      ]
    },
    "cost": "0.750000",
    "settled": true,
    "createdAt": "2026-08-28T12:00:00Z",
    "completedAt": "2026-08-28T12:00:30Z"
  }
}

사용 가능한 파일은 assets[].url에서 바로 열거나 다운로드할 수 있으며 API Authorization 헤더가 필요하지 않습니다. 서명 URL은 expiresAt에 만료됩니다. 보관 기간 내에 작업을 다시 조회하면 URL이 갱신됩니다. 처리 중이거나 사용할 수 없는 파일에는 URL이 없습니다. 서명 URL은 비공개로 보관하세요.

SDK 및 연동

앱, 터미널, AI 어시스턴트 또는 시각적 워크플로에서 SpicyAPI를 사용하세요. 원하는 설정 가이드를 선택하세요.

ComfyUI에서 쓰기

ComfyUI Manager나 아래 명령으로 SpicyAPI 노드를 설치한 뒤 캔버스에서 ByteDance Lip Sync · Lip Sync a Video to New Audio를 검색하세요. 노드는 이 페이지와 같은 옵션을 제공하며, 실행하기 전에 가격을 보여 줍니다.

cd ComfyUI/custom_nodes
git clone https://github.com/spicyapi-ai/comfyui-spicyapi