Skip to main content
POST
Create a response (ZeroClick-authenticated)
This is the Responses endpoint behind ZeroClick, ZeroGPU’s agent-payment layer. Same request/response bodies and same model routing as /v1/responses — only authentication, authorization, and metering differ.
  • 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 — actual token usage is settled with ZeroClick and reported via the zc-usage response header. Stripe metering is bypassed; ZeroClick is the sole biller.
The input and output shapes vary by model; open a model page for a prefilled playground. 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

application/json
model
string
required
Example:

"LFM2.5-1.2B-Instruct"

input
string
required

Prompt text. Combined with instructions (as a system message) to form the model input.

instructions
string

System-style instructions prepended to the input. Classification models may pass comma-separated or bracketed candidate labels here.

max_output_tokens
integer | null
parallel_tool_calls
boolean
default:true
previous_response_id
string | null
store
boolean
default:true
temperature
number | null
top_p
number | null
truncation
enum<string>
default:auto
Available options:
auto,
disabled
categories
string[]

Candidate labels for text-classification models.

multilingual
boolean
metadata
object

Up to 16 string key/value pairs echoed back in the response envelope. Also carries GLiNER usecase options (usecase, schema, labels, threshold, mask, replacement_char), which are consumed and not necessarily echoed.

text
object

Response

OpenAI Responses response object. Includes the zc-usage header settling actual usage with ZeroClick.

OpenAI Responses response object. On error, status is failed and error is populated.

id
string
object
string
Allowed value: "response"
created_at
integer
status
enum<string>
Available options:
completed,
failed
completed_at
integer | null
error
null | object

Error attached to a Responses envelope. OpenAI's ResponseError carries code and message; type and param are also emitted by some error sites on this endpoint.

incomplete_details
unknown
instructions
string | null
max_output_tokens
integer | null
model
string
output
object[]
parallel_tool_calls
boolean
previous_response_id
string | null
reasoning
object
store
boolean
temperature
number | null
text
object
tool_choice
string
tools
any[]
top_p
number | null
truncation
enum<string>
Available options:
auto,
disabled
usage
object | null
user
string | null
metadata
object