Integration guide

Overview#

hinnflowAI is an AI model gateway: one API key reaches models from many providers, with unified billing and usage tracking. The API follows the OpenAI API format, so any OpenAI-compatible SDK, framework or client works as is.

Quick start#

1. Sign up and log in.
2. Open Console → API keys, create a key and save it (it starts with sk-).
3. Add credit in the Wallet, or redeem a top-up code.
4. Set the base URL to https://api.hinnflow.com/v1 and the API key to your new key, then make your first call:

curl https://api.hinnflow.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Introduce yourself in one sentence."}
    ]
  }'

Authentication#

Send your API key in the request header on every call:

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx

• A key spends your balance. Use it on the server only; never ship it in frontend code, app bundles or public repositories.
• Create separate keys per project, each with its own spend limit, expiry, allowed models and IP allowlist.
• If a key leaks, disable or delete it in the console and it stops working immediately.

Chat completions#

Generates a reply from the conversation so far. The most common endpoint. Key parameters:

Other parameters match the official OpenAI API and are passed through to the upstream model. Example response:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1792560000,
  "model": "deepseek-v4-flash",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 86,
    "total_tokens": 110
  }
}

Streaming#

Add "stream": true and the response arrives as a stream of SSE events, ideal for chat UIs that render as they go. The stream ends with data: [DONE].

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Write a short poem about the sea."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content if chunk.choices else None
    if delta:
        print(delta, end="", flush=True)

The raw event stream looks like this:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Waves"}}]}

data: [DONE]

List models#

Returns every model the key can call. If the key restricts models, only the allowed ones are listed. See the model list for pricing and availability.

curl https://api.hinnflow.com/v1/models \
  -H "Authorization: Bearer $API_KEY"

Other endpoints#

The gateway runs on new-api and also supports these OpenAI-format endpoints. Which endpoints a given model supports is shown in its details on the model list.

For full parameter details, see the new-api API reference.

Errors#

Errors return a non-2xx status with an OpenAI-style body:

{
  "error": {
    "message": "Invalid token (request id: 2026102110...)",
    "type": "new_api_error",
    "code": ""
  }
}

Billing#

• Most models are billed per token, with separate input and output prices listed per million tokens on the model list.
• Some models are billed per request, or tiered by time of day or context length (shown as “Dynamic pricing”).
• Requests that fail with an upstream error are not charged; any pre-held amount is returned.
• Your balance and per-request spend are in the console.

FAQ#