API 문서

API 키는 API 키 페이지에서 만듭니다. 글자당 언어에 따라 1~5크레딧이 차감되며(언어 항목 참고), 오디오 생성에 실패하면 크레딧이 환불됩니다.

AI 에이전트용

세 가지 연동 방법 중 에이전트가 지원하는 방법을 선택하세요. 기계 판독용 문서: /llms.txt (LLM용 안내) 및 /api/v1/openapi.json (OpenAPI 3.1).

1. MCP server

URL https://voicewrap247.com/api/mcp. 도구: list_voices, text_to_speech, get_job, dub_media, get_dubbing, get_balance. OAuth(로그인만 하면 되며 키 불필요) 또는 API 키로 인증합니다. list_voices와 text_to_speech는 선택 항목인 language 필드를 받습니다(언어 참고). dub_media는 공개 source_url의 동영상·오디오를 더빙하고, get_dubbing은 진행 상황과 결과 파일을 돌려줍니다(더빙 참고).

Claude.ai / Claude Desktop: API 키 불필요

Settings → Connectors → Add custom connector.
이름을 VoiceWrap으로 입력하고 URL https://voicewrap247.com/api/mcp를 붙여 넣은 뒤 Add를 클릭합니다.
Connect를 클릭하고 Google로 로그인한 뒤 허용을 선택합니다. 연결 해제는 API 키 페이지에서 할 수 있습니다.

다른 클라이언트는 API 키를 사용합니다:

Claude Code

claude mcp add --transport http voicewrap https://voicewrap247.com/api/mcp \
  --header "Authorization: Bearer sk_live_..."

Cursor · ~/.cursor/mcp.json

{
  "mcpServers": {
    "voicewrap": {
      "url": "https://voicewrap247.com/api/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}

Claude Desktop · claude_desktop_config.json

{
  "mcpServers": {
    "voicewrap": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://voicewrap247.com/api/mcp",
               "--header", "Authorization: Bearer sk_live_..."]
    }
  }
}

2. OpenAI SDK (base_url 변경)

Python

from openai import OpenAI

client = OpenAI(api_key="sk_live_...", base_url="https://voicewrap247.com/api/v1")
client.audio.speech.create(
    model="voicewrap", voice="Ngọc Huyền", input="Xin chào!"
).write_to_file("speech.mp3")

TypeScript

import OpenAI from "openai";

const client = new OpenAI({ apiKey: "sk_live_...", baseURL: "https://voicewrap247.com/api/v1" });
const res = await client.audio.speech.create({ model: "voicewrap", voice: "nova", input: "Xin chào!" });
await fs.promises.writeFile("speech.mp3", Buffer.from(await res.arrayBuffer()));

3. REST API

아래 섹션을 참고하세요.

인증

Authorization: Bearer sk_live_...

계정당 분당 30개 요청으로 제한됩니다. 요청당 텍스트는 최대 5,000자입니다.

OpenAI 호환: POST /api/v1/audio/speech

OpenAI와 같은 형식입니다. 오디오 파일을 바로 반환하며, 긴 텍스트는 완료될 때까지 기다립니다(최대 약 4.5분). model 필드는 무시됩니다. 선택 항목인 language 필드는 VoiceWrap 확장입니다(언어 참고).

curl https://voicewrap247.com/api/v1/audio/speech \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Xin chào, đây là VoiceWrap.", "voice": "Ngọc Huyền", "response_format": "mp3"}' \
  --output speech.mp3

OpenAI 목소리 이름도 사용할 수 있습니다. 베트남어에서는 다음과 같이 대응합니다: alloy → Ngọc Huyền, ash → Minh Triết, ballad → Ngọc Linh, coral → Thùy Dung, echo → Hải Đăng, fable → Thiện Minh, nova → Mai Anh, onyx → Thiền Tâm Đức, sage → Quỳnh Anh, shimmer → Trúc Ly, verse → Thanh Bình. 다른 언어에서는 각 이름이 같은 성별의 원어민 목소리에 대응합니다.

음성 생성(작업): POST /api/v1/tts

작업과 오디오 링크(1시간 후 만료)를 반환합니다. 500자 이하는 즉시 반환되고(200), 그보다 길거나 "async": true를 보내면 202를 반환하므로 이후 2~5초마다 GET /api/v1/tts/:id를 조회하세요.

curl https://voicewrap247.com/api/v1/tts \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Giá gói Pro là 100.000 đồng.", "voice": "Hải Đăng", "speed": 1.0, "format": "mp3"}'

{
  "id": "f0b2...",
  "status": "succeeded",          // queued | running | succeeded | failed
  "progress": 1,                  // 실행 중에는 0..1
  "queue_position": null,         // 대기 중이면 앞에 있는 작업 수
  "language": "vi",               // 읽은 언어, 생략 시 목소리의 언어 또는 자동 감지
  "audio_url": "https://...",     // 재생용, 1시간 후 만료
  "download_url": "https://...",  // 파일 다운로드
  "duration_seconds": 3.4,
  "chars": 28,                    // 텍스트 글자 수
  "cost": 28                      // 차감 크레딧: 글자 수 × 언어 가중치
}

언어

API는 11개 언어를 읽습니다. 기본 제공 목소리는 모두 원어민이며 자기 언어만 읽고, 직접 클로닝한 목소리는 어떤 언어든 읽을 수 있습니다. POST /api/v1/tts, POST /api/v1/audio/speech(OpenAI 형식에 대한 VoiceWrap 확장), MCP 도구 text_to_speech에 선택 항목인 language 필드(ISO 639-1 코드)를 보낼 수 있습니다. 생략하면 기본 제공 목소리는 그 목소리의 언어로 읽고, 클로닝한 목소리이거나 목소리를 지정하지 않으면 텍스트에서 언어를 감지합니다. 목소리를 지정하지 않으면 해당 언어의 기본 목소리(아래 참고)가 읽습니다. 숫자·퍼센트·통화는 언어별 읽는 방식대로 읽습니다.

지원 코드와 언어별 기본 목소리:

vi Tiếng Việt · Hải Đăng
en English · Emma
zh 中文 · Vivian
ja 日本語 · Anna
ko 한국어 · Sohee
fr Français · Camille
de Deutsch · Lena
es Español · Lucía
it Italiano · Giulia
pt Português · Beatriz
ru Русский · Natasha

그 외의 코드(텍스트에서 감지된 경우 포함)는 400 unsupported_language를 반환합니다. 기본 제공 목소리에 다른 language를 지정하면 400 voice_language_mismatch를 반환하며, 해당 언어의 목소리 목록을 알려 줍니다.

글자당 크레딧은 읽는 언어에 따라 다릅니다. cost = 글자 수 × 가중치(연속된 공백은 한 글자로 셉니다). 중국어·일본어·한국어는 한 글자가 한 음절이라 더 많이 차감됩니다.

글자당 크레딧	언어
×1	`vi` Tiếng Việt
×2	`en` English, `fr` Français, `de` Deutsch, `es` Español, `it` Italiano, `pt` Português, `ru` Русский
×5	`zh` 中文, `ja` 日本語, `ko` 한국어

POST /api/v1/tts

curl https://voicewrap247.com/api/v1/tts \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "こんにちは、VoiceWrap です。", "voice": "Anna", "language": "ja"}'

POST /api/v1/audio/speech

curl https://voicewrap247.com/api/v1/audio/speech \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello from VoiceWrap.", "voice": "nova", "language": "en"}' \
  --output hello.mp3

Python · OpenAI SDK

client.audio.speech.create(
    model="voicewrap", voice="nova", input="Hello from VoiceWrap.",
    extra_body={"language": "en"},  # language는 VoiceWrap 확장이므로 extra_body로 전달
).write_to_file("hello.mp3")

목소리: GET /api/v1/voices

voice에는 이름(성조 부호 유무 무관, 예: "ngoc-huyen"), id 또는 OpenAI 목소리 이름을 전달합니다. 비워 두면 해당 언어의 기본 목소리를 사용합니다. ?language=ja를 붙이면 그 언어를 읽는 목소리(와 클로닝한 목소리)만 반환합니다. 각 목소리에는 language(클로닝한 목소리는 null, 모든 언어 지원)와 gender가 있습니다.

curl "https://voicewrap247.com/api/v1/voices?language=vi" -H "Authorization: Bearer $VOICEWRAP_API_KEY"

{ "voices": [ { "id": "...", "name": "Ngọc Huyền", "key": "ngoc-huyen",
                "description": "Nữ · Miền Bắc · Tự nhiên", "type": "system",
                "language": "vi", "gender": "female",
                "preview_url": "https://..." } ] }

목소리 클론: POST /api/v1/voices

3~15초 분량의 깨끗한 음성과 정확한 대본이 필요합니다. 본인 또는 동의한 사람의 목소리만 사용하세요.

curl https://voicewrap247.com/api/v1/voices \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -F name="Giọng của tôi" \
  -F ref_text="Nội dung chính xác của đoạn ghi âm" \
  -F consent=true \
  -F file=@sample.wav

더빙: POST /api/v1/dubbing

동영상이나 오디오를 다른 언어로 더빙합니다. 음성을 받아 적고 번역해 대상 언어로 한 줄씩 읽은 뒤, 원래 배경음(음악과 효과음)에 섞습니다. 더빙된 MP4(동영상의 경우), MP3, 번역된 SRT 자막을 받습니다. 원본 길이 기준 분당 20,000크레딧, 초 단위 과금, 파일당 최소 1분이며 최대 15분입니다. 실패한 작업은 크레딧을 환불합니다.

1. 파일 업로드

POST /api/v1/dubbing/uploads에 파일 이름, 형식, 크기(최대 50MB)를 보내면 서명된 upload_url을 돌려줍니다. 여기에 파일을 PUT(Content-Type 포함)한 뒤 2단계에서 upload_path를 전달하세요. 공개된 파일이나 더 큰 파일은 이 단계를 건너뛰고 source_url을 보내면 됩니다.

curl https://voicewrap247.com/api/v1/dubbing/uploads \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "intro.mp4", "content_type": "video/mp4", "size": 18874368}'

{ "upload_path": "…/source.mp4", "upload_url": "https://…", "token": "…" }

curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --data-binary @intro.mp4

2. 작업 만들기

POST /api/v1/dubbing은 202와 작업을 돌려줍니다. upload_path와 source_url 중 하나만 보내세요.

curl https://voicewrap247.com/api/v1/dubbing \
  -H "Authorization: Bearer $VOICEWRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{
  "upload_path": "…/source.mp4",  // 1단계에서 받은 값(또는 source_url)
  "source_name": "intro.mp4",     // 선택, 표시 이름
  "target_language": "en",        // 더빙할 언어
  "source_language": "vi",        // 선택, 자동 감지
  "voice": "clone",               // "clone" 또는 목소리 이름/id
  "consent": true                 // "clone"이면 필수
}
EOF

"voice": "clone"(기본값)은 화자 본인의 목소리를 유지하며 "consent": true가 필요합니다. 파일 속 인물의 목소리를 사용할 권리가 있음을 확인하는 값입니다. 그 밖에 대상 언어를 읽는 기본 목소리의 이름이나 id(GET /api/v1/voices?language=...), 또는 내가 복제한 목소리를 보낼 수 있습니다.

3. 결과 조회

status가 succeeded나 failed가 될 때까지 5~10초마다 GET /api/v1/dubbing/:id를 조회하세요. 더빙에는 몇 분이 걸립니다. 파일 링크는 서명되어 있으며 1시간 후 만료되므로, 작업을 다시 조회하면 새 링크를 받습니다. GET /api/v1/dubbing은 최근 작업 20개를 돌려줍니다(lines 제외).

curl https://voicewrap247.com/api/v1/dubbing/8c1e... -H "Authorization: Bearer $VOICEWRAP_API_KEY"

{
  "id": "8c1e...",
  "status": "succeeded",          // queued | running | succeeded | failed
  "progress": 1,                  // 0..1
  "source_name": "intro.mp4",
  "is_video": true,
  "source_language": "vi",
  "target_language": "en",
  "voice": "clone",
  "duration_seconds": 92.4,
  "cost": 30800,                  // 차감된 크레딧, 초 단위
  "files": {                      // 서명된 링크, 1시간 후 만료
    "video": "https://...",       // MP4, 오디오면 null
    "audio": "https://...",       // MP3
    "subtitles": "https://..."    // 번역된 SRT
  },
  "lines": [                      // 각 줄: 원문과 번역
    { "start": 0.4, "end": 3.1, "text": "Xin chào các bạn", "translation": "Hi everyone" }
  ],
  "error": null,
  "created_at": "2026-10-25T08:00:00Z",
  "finished_at": "2026-10-25T08:03:12Z"
}

제한: 업로드 최대 50MB, 원본 최대 15분, 시간당 작업 20개. 전용 오류 코드: 400 consent_required, unreadable_media, too_long, 404 upload_not_found, 502 dubbing_failed(크레딧 환불됨).

오류 코드

{ "error": { "code": "insufficient_credits", "message": "..." } }

400 invalid_request (예: 필드 누락 또는 잘못된 값)
400 unsupported_language (11개 언어 밖의 코드, 텍스트에서 감지된 경우 포함)
400 voice_language_mismatch (기본 제공 목소리에 다른 language 지정, 메시지에 해당 언어의 목소리 목록 포함)
401 invalid_api_key, unauthorized
402 insufficient_credits
404 voice_not_found (목소리 목록 포함), job_not_found
429 rate_limited
400 consent_required, unreadable_media, too_long, 404 upload_not_found, 502 dubbing_failed (더빙)
502 synthesis_failed (크레딧 환불됨)
504 still_running (/audio/speech에서만, id로 작업 조회)