Chat Completions — Hypery Docs

Overview

The Chat Completions API is OpenAI-compatible, allowing you to use the official OpenAI SDK while accessing models from multiple providers including Anthropic, OpenAI, Google, Meta, and more.

Authentication: API Key or OAuth token
Required Scopes (OAuth): ai:chat or ai:completions

Quick Start

Get started in under a minute with the OpenAI SDK:

import OpenAI from 'openai'
 
const client = new OpenAI({
  apiKey: process.env.GATEWAY_API_KEY,
  baseURL: 'https://hypery.ai/api/v1'
})
 
const response = await client.chat.completions.create({
  model: 'anthropic/claude-3.5-sonnet',
  messages: [
    { role: 'user', content: 'Explain quantum computing' }
  ]
})
 
console.log(response.choices[0].message.content)

from openai import OpenAI
 
client = OpenAI(
    api_key="your-gateway-api-key",
    base_url="https://hypery.ai/api/v1"
)
 
response = client.chat.completions.create(
    model="anthropic/claude-3.5-sonnet",
    messages=[
        {"role": "user", "content": "Explain quantum computing"}
    ]
)
 
print(response.choices[0].message.content)

curl https://hypery.ai/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3.5-sonnet",
    "messages": [
      {"role": "user", "content": "Explain quantum computing"}
    ]
  }'

Create Chat Completion

Generate a model response for a conversation.

Endpoint: POST /api/v1/chat/completions

const response = await client.chat.completions.create({
  model: 'anthropic/claude-3.5-sonnet',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is the capital of France?' }
  ],
  max_tokens: 100,
  temperature: 0.7
})
 
console.log(response.choices[0].message.content)

response = client.chat.completions.create(
    model="anthropic/claude-3.5-sonnet",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"}
    ],
    max_tokens=100,
    temperature=0.7
)
 
print(response.choices[0].message.content)

curl https://hypery.ai/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3.5-sonnet",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "max_tokens": 100,
    "temperature": 0.7
  }'

Request Parameters

Parameter	Type	Required	Description
`model`	string	Yes	Model ID (e.g., `anthropic/claude-3.5-sonnet`)
`messages`	array	Yes	Array of message objects with `role` and `content`
`max_tokens`	number	No	Maximum tokens to generate (default varies by model)
`temperature`	number	No	Sampling temperature 0-2 (default: 0.7)
`top_p`	number	No	Nucleus sampling 0-1 (default: 1)
`stream`	boolean	No	Enable streaming responses (default: false)
`stop`	string \| array	No	Stop sequences
`frequency_penalty`	number	No	-2 to 2, penalize repeated tokens (default: 0)
`presence_penalty`	number	No	-2 to 2, penalize new topics (default: 0)
`tools`	array	No	Available functions for tool calling
`tool_choice`	string \| object	No	Control tool selection (`auto`, `required`, `none`)
`provider`	string	No	Specify provider (`openrouter`, `replicate`, `huggingface`)

Message Roles

Role	Description
`system`	Instructions for the model's behavior
`user`	User messages and prompts
`assistant`	Model responses (for conversation history)
`tool`	Tool/function execution results

Response:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699564800,
  "model": "anthropic/claude-3.5-sonnet",
  "provider": "openrouter",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}

Response Fields

Field	Type	Description
`id`	string	Unique completion ID
`object`	string	Object type (`chat.completion`)
`created`	number	Unix timestamp
`model`	string	Model used for completion
`provider`	string	Provider that served the request
`choices`	array	Array of completion choices
`usage`	object	Token usage statistics

Model Selection

Choose from 200+ models across multiple providers.

Model ID Format

Models use the format: organization/model-name

anthropic/claude-3.5-sonnet
openai/gpt-4o
google/gemini-pro
meta-llama/llama-3-70b

The first part is the model creator/organization, NOT the provider. The provider (which API hosts it) is separate.

Popular Models

Model ID	Context	Best For
`anthropic/claude-3.5-sonnet`	200K	Coding, analysis, long documents
`openai/gpt-4o`	128K	General purpose, vision
`openai/gpt-4o-mini`	128K	Fast, cost-effective tasks
`google/gemini-pro`	32K	Quick responses
`meta-llama/llama-3-70b`	8K	Open source

View all models →

Error Handling

Common Error Responses

Insufficient Credits

{
  "error": {
    "message": "Insufficient credits. Required: 0.05, Available: 0.00",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

Status Code: 429

Spending Limit Exceeded

{
  "error": {
    "message": "Team spending limit exceeded",
    "type": "spending_limit_exceeded",
    "code": "spending_limit_exceeded"
  }
}

Status Code: 402

Invalid Model

{
  "error": {
    "message": "Model not found: invalid/model",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Status Code: 400

Authentication Error

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Status Code: 401

Error Handling Example

try {
  const response = await client.chat.completions.create({
    model: 'anthropic/claude-3.5-sonnet',
    messages: [{ role: 'user', content: 'Hello' }]
  })
} catch (error) {
  if (error.status === 429) {
    console.error('Insufficient credits:', error.message)
  } else if (error.status === 402) {
    console.error('Spending limit exceeded:', error.message)
  } else {
    console.error('API error:', error)
  }
}

Advanced Features

Provider Routing

Control which sub-providers OpenRouter uses for optimal cost and performance:

const response = await client.chat.completions.create({
  model: 'anthropic/claude-3.5-sonnet',
  messages: [{ role: 'user', content: 'Hello' }],
  providerRouting: {
    sort: 'price',              // Sort by price, throughput, or latency
    allow_fallbacks: true,      // Enable automatic failover
    max_price: {
      prompt: 0.000001,         // Max per prompt token
      completion: 0.000003      // Max per completion token
    }
  }
})

Context Management

The gateway automatically optimizes conversation context:

Truncates messages based on team/app limits
Preserves system messages
Prioritizes recent messages
Configurable via dashboard

Prompt Caching

Supported models automatically cache repeated prompts to reduce costs by up to 90%:

const response = await client.chat.completions.create({
  model: 'anthropic/claude-3.5-sonnet',
  messages: [
    { 
      role: 'system', 
      content: longSystemPrompt  // Cached automatically
    },
    { role: 'user', content: 'Quick question' }
  ]
})

Best Practices

Set Appropriate Limits

const response = await client.chat.completions.create({
  model: 'anthropic/claude-3.5-sonnet',
  messages: [{ role: 'user', content: 'Summarize this document' }],
  max_tokens: 500,         // Limit response length
  temperature: 0.7,        // Control randomness
  stop: ['\n\n', 'END']   // Define stop sequences
})

Use System Messages

const response = await client.chat.completions.create({
  model: 'anthropic/claude-3.5-sonnet',
  messages: [
    { 
      role: 'system', 
      content: 'You are a technical documentation expert. Be concise and accurate.'
    },
    { role: 'user', content: 'Explain REST APIs' }
  ]
})

Monitor Token Usage

const response = await client.chat.completions.create({
  model: 'anthropic/claude-3.5-sonnet',
  messages: [{ role: 'user', content: 'Hello' }]
})
 
console.log('Tokens used:', response.usage.total_tokens)
console.log('Cost estimate:', response.usage.total_tokens * 0.000015)

Next Steps

Streaming

Stream responses in real-time for better UX

Function Calling

Build AI agents with tool use

Vision

Analyze images with multi-modal models

Models

Browse all available models