VoiceWrap

API 문서

API 키는 API 키 페이지에서 만듭니다. 글자 1자당 1크레딧이 차감되며, 오디오 생성에 실패하면 크레딧이 환불됩니다.

AI 에이전트용

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

1. MCP server

URL https://voicewrap.app/api/mcp. 도구: list_voices, text_to_speech, get_job, get_balance. OAuth(로그인만 하면 되며 키 불필요) 또는 API 키로 인증합니다. list_voices와 text_to_speech는 선택 항목인 language 필드를 받습니다(언어 참고).

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

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

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

Claude Code
claude mcp add --transport http voicewrap https://voicewrap.app/api/mcp \
  --header "Authorization: Bearer sk_live_..."
Cursor · ~/.cursor/mcp.json
{
  "mcpServers": {
    "voicewrap": {
      "url": "https://voicewrap.app/api/mcp",
      "headers": { "Authorization": "Bearer sk_live_..." }
    }
  }
}
Claude Desktop · claude_desktop_config.json
{
  "mcpServers": {
    "voicewrap": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://voicewrap.app/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://voicewrap.app/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://voicewrap.app/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://voicewrap.app/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://voicewrap.app/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,
  "cost": 28
}

언어

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

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

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

POST /api/v1/tts
curl https://voicewrap.app/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://voicewrap.app/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://voicewrap.app/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://voicewrap.app/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

오류 코드

{ "error": { "code": "insufficient_credits", "message": "..." } }
API 문서 · VoiceWrap