Vercel AI Gateway

하나의 API 키와 URL을 사용하면서도 요청마다 제공업체를 선택할 수 있습니다. Vercel AI Gateway는 여러 모델 제공업체 앞에 위치합니다. 이 패키지는 해당 공개 OpenAI 호환 API와 통신합니다.

@tanstack/ai-vercel-gateway를 설치합니다. 그런 다음 vercelGatewayText, vercelGatewayEmbedding 또는 vercelGatewayImage를 호출합니다.

설치

npm install @tanstack/ai-vercel-gateway

인증

AI_GATEWAY_API_KEY를 설정합니다. 이 키가 설정되지 않으면 어댑터는 VERCEL_OIDC_TOKEN을 사용합니다.

export AI_GATEWAY_API_KEY="..."

create* 팩토리에 키를 전달할 수도 있습니다.

import { createVercelGatewayText } from "@tanstack/ai-vercel-gateway"

const adapter = createVercelGatewayText(
  "anthropic/claude-opus-5",
  process.env.AI_GATEWAY_API_KEY!,
)

채팅

기본 어댑터는 https://ai-gateway.vercel.sh/v1의 OpenAI Responses API를 사용합니다. 모델 ID는 creator/model 형식을 사용합니다.

서버. SSE를 통해 응답을 스트리밍하는 엔드포인트입니다.

import { chat, toServerSentEventsResponse } from "@tanstack/ai"
import { vercelGatewayText } from "@tanstack/ai-vercel-gateway"

export async function POST(request: Request) {
  const { messages } = await request.json()

  const stream = chat({
    adapter: vercelGatewayText("anthropic/claude-opus-5"),
    messages,
  })

  return toServerSentEventsResponse(stream)
}

클라이언트. 다른 모든 제공업체와 동일한 useChat 훅입니다.

import { useState } from "react"
import { fetchServerSentEvents, useChat } from "@tanstack/ai-react"

export function Chat() {
  const [input, setInput] = useState("")

  const { messages, sendMessage, isLoading } = useChat({
    connection: fetchServerSentEvents("/api/chat"),
  })

  return (
    <div>
      {messages.map((message) => (
        <div key={message.id}>
          <strong>{message.role}</strong>
          {message.parts.map((part, index) =>
            part.type === "text" ? <p key={index}>{part.content}</p> : null,
          )}
        </div>
      ))}

      <form
        onSubmit={(event) => {
          event.preventDefault()
          if (!input.trim() || isLoading) return
          sendMessage(input)
          setInput("")
        }}
      >
        <input value={input} onChange={(event) => setInput(event.target.value)} />
        <button type="submit" disabled={isLoading}>
          Send
        </button>
      </form>
    </div>
  )
}

채팅 완성

모델이 Chat Completions와 통신해야 할 때 { api: "chat" }를 전달합니다. 기본값은 Responses입니다.

import { chat } from "@tanstack/ai"
import { vercelGatewayText } from "@tanstack/ai-vercel-gateway"

const stream = chat({
  adapter: vercelGatewayText("openai/gpt-5.5", { api: "chat" }),
  messages: [{ role: "user", content: "Hello" }],
})

api: "responses"는 기본값과 같습니다. api: "chat-completions"는 api: "chat"과 같습니다.

Gateway 라우팅

Gateway 라우팅은 modelOptions.gateway에 지정합니다. 어댑터는 해당 필드를 providerOptions.gateway로 전송합니다. 요청 본문의 최상위 수준에 gateway를 넣지 않습니다.

import { chat } from "@tanstack/ai"
import { vercelGatewayText } from "@tanstack/ai-vercel-gateway"

const stream = chat({
  adapter: vercelGatewayText("anthropic/claude-opus-5"),
  messages: [{ role: "user", content: "Hello" }],
  modelOptions: {
    gateway: {
      order: ["anthropic", "openai"],
      only: ["anthropic"],
      sort: "cost",
      models: ["anthropic/claude-opus-5", "openai/gpt-5.5"],
      caching: "auto",
      disallowPromptTraining: true,
    },
  },
})

order는 시도할 제공업체 목록입니다. only는 실행할 수 있는 제공업체를 제한합니다. sort는 비용, 첫 토큰까지의 시간 또는 초당 토큰 수를 기준으로 선택합니다. models는 폴백 모델 목록입니다.

order와 only는 "anthropic"과 같은 카탈로그 제공업체 ID를 허용합니다. models는 카탈로그 채팅 모델 ID를 허용합니다. 각 채팅 모델에는 카탈로그에서 가져온 고유한 modelOptions 키와 입력 타입도 있습니다. 텍스트 전용 모델은 이미지 파트를 허용하지 않습니다. 카탈로그에 temperature가 없는 모델은 temperature를 허용하지 않습니다.

임베딩

import { embed } from "@tanstack/ai"
import { vercelGatewayEmbedding } from "@tanstack/ai-vercel-gateway"

const result = await embed({
  adapter: vercelGatewayEmbedding("openai/text-embedding-3-small"),
  input: "a red guitar",
})

console.log(result.embeddings[0]?.vector)

이미지

이미지 생성은 텍스트에서 이미지로 변환하는 방식만 지원합니다. 어댑터는 POST /v1/images/generations를 호출합니다. 이미지 편집은 아직 이 패키지에 포함되지 않습니다.

import { generateImage } from "@tanstack/ai"
import { vercelGatewayImage } from "@tanstack/ai-vercel-gateway"

const result = await generateImage({
  adapter: vercelGatewayImage("openai/gpt-image-1"),
  prompt: "a red guitar",
})

요약

import { summarize } from "@tanstack/ai"
import { vercelGatewaySummarize } from "@tanstack/ai-vercel-gateway"

const result = await summarize({
  adapter: vercelGatewaySummarize("anthropic/claude-opus-5"),
  text: "The Fender Stratocaster is a versatile electric guitar.",
  stream: false,
})

이 패키지에서 지원하지 않는 기능

이 패키지는 동영상을 생성하지 않습니다. 음성, 전사 또는 재순위 지정도 지원하지 않습니다. 해당 작업에는 전용 어댑터를 사용합니다.

카탈로그는 GET /v1/models에서 가져오는 폐쇄형 목록입니다. CI가 매일 이 목록을 업데이트합니다.