FAQ
FAQ
Is this really OpenAI-compatible?
Yes. Point the OpenAI SDK’s base_url at https://hisoka.ai/api/v1 and keep your request
code. Chat completions, streaming and tool calls use the same shapes.
The same is true for Anthropic clients, which is why Claude Code and Cursor work with two
environment variables and no adapter.
Which endpoint do I use?
| Client | Endpoint |
|---|---|
| Claude Code, Cursor, Zed | POST /messages |
| Codex CLI | POST /responses |
| Cline, Roo, Kilo, Continue, aider, OpenAI SDK | POST /chat/completions |
Those clients have no fallback. A wrong endpoint reads as the gateway being broken, so check
this table before anything else.
Why does my base URL 404?
The base URL ends at /api/v1. The SDKs append their own version segment, so
https://hisoka.ai/api/v1 becomes /api/v1/chat/completions. Set it deeper and every
request misses.
The gateway collapses a repeated version segment (/api/v1/v1/messages works), but it
never strips a single one, because clients that send it once must keep working.
Do I need a balance for a free model?
Yes, a small one. A free model settles at zero per call, but it still consumes upstream
capacity, so an account spent down to nothing is refused with 402 and a message that names
the floor.
Reading that as a billing bug is reasonable, and it is not one: the model costs nothing,
the account is just not allowed to be empty.
Why did I get an empty answer?
Three different causes, and the reply tells you which:
| Signal | Cause |
|---|---|
finish_reason: "stop", reasoning present |
a reasoning model spent its budget thinking |
finish_reason: "length" |
the answer was cut off, raise max_tokens |
content: null, tool calls present |
the model called a tool instead of answering |
Only the second is worth retrying with a bigger cap. See
Reasoning models.
Why is my agent repeating the same tool?
Almost always tool_choice: "required" in the client, which forbids the model from
answering without a call. The gateway never rewrites an omitted tool_choice, so this is a
client setting. See Tool calling.
How do I know what a call cost?
hisoka.usd_micro_charged in the response is the exact integer the wallet moved.
hisoka.usd_charged is the same number as a rounded decimal, and on a cheap call the
rounding is the whole figure.
For history, GET /transactions gives per-call rows with the token counts behind each
charge.
Are failed requests billed?
No. A failure that produces an error charges nothing, and a reply that arrives but cannot be
metered is discarded rather than billed half (that is 502 usage_unavailable).
A gap in GET /transactions where your failed requests would be is the confirmation.
Can I use one key for several apps?
You can, but one key per application is better: revoking a leak then does not break
everything. See API keys.
Is there a batch API?
No. A request is a request. There is no queue to submit to and no discount for volume.
Do you store my prompts?
The gateway proxies a request and records usage: model, token counts, cost, status. The
prompt body is not stored in your ledger, and GET /transactions returns the token counts
rather than the text.
Why is a model missing from the catalogue?
An out-of-stock model is absent rather than listed and failing. Every connection behind it
being dead makes it unsellable, and a buyer who paid for a model that cannot answer is a
refund rather than an error message.
The catalogue is the authority: GET /api/v1/models.
What happens when a provider is down?
The request is retried on another account behind the same model, inside the same call, so
most blips never reach you. When everything is exhausted you get 429 pool_exhausted with a
Retry-After for the soonest free account. See Failover.
Can I get a different price?
Prices are set per model and published on GET /models. There is no per-account rate, no
volume discount, and no negotiation surface in the API.
How do I report a bug?
Include the request_id from the response, the endpoint, and the code. That is enough to
find the exact server-side attempt without exchanging prompts or keys.
Never paste a full API key.