Skip to main content
POST
Create speech (ZeroClick-authenticated)
This is the Speech endpoint behind ZeroClick, ZeroGPU’s agent-payment layer. Same request/response bodies, limits, and model as /v1/audio/speech — only authentication, authorization, and metering differ. The body is streamed upstream unread, so the request is always served by the configured model (chatterbox-nano). Send JSON, or multipart/form-data with a voice_sample to clone a voice.
  • Authentication — no x-api-key. A buying agent calls ZeroClick’s hosted pay URL; ZeroClick proxies the request and signs the raw request bytes with an HMAC in the zc-signature header. A request is authenticated only by a valid signature.
  • Authorization — a ZeroClick allowance check runs before any billable work. It fails open on a transient ZeroClick outage (the signature has already verified), but never for a missing or invalid signature.
  • Metering — billed per audio second. The allowance check asks for a 1-second floor, since the duration is not known until the clip is decoded or generated. On success, zc-usage reports max(1, ceil(x-audio-duration-seconds)) audio seconds. Stripe metering is bypassed; ZeroClick is the sole biller.
Handle errors the same way as API error codes.

Authorizations

zc-signature
string
header
required

HMAC signature minted by ZeroClick over the raw request bytes, of the form t=<unix-seconds>,kid=<key-id>,v1=<hex-hmac>. Verified by the @zeroclickai/sellers SDK against the seller's signing secret keyed by kid. A missing or invalid signature is rejected with 401 invalid_zeroclick_signature; this is never failed open.

Headers

zc-request-id
string

ZeroClick request id, echoed in logs for correlation. Set by ZeroClick when it proxies the request.

Example:

"zcreq_1"

zc-agent-id
string

Identifier of the buying agent. Used to partition logs/analytics by agent; becomes the synthesized caller identity.

Example:

"agt_1"

Body

Multipart form, required for voice cloning.

input
string<textarea>
required

The text to speak. Inline tags such as [laugh] and [cough] add paralinguistic cues.

Required string length: 1 - 2000
Example:

"Testing model to generate voice. Hey how are you today?"

model
enum<string>
default:chatterbox-nano

Model identifier. The endpoint serves chatterbox-nano.

Available options:
chatterbox-nano
Example:

"chatterbox-nano"

voice
enum<string>
default:default

OpenAI voice names are accepted and all map to the built-in voice.

Available options:
default,
builtin,
chatterbox,
alloy,
ash,
ballad,
cedar,
coral,
echo,
fable,
marin,
nova,
onyx,
sage,
shimmer,
verse
Example:

"default"

response_format
enum<string>
default:mp3

pcm is raw 16-bit little-endian mono at 24 kHz.

Available options:
mp3,
opus,
aac,
flac,
wav,
pcm
Example:

"mp3"

seed
integer

Pins sampling for repeatable output (best-effort).

Required range: 0 <= x <= 4294967295
Example:

1234

temperature
number
default:0.8

Sampling temperature.

Required range: 0 <= x <= 2
top_p
number
default:0.95

Nucleus sampling.

Required range: 0 <= x <= 1
top_k
integer
default:1000

Top-k sampling.

Required range: 0 <= x <= 10000
repetition_penalty
number
default:1.2

Penalty on repeated speech tokens.

Required range: 1 <= x <= 4
voice_sample
file

Reference clip to clone a voice from. Overrides voice. Not stored.

Response

The audio file, with a content type matching response_format. Includes the zc-usage header settling actual usage with ZeroClick.

The response is of type file.