Chat Completions

Endpoint

Requires an API key with the inference scope. The body must be JSON with Content-Type: application/json and at most 2 MB.

Request body

Fields not listed, such as response_format, seed or logprobs, are ignored. Validation failures return invalid_request with param set to the path of the offending field, for example messages.0.content.

Messages

content is a string or an array of { "type": "text", "text": "…" } parts, which are concatenated without separators.

Tools

Tools are supported only by models with the tools capability. Sending tools to any other model returns invalid_request with param: "tools".

• function.name must match ^[a-zA-Z0-9_-]{1,64}$.
• function.description is optional, up to 2,000 characters.
• function.parameters is a JSON Schema object; it defaults to an empty object schema.
• Tool call arguments in assistant messages may be up to 100,000 characters.

{
  "model": "claude-sonnet",
  "messages": [
    { "role": "user", "content": "What is 2^61 - 1? Use the calculator." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "calculate",
        "description": "Evaluate an integer arithmetic expression.",
        "parameters": {
          "type": "object",
          "properties": { "expression": { "type": "string" } },
          "required": ["expression"]
        }
      }
    }
  ]
}

When the model calls a tool, the response has finish_reason: "tool_calls" and message.tool_calls. Run the tool yourself, then send its result back:

{
  "model": "claude-sonnet",
  "messages": [
    { "role": "user", "content": "What is 2^61 - 1? Use the calculator." },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "toolu_01",
          "type": "function",
          "function": { "name": "calculate", "arguments": "{\"expression\":\"2**61 - 1\"}" }
        }
      ]
    },
    { "role": "tool", "tool_call_id": "toolu_01", "content": "2305843009213693951" }
  ],
  "tools": [ ... ]
}

Each round trip is a separate billed request with its own receipt. The gateway does not execute your tools; for hosted code execution see Sandboxes and Agents.

Example

curl https://www.hushcompute.xyz/v1/chat/completions \
  -H "Authorization: Bearer $HUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet",
    "max_completion_tokens": 1024,
    "messages": [
      { "role": "system", "content": "Answer in one paragraph." },
      { "role": "user", "content": "Why do reservations make prepaid billing safe?" }
    ]
  }'

Response

{
  "id": "req_01K58ZQ4W5V8E2R7PKD3N6A0TG",
  "object": "chat.completion",
  "created": 1789387200,
  "model": "claude-sonnet",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "A reservation sets aside ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 480, "completion_tokens": 310, "total_tokens": 790 },
  "receipt": {
    "id": "rcpt_01K58ZQ4W6N3T2B9XRC7D1M5HJ",
    "hash": "0x6f0d…a3c9",
    "signature": "0x9b1f…c07e1b",
    "signer": "0x3A4c…91De",
    "url": "https://www.hushcompute.xyz/proofs/rcpt_01K58ZQ4W6N3T2B9XRC7D1M5HJ"
  },
  "billing": {
    "request_id": "req_01K58ZQ4W5V8E2R7PKD3N6A0TG",
    "cost_micro_usd": "4466",
    "cost_usd": "0.004466",
    "usage_estimated": false,
    "fingerprint_salt": "0x51c2…7f08"
  }
}

Streaming

With stream: true the response is text/event-stream. Each event is a data: line with a chat.completion.chunk object:

1. A first chunk with delta: { "role": "assistant", "content": "" }.
2. Content chunks with delta.content, or a tool-call chunk with delta.tool_calls.
3. A chunk with an empty delta and the finish_reason.
4. A final chunk with "choices": [] plus usage, receipt, billing and latency_ms.
5. The terminator data: [DONE].

data: {"id":"req_01K5…","object":"chat.completion.chunk","created":1789387200,"model":"claude-sonnet","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"req_01K5…","object":"chat.completion.chunk","created":1789387200,"model":"claude-sonnet","choices":[{"index":0,"delta":{"content":"A reservation"},"finish_reason":null}]}

data: {"id":"req_01K5…","object":"chat.completion.chunk","created":1789387200,"model":"claude-sonnet","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"req_01K5…","object":"chat.completion.chunk","created":1789387200,"model":"claude-sonnet","choices":[],"usage":{"prompt_tokens":480,"completion_tokens":310,"total_tokens":790},"receipt":{"id":"rcpt_01K5…","hash":"0x6f0d…","signature":"0x9b1f…","signer":"0x3A4c…","url":"https://www.hushcompute.xyz/proofs/rcpt_01K5…"},"billing":{"request_id":"req_01K5…","cost_micro_usd":"4466","cost_usd":"0.004466","usage_estimated":false,"fingerprint_salt":"0x51c2…"},"latency_ms":2130}

data: [DONE]

Tool calls are delivered in a single chunk containing complete arguments for every call, each with an index, rather than as incremental fragments.

const stream = await client.chat.completions.create({
  model: "claude-sonnet",
  messages: [{ role: "user", content: "Write a haiku about ledgers." }],
  stream: true,
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);

  // The final chunk has no choices and carries usage, receipt and billing.
  if (chunk.choices.length === 0) {
    const final = chunk as typeof chunk & {
      receipt: { id: string; url: string };
      billing: { cost_micro_usd: string; fingerprint_salt: string };
      latency_ms: number;
    };
    console.log("\n", final.usage, final.billing.cost_micro_usd, final.receipt.url);
  }
}

The x-request-id and x-receipt-id headers are sent when the stream opens, before the outcome is known.

Errors during a stream

Authentication, validation, policy, rate-limit, budget and balance checks all run before the stream opens, so those failures arrive as a normal JSON error with an HTTP error status. Once HTTP 200 has been sent, a failure is reported in-band as a data: event with an error object, followed by data: [DONE]:

• Output already delivered. The delivered portion is metered (estimated if the provider reported no usage) and receipted with status failed. The error event includes receipt and billing for that portion.
• Nothing delivered. The reservation is released in full, nothing is charged, and no receipt is issued. The receipt ID in the x-receipt-id header will not resolve.

data: {"error":{"type":"provider_error","message":"The upstream provider could not be reached.","request_id":"req_01K5…"},"receipt":{"id":"rcpt_01K5…","hash":"0x…","signature":"0x…","signer":"0x…","url":"https://www.hushcompute.xyz/proofs/rcpt_01K5…"},"billing":{"request_id":"req_01K5…","cost_micro_usd":"913","cost_usd":"0.000913","usage_estimated":true,"fingerprint_salt":"0x…"}}

data: [DONE]

If the client disconnects mid-stream, the gateway cancels the upstream request and applies the same rules.

Billing behaviour

• Before calling the model, the gateway reserves a conservative estimate of the input cost plus max_completion_tokens at the output price. After completion it charges the actual cost and releases the remainder. See Usage.
• A non-streaming request that fails upstream is not charged: the reservation is released and no receipt is issued.
• When a provider omits token usage, usage_estimated is true and the gateway bills an estimate: half its conservative input estimate, and one output token per four UTF-8 bytes of generated content.

Compatibility notes

• The response id is the gateway request ID, not an upstream completion ID.
• Only one choice is returned; n must be 1.
• tool_choice supports auto and none only; required or a named function returns 400.
• Streaming always ends with a usage chunk followed by [DONE]. Clients that ignore chunks with empty choices are unaffected.