API REFERENCE · CHAT COMPLETIONS

Chat completions

OpenAI-compatible endpoint for chat-style conversations. Use this for almost everything text-shaped: assistants, RAG, code generation, summarization, agents.

POSThttps://api.hoonify.ai/v1/chat/completions

Authentication

Send your API key as a bearer token. See the Subscriptions page for creating and rotating keys.

shell

Authorization: Bearer hoon_…

Request body

Field	Type	Description
model	string · required	Model identifier — e.g. `deepseek-v4-pro`. See catalog.
messages	array · required	Conversation turns. Each item is `{role, content}`. Roles: `system`, `user`, `assistant`, `tool`.
temperature	number · 0–2	Sampling temperature. Default `0.7`. Lower = more deterministic.
max_tokens	integer	Hard cap on completion tokens. Defaults to model max if omitted.
top_p	number · 0–1	Nucleus sampling. Default `1`. Use this or temperature, not both.
top_k	integer	Hoonify extension. Sample from the top-k logits. Default `0` (off).
stream	boolean	If `true`, returns Server-Sent Events instead of one JSON body.
tools	array	Function-calling. Same shape as the OpenAI `tools` array.

Example request

json

{
  "model": "deepseek-ai/DeepSeek-V4-Pro",
  "messages": [
    {"role": "system", "content": "You are a helpful AI assistant."},
    {"role": "user",   "content": "Summarize quantum tunneling in one paragraph."}
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "top_p": 0.95,
  "stream": false
}

Response

Non-streaming responses return a single JSON body. Streaming responses are an SSE stream of chat.completion.chunk objects terminated by [DONE].

json

{
  "id": "chatcmpl-FRcX2Fe1k4vR",
  "object": "chat.completion",
  "created": 1745784012,
  "model": "deepseek-ai/DeepSeek-V4-Pro",
  "system_fingerprint": "hoonify-fp8-r12",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum tunneling is the phenomenon where a particle…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 142,
    "total_tokens": 170
  }
}

Errors

Errors return the OpenAI-style error envelope: {"error": {"type": ..., "message": ...}}.

Status	Type	Cause
400	invalid_request	Malformed JSON, unsupported field, or invalid value.
401	unauthorized	Missing, malformed, or revoked API key.
404	model_not_found	Model ID does not exist or is not available to your org.
409	no_capacity	No replica currently available. Retry with backoff.
429	rate_limited	Per-key RPM exceeded. Back off and retry with jitter.
503	unavailable	Temporarily unable to serve the request. Retry with backoff.

Idempotency

For long completions, set X-Hoonify-Idempotency-Keyon retries. Hoonify deduplicates within a 5-minute window — you won't pay twice for a request that succeeded server-side but failed mid-flight back to your client.

Tool calling

Pass tools with JSON-Schema function definitions. The model returns atool_calls array on the assistant message; you execute the call and post the result back as a tool-role message in the next turn. Same shape as the OpenAI tools API — drop-in compatible.