Your voices.
In your own workflow.

Give each integration its own key.

Sign in and open Developers. Name your key, choose its permissions, set an expiry and a cumulative credit budget, then copy the secret shown once. Keep it in your server's secret configuration.

voices:read

Discover library voices and your saved custom voices.

generations:write

Estimate, generate and cancel queued work. An estimate spends nothing.

generations:read

Read your job status and history, and download audio.

usage:read

Read available, reserved and spent generation credits.

New keys start with read-only permissions selected. Add generations:write to estimate or generate. Send the key in an Authorization: Bearer header; never put it in a URL, frontend bundle or tool argument.

Choose the ceiling, then stay in control

A key's budget counts its successful and currently reserved generation credits over its lifetime. It does not reset monthly or add funds to your account. The separate maxCredits field caps one generation.

The key form supports 1–365 days of access and budgets from 1 to 100,000,000 credits. To rotate a secret or change its permissions, budget or expiry, create a replacement and revoke the old key. Up to 20 active, unexpired credentials, including OAuth connections, can exist at once.

Your first REST generation.

Use https://www.vocalcopycat.com/api/v1. The shell examples below assume you have configured VCC_API_KEY privately. Each generation is asynchronous: keep its job ID while the audio is being made.

1. Find an available voice

curl --fail-with-body https://www.vocalcopycat.com/api/v1/voices \
  -H "Authorization: Bearer $VCC_API_KEY"

Choose an actual id from data and set VCC_VOICE_ID to it. IDs look like catalog:123 or custom:456; these numbers are examples. If the response includes nextCursor, pass it as the URL-encoded cursor parameter to read another page.

2. Ask for the price

curl --fail-with-body https://www.vocalcopycat.com/api/v1/generations/estimate \
  -H "Authorization: Bearer $VCC_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"voiceId\":\"$VCC_VOICE_ID\",\"text\":\"Hello from VocalCopyCat.\"}"

The response includes credits, units, pricingVersion and billingUnit. This spends nothing. Set VCC_MAX_CREDITS to the integer ceiling you approve before submitting.

3. Submit with an idempotency key

Set VCC_IDEMPOTENCY_KEY to a new unique value, such as a UUID, and save it with the exact input. It identifies this one intended generation.

curl --fail-with-body https://www.vocalcopycat.com/api/v1/generations \
  -H "Authorization: Bearer $VCC_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $VCC_IDEMPOTENCY_KEY" \
  --data "{\"voiceId\":\"$VCC_VOICE_ID\",\"text\":\"Hello from VocalCopyCat.\",\"maxCredits\":$VCC_MAX_CREDITS}"

HTTP 202 returns the job id, status and reserved credits. Keep the ID. After an interrupted request, retry with the same key and exactly the same input, including the credit ceiling. A matching retry returns the existing job; different input with that key returns 409.

Idempotency keys are 8–128 characters: letters, digits, dots, underscores, colons or hyphens. Use a new key only for deliberately new work. REST accepts an omitted maxCredits, but we recommend always including it.

4. Check that job, then download

curl --fail-with-body "https://www.vocalcopycat.com/api/v1/generations/$VCC_JOB_ID" \
  -H "Authorization: Bearer $VCC_API_KEY"

While status is queued, running or persisting, wait before checking again. Start around two seconds, then back off to five and ten. Stop on succeeded, failed or cancelled. Use a bounded deadline and honor Retry-After when present.

A successful job includes a relative audioUrl. Fetch it with your key and handle its 307 redirect manually. Download the signed HTTPS URL from Location in a separate request without the API key. The storage link lasts 15 minutes; the authenticated audio endpoint can issue a fresh one.

# After configuring the environment above:
node examples/generate.mjs

# Resume without creating new work:
VCC_JOB_ID='<existing-job-uuid>' node examples/generate.mjs

History, cancellation and one-off cloning

GET /api/v1/generations lists your latest 30 jobs across the browser, API and MCP. GET /api/v1/usage returns account generation usage. To cancel a queued job, use POST /api/v1/generations/{id}/cancel; work that has started returns 409.

For a one-off reference, the generation endpoint also accepts multipart audioFile, text and maxCredits, with the same idempotency header. Quote it using the estimate endpoint with {"type":"clone","text":"..."}. Upload audio you own or have permission to use. Reusable voice creation is available in My voices.

Connect an AI client through MCP.

Add this exact endpoint in a client that supports remote Streamable HTTP:

https://www.vocalcopycat.com/mcp

Connect with OAuth

1. Let your compatible client discover the authorization server, register its callback and open the VocalCopyCat sign-in page.
2. Review the app name, callback and requested permissions. Read-only access is the default. To estimate or generate speech, your client must request generations:write before opening consent; the consent page does not edit permissions.
3. Approve a credit budget before allowing generation. An OAuth connection can have a ceiling up to 1,000,000 credits.
4. Reauthorize when its one-hour token expires, or revoke the connection in Developers. Refresh tokens are not currently supported.

OAuth tokens are restricted to MCP. For REST, create a developer key. Clients with configurable bearer authentication can also use that developer key on the MCP endpoint, following its own expiry and budget.

Choose a returned voice ID, estimate the cost, then authorize generation with a unique idempotencyKey and required maxCredits. Save the job ID and check active work with bounded get_generation calls. On success, this tool returns a signed download URL directly, valid for 15 minutes.

MCP returns metadata and links, rather than embedded audio. It has no upload, voice-creation, history-listing or cancellation tool. You can use saved custom voices that already belong to your account. Tool errors set isError: true with a text JSON code and error; HTTP 200 alone does not mean a tool succeeded.

Clear limits. Shared credits.

Pricing follows normalized UTF-8 bytes

Library voices cost one credit per byte; saved custom voices and uploaded references cost five. Characters can use more than one byte. The browser shows a local typing estimate; integrations can ask the server for a quote when generation is intended. Submission checks the current price, funds and approved ceiling again.

Accepted jobs reserve credits. Success captures them, and terminal failure or queued cancellation returns the reservation once. The API and MCP do not provide a separate balance or credit package.

Request limits and supported uploads

Current defaults allow 180 authenticated REST requests per minute and 120 MCP requests per minute, per account. Multipart generation submissions are limited to 10 per hour. Key creation is also limited to 10 per hour. Queue capacity can produce a 429 response before you reach these limits.

Reference files must contain supported, readable audio: WAV, MP3, Ogg, FLAC, WebM or MP4/M4A. Four MiB means 4,194,304 bytes. Arbitrary reference URLs are not accepted. These limits describe the current service, not a throughput or availability guarantee.

Poll only work you are actively waiting for, back off while it runs and stop at a terminal result or your local deadline. Pause browser polling when hidden or offline. Idle history and balance polling is unnecessary.

Recover the job. Keep the audio private.

A lost connection does not cancel work

Keep the job ID and read it again when you reconnect. If the submission response never arrived, retry its same idempotency key and input. Do not create a new generation just because your local waiting limit ended. Only queued, unstarted work can be cancelled; revoking a credential also leaves accepted jobs in place.

Read the error before retrying

• 400 or 413: correct the input or media limits. 401: replace an expired or revoked credential. 403: check permissions or the MCP client Origin.
• 402: check the account balance, cumulative credential budget and this request's maxCredits.
• 404: check the ID and owning account. 409: resolve conflicting idempotency input, unfinished audio or cancellation after work started.
• 429 or temporary 5xx: back off within a bounded deadline. Honor Retry-After when present; keep the same submission key and payload.

REST errors include error, code, requestId and retryable. Save safe codes and request IDs for support. A failed job may also contain a code; review it before deliberately creating another generation.

Refresh links without regenerating

Generated audio is stored privately. A signed link grants access to anyone holding it until it expires, so keep it out of public logs and posts. Request the audio endpoint again, or use MCP's get_generation, to get a fresh link. Never send the API secret to the storage URL.

The 15-minute link lifetime is not a deletion schedule or a guarantee of permanent storage. Revoking a key blocks future authentication but does not invalidate already issued links. Download important results to your own storage.

The current interface does not include webhooks, batch submission, streaming speech, OAuth refresh tokens or a published uptime guarantee.