OpenAI Chat Completions

POST /v1/chat/completions

OpenAI-compatible chat completions. All standard parameters are accepted (temperature, max_tokens, tools, top_p, stop, etc.).

See OpenAI's documentation for the full request and response specification.

Request

curl https://hyper.charm.land/v1/chat/completions \
  -H "Authorization: Bearer sk-hyper-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "system", "content": "You are helpful."},
      {"role": "user", "content": "Hello!"}
    ]
  }'

Field	Type	Required	Description
model	string	yes	Model ID from /v1/models
messages	array	yes	Array of message objects
stream	boolean	no	Set true for SSE streaming (default false)
temperature	number	no	0–2
max_tokens	integer	no	Max output tokens
tools	array	no	Tool/function definitions

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1718000000,
  "model": "deepseek-v4-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hey there!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 5,
    "total_tokens": 15,
    "cost": {
      "usd": 0.000012,
      "hypercredits": 12
    },
    "remaining": {
      "hypercredits": 88
    }
  }
}

Custom Usage Fields

Hyper extends the standard usage object with cost and balance information:

Field	Description
usage.cost.usd	Cost of this request in USD
usage.cost.hypercredits	Cost in Hypercredits
usage.remaining.hypercredits	Team's remaining Hypercredit balance after this request

These fields are included in both regular and streaming responses. For streaming, they appear in the final chunk when include_usage is enabled via stream_options.

Streaming

Set "stream": true to receive server-sent events:

curl https://hyper.charm.land/v1/chat/completions \
  -H "Authorization: Bearer sk-hyper-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

Each chunk is a data: line containing a chat.completion.chunk object. The stream ends with data: [DONE].

Errors

All errors use the standard OpenAI error format:

{
  "error": {
    "message": "...",
    "type": "...",
    "code": null
  }
}

Status	error.type	Cause
400	invalid_request_error	Invalid JSON, missing model or messages, context window exceeded
401	authentication_error	Missing or invalid API key
402	billing_error	Insufficient Hypercredits
403	permission_error	Forbidden
404	invalid_request_error	Model not found
429	rate_limit_error	Rate limit exceeded
5xx	server_error	Upstream provider failure