OpenAI-Compatible API

ColabHive exposes an OpenAI-compatible chat endpoint so you can point existing OpenAI clients at the platform with only a base-URL and API-key change.

POST https://api.colabhive.com/v1/chat/completions
GET  https://api.colabhive.com/v1/models
GET  https://api.colabhive.com/v1/models/{model}

Note the prefix: this surface is mounted at /v1 (the API root), not under /api/builder/v1.

Authenticate with your ColabHive API key (hive_…) — see Authentication. Errors are returned as OpenAI-style error objects ({"error": {"message": ..., "type": ...}}), so the official SDKs raise their normal exception types (AuthenticationError on 401, NotFoundError on 404).

---

Request

{
  "model": "qwen-2.5-7b-instruct",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is machine learning?"}
  ],
  "max_tokens": 500,
  "temperature": 0.7
}

Field	Type	Notes
model	string	Required. Preferably a ColabHive endpoint UUID from GET /v1/models — that is the canonical identifier and always routes to the right deployment. A model name is also accepted and resolved to an active base model; unknown values return 404.
messages	array	Required, non-empty. OpenAI chat messages (role + content); tool role is accepted.
max_tokens	int	Optional.
temperature	number	Optional.
stream	bool	Optional. See Streaming — note the current behavior.

Passthrough fields. Additional OpenAI fields are forwarded verbatim to the model server: tools, tool_choice, parallel_tool_calls, response_format, and other unknown fields. Tool calling requires the target model to have been started with tool-choice support; when available, the response includes tool_calls and finish_reason: "tool_calls".

---

Response

A standard OpenAI chat.completion object:

{
  "id": "chatcmpl-8f2a...",
  "object": "chat.completion",
  "created": 1770000000,
  "model": "qwen-2.5-7b-instruct",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Machine learning is..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
}

When the underlying model server emits tool_calls, finish_reason, and token usage, those pass through unchanged. If the served model does not report token counts, usage fields are 0.

This endpoint runs a synchronous request. If the target model is cold, the gateway derives its wait ceiling from measured load time for that model, with a conservative fallback when no measurement exists. If it cannot produce a result within that ceiling it returns HTTP 503 — retry shortly or pre-warm the model with a small request first.

---

Streaming

Passing "stream": true returns incremental, token-by-token SSE (Content-Type: text/event-stream): the deltas are forwarded from the model server as they are produced, ending with data: [DONE]. Use it exactly as you would with OpenAI.

stream = client.chat.completions.create(
    model="5d21e32a-3bbb-4040-9c34-3b06c4415b84",
    messages=[{"role": "user", "content": "Write a short paragraph about distributed computing."}],
    max_tokens=800,
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Automatic fallback on older nodes

If the node serving your request runs a node-runtime older than 0.10.195, it cannot emit incremental deltas. In that case the gateway falls back to the previous behaviour — the full completion arrives as one chat.completion.chunk followed by data: [DONE]. The response is still valid SSE and the official SDKs consume it without changes, so a mixed-version fleet never breaks a client; you simply get the answer all at once instead of gradually.

---

Listing models

GET /v1/models returns the standard OpenAI model list. The id of each entry is a ColabHive endpoint UUID — the exact value to pass as model in a chat request, so whatever a client lists is always something it can actually call.

{
  "object": "list",
  "data": [
    {
      "id": "5d21e32a-3bbb-4040-9c34-3b06c4415b84",
      "object": "model",
      "created": 1767654203,
      "owned_by": "colabhive",
      "name": "gpt-oss-20b",
      "task_type": "text-generation"
    }
  ]
}

name and task_type are ColabHive extensions — the official SDKs ignore unknown fields, while UIs that understand them can show a readable label instead of a raw UUID.

What you see. Models owned by your account, plus the approved public catalogue. The list is scoped to models this surface can actually serve (chat-capable LLMs); trained tabular, forecasting and specialist endpoints are not listed here — reach those through the Inference API.

Retrieve a model

GET /v1/models/{model} retrieves a single entry, accepting either the endpoint UUID or the endpoint name, and returns 404 with an OpenAI error object if it is unknown or not visible to you.

---

Reasoning models

Some models (for example gpt-oss-20b) reason before answering and return that trace in a separate reasoning_content field on the message. The user-facing text is always in the usual choices[0].message.content.

Give reasoning models enough max_tokens

The reasoning trace consumes the same token budget as the answer. With a small max_tokens, the model can spend it all reasoning and return an empty content with finish_reason: "length". If you get blank answers from a reasoning model, raise max_tokens before anything else.

---

Examples

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://api.colabhive.com/v1",
    api_key="hive_...",
)

# Discover what you can call — each `id` is usable as `model` verbatim.
for m in client.models.list():
    print(m.id, m.name)

resp = client.chat.completions.create(
    model="5d21e32a-3bbb-4040-9c34-3b06c4415b84",
    messages=[{"role": "user", "content": "What is machine learning?"}],
    max_tokens=500,
)
print(resp.choices[0].message.content)

cURL

curl "https://api.colabhive.com/v1/models" \
  -H "Authorization: Bearer hive_..."

curl -X POST "https://api.colabhive.com/v1/chat/completions" \
  -H "Authorization: Bearer hive_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "5d21e32a-3bbb-4040-9c34-3b06c4415b84",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 500
  }'

---

See Also

• Inference API — the native inference surface (sync/async, readiness, binary I/O)
• Actions API — discover callable models and their slugs
• Models API — import HF models, registry, capabilities