Vercel AI SDK — Hypery Docs

Overview

The Vercel AI SDK includes an Hypery feature that routes requests to multiple providers. Hypery Hub can replace Vercel's Hypery and provide the same functionality with additional features.

Vercel's Hypery: https://hypery.vercel.sh/v1/ai
Hypery Hub: https://hypery.ai/v1/ai (or use OpenAI-compatible endpoint)

Installation

Install the Vercel AI SDK (v5.0.36+ or v6):

npm install ai

createGateway is available in AI SDK v5.0.36+ and v6. If using v5, ensure you have at least version 5.0.36.

Option 1: Replace Vercel's Gateway (Recommended)

Use Hypery Hub as a drop-in replacement for Vercel's Gateway. Hypery serves the Vercel AI Gateway protocol at /v1/ai/* (/config, /language-model, /embedding-model, /image-model, …) and transparently proxies to the upstream gateway while attaching your billing.

Configuration

import { createGateway } from 'ai'
 
const gateway = createGateway({
  apiKey: process.env.GATEWAY_API_KEY,   // your Hypery OAuth token or API key (ak_…)
  baseURL: 'https://hypery.ai/v1/ai'      // Replace Vercel's gateway
})

Billing: the /v1/ai protocol path is served in vag_passthrough billing mode (the default) — usage is metered to your team's Stripe customer directly. If your app is on the credit-ledger modes (metered/prepaid), use the OpenAI-compatible /api/v1 endpoint (Option 2) instead; the raw gateway protocol path returns 400 UNSUPPORTED_BILLING_MODE there. Requests fail closed with 402 if the team has no Stripe customer on file.

Usage

Use the exact same model ID format as Vercel's gateway:

import { generateText } from 'ai'
 
const { text } = await generateText({
  model: gateway('anthropic/claude-3.5-sonnet'),
  prompt: 'Explain quantum computing'
})

The model ID format creator/model-name works with both Vercel's gateway and Hypery Hub. No code changes needed when switching!

Option 2: Use OpenAI Provider

Alternatively, use the OpenAI provider with our OpenAI-compatible endpoint:

import { createOpenAI } from '@ai-sdk/openai'
 
const aiGateway = createOpenAI({
  apiKey: process.env.GATEWAY_API_KEY,
  baseURL: 'https://hypery.ai/api/v1'
})

Difference:

Gateway endpoint (/v1/ai) - Uses Vercel's model ID format, supports provider routing
OpenAI endpoint (/api/v1) - Standard OpenAI-compatible format

Text Generation

Use any model through Hypery:

import { generateText } from 'ai'
import { createOpenAI } from '@ai-sdk/openai'
 
const aiGateway = createOpenAI({
  apiKey: process.env.GATEWAY_API_KEY!,
  baseURL: 'https://hypery.ai/api/v1'
})
 
const { text } = await generateText({
  model: aiGateway('anthropic/claude-3.5-sonnet'),
  prompt: 'Explain quantum computing in simple terms'
})
 
console.log(text)

Streaming

Stream responses in real-time:

import { streamText } from 'ai'
 
const result = streamText({
  model: aiGateway('openai/gpt-4o'),
  prompt: 'Write a poem about code'
})
 
for await (const chunk of result.textStream) {
  process.stdout.write(chunk)
}

React Server Components

Use in Next.js Server Components:

import { generateText } from 'ai'
import { createOpenAI } from '@ai-sdk/openai'
 
const aiGateway = createOpenAI({
  apiKey: process.env.GATEWAY_API_KEY!,
  baseURL: 'https://hypery.ai/api/v1'
})
 
export default async function Page() {
  const { text } = await generateText({
    model: aiGateway('anthropic/claude-3.5-sonnet'),
    prompt: 'Explain React Server Components'
  })
  
  return <div>{text}</div>
}

Chat UI Hook

Build chat interfaces with useChat:

'use client'
 
import { useChat } from 'ai/react'
 
export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: '/api/chat'  // Your Next.js API route
  })
  
  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          <strong>{m.role}:</strong> {m.content}
        </div>
      ))}
      
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
        <button type="submit">Send</button>
      </form>
    </div>
  )
}

API Route Handler

Create the API route for the chat UI:

// app/api/chat/route.ts
import { createOpenAI } from '@ai-sdk/openai'
import { streamText } from 'ai'
 
const aiGateway = createOpenAI({
  apiKey: process.env.GATEWAY_API_KEY!,
  baseURL: 'https://hypery.ai/api/v1'
})
 
export async function POST(req: Request) {
  const { messages } = await req.json()
  
  const result = streamText({
    model: aiGateway('anthropic/claude-3.5-sonnet'),
    messages
  })
  
  return result.toDataStreamResponse()
}

Tool Calling

Use function calling with the AI SDK:

import { generateText, tool } from 'ai'
import { z } from 'zod'
 
const { text } = await generateText({
  model: aiGateway('anthropic/claude-3.5-sonnet'),
  prompt: 'What is the weather in San Francisco?',
  tools: {
    getWeather: tool({
      description: 'Get current weather for a location',
      parameters: z.object({
        location: z.string().describe('City name')
      }),
      execute: async ({ location }) => {
        // Your weather API call
        return { temp: 72, condition: 'Sunny' }
      }
    })
  }
})

Model IDs

Both Vercel's gateway and Hypery Hub use the same model ID format:

// Format: creator/model-name (same as Vercel)
gateway('anthropic/claude-3.5-sonnet')
gateway('openai/gpt-4o')
gateway('google/gemini-pro')
gateway('meta-llama/llama-3-70b')

This means you can switch from Vercel's Hypery to Hypery Hub without changing model IDs.

Environment Variables

Set in your .env file or Vercel project settings:

# Hypery Hub
GATEWAY_API_KEY=your-gateway-api-key
 
# Optional: Override default gateway URL
AI_GATEWAY_BASE_URL=https://hypery.ai/v1/ai

Then use in code:

import { createGateway } from 'ai'
 
const gateway = createGateway({
  apiKey: process.env.GATEWAY_API_KEY,
  baseURL: process.env.AI_GATEWAY_BASE_URL
})

Vercel Hypery vs Hypery Hub

Feature	Vercel Hypery	Hypery Hub
Base URL	`hypery.vercel.sh/v1/ai`	`hypery.ai/v1/ai`
Model Format	`creator/model-name`	`creator/model-name` (same!)
Billing	Through Vercel	Your own credits
Models	Vercel-supported only	2000+ models
Team Management	Via Vercel teams	Full OAuth + Management APIs
Custom Admin	No	Yes
Self-hosted	No	Yes

Migration

To switch from Vercel's Hypery to Hypery Hub:

Change baseURL from https://hypery.vercel.sh/v1/ai to https://hypery.ai/v1/ai
Update API key to your Hypery Hub key
That's it! - Model IDs and code stay the same

Next Steps

Chat API

Learn about available models and features

Models

Browse all available models

Authentication

Set up API keys or OAuth