API 형식

OpenAI Chat Completions, Anthropic Messages, 또는 OpenAI Responses 요청을 사용해 LLM Gateway를 통해 프로바이더 전반의 모델을 호출하는 방법을 알려드릴게요.

참고: LLM Gateway는 베타 상태입니다.

표준 LLM Gateway API는 세 가지 요청·응답 형식을 지원합니다. 애플리케이션이 이미 사용하는 형식을 선택한 뒤 동일한 엔드포인트로 자체 키(bring-your-own-key) 또는 Gateway Credits 모델을 호출하세요.

출처: 문서

본문

API 형식 비교

API format	Base URL	Prompt endpoint	Compatible client
OpenAI Chat Completions	`https://gateway.smith.langchain.com/v1`	`POST /chat/completions`	OpenAI-compatible Chat Completions clients
Anthropic Messages	`https://gateway.smith.langchain.com`	`POST /v1/messages`	Anthropic Messages clients
OpenAI Responses	`https://gateway.smith.langchain.com/v1`	`POST /responses`	OpenAI-compatible Responses clients

모든 형식은 워크스페이스 범위 LangSmith API 키로 인증합니다. 프로바이더 API 키로 또는 Authorization: Bearer 토큰으로 전달하세요.

이 기본 URL은 LangSmith Cloud의 US 게이트웨이용입니다. 다른 리전과 BYOC 데이터 플레인은 가용성 확인을 참고하세요.

자체 키 모델의 경우 model을 <provider>/<model>로 설정합니다. 예: openai/gpt-5.4-mini, anthropic/claude-opus-5, azure/<deployment-name>. Gateway Credits 모델의 경우 moonshotai/kimi-k3 같은 지원 모델 이름을 전달합니다.

Chat Completions 사용

OpenAI 호환 클라이언트를 https://gateway.smith.langchain.com/v1로 지정합니다. 전체 요청·응답 스키마는 OpenAI Chat Completions API를 참고하세요.

curl https://gateway.smith.langchain.com/v1/chat/completions \
    -H "Authorization: Bearer $LANGS..._KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"anthropic/claude-opus-5","messages":[{"role":"user","content":"Hello!"}]}'

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.smith.langchain.com/v1",
    api_key=os.environ["LANGSMITH_API_KEY"],
)
response = client.chat.completions.create(
    model="anthropic/claude-opus-5",
    messages=[{"role": "user", "content": "Hello!"}],
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.smith.langchain.com/v1",
  apiKey: proces...KEY,
});
const response = await client.chat.completions.create({
  model: "anthropic/claude-opus-5",
  messages: [{ role: "user", content: "Hello!" }],
});

Messages 사용

Anthropic 클라이언트를 https://gateway.smith.langchain.com으로 지정합니다. 전체 요청·응답 스키마는 Anthropic Messages API를 참고하세요.

curl https://gateway.smith.langchain.com/v1/messages \
    -H "Authorization: Bearer $LANGS..._KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"openai/gpt-5.4-mini","max_tokens":1024,"messages":[{"role":"user","content":"Hello!"}]}'

import os

import anthropic

client = anthropic.Anthropic(
    base_url="https://gateway.smith.langchain.com",
    api_key=os.environ["LANGSMITH_API_KEY"],
)
message = client.messages.create(
    model="openai/gpt-5.4-mini",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://gateway.smith.langchain.com",
  apiKey: proces...KEY,
});
const message = await client.messages.create({
  model: "openai/gpt-5.4-mini",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }],
});

Responses 사용

OpenAI 호환 클라이언트를 https://gateway.smith.langchain.com/v1로 지정합니다. 전체 요청·응답 스키마는 OpenAI Responses API를 참고하세요.

curl https://gateway.smith.langchain.com/v1/responses \
    -H "Authorization: Bearer $LANGS..._KEY" \
    -H "Content-Type: application/json" \
    -d '{"model":"anthropic/claude-opus-5","input":"Hello!"}'

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.smith.langchain.com/v1",
    api_key=os.environ["LANGSMITH_API_KEY"],
)
response = client.responses.create(
    model="anthropic/claude-opus-5",
    input="Hello!",
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.smith.langchain.com/v1",
  apiKey: proces...KEY,
});
const response = await client.responses.create({
  model: "anthropic/claude-opus-5",
  input: "Hello!",
});

프롬프트 캐싱 활성화

OpenAI 모델(Chat Completions 및 Responses)은 암시적 프롬프트 캐싱을 자동으로 지원하므로 추가 파라미터가 필요 없습니다.

Anthropic 모델과 일부 구형 OpenAI 모델은 프롬프트 캐싱에 명시적 옵트인이 필요합니다. 표준 게이트웨이 엔드포인트를 통해 이 모델을 호출할 때 요청 본문에 프로바이더별 필드를 전달하세요.

참고: 명시적 캐싱 지원은 게이트웨이 수준 캐싱 정책이 개발되는 동안의 임시 조치입니다. 다음 필드는 업스트림 프로바이더로 전달됩니다.

Anthropic 모델

ttl 값과 함께 prompt_cache_options를 포함합니다:

curl https://gateway.smith.langchain.com/v1/responses \
    -H "Authorization: Bearer $LANGS..._KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "anthropic/claude-opus-5",
      "input": "Hello!",
      "prompt_cache_options": {"ttl": "30m"}
    }'

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.smith.langchain.com/v1",
    api_key=os.environ["LANGSMITH_API_KEY"],
)
response = client.responses.create(
    model="anthropic/claude-opus-5",
    input="Hello!",
    extra_body={"prompt_cache_options": {"ttl": "30m"}},
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.smith.langchain.com/v1",
  apiKey: proces...KEY,
});
const response = await client.responses.create({
  model: "anthropic/claude-opus-5",
  input: "Hello!",
  // @ts-ignore — provider-specific field
  prompt_cache_options: { ttl: "30m" },
});

동일한 필드는 Chat Completions 엔드포인트에서도 동작합니다:

curl https://gateway.smith.langchain.com/v1/chat/completions \
    -H "Authorization: Bearer $LANGS..._KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "anthropic/claude-opus-5",
      "messages": [{"role": "user", "content": "Hello!"}],
      "prompt_cache_options": {"ttl": "30m"}
    }'

구형 OpenAI 모델

일부 구형 OpenAI 모델은 prompt_cache_retention을 통한 명시적 캐시 제어를 지원합니다. 대부분 모델에서는 "in_memory"로 설정하세요. 특히 gpt-5.5는 "24h"를 사용합니다:

curl https://gateway.smith.langchain.com/v1/responses \
    -H "Authorization: Bearer $LANGS..._KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.4-mini",
      "input": "Hello!",
      "prompt_cache_retention": "in_memory"
    }'

curl https://gateway.smith.langchain.com/v1/responses \
    -H "Authorization: Bearer $LANGS..._KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "input": "Hello!",
      "prompt_cache_retention": "24h"
    }'

전체 prompt_cache_retention 문서는 OpenAI prompt caching 가이드를 참고하세요.

변환 동작 이해하기

엔드포인트는 애플리케이션이 보내고 받는 형식을 결정합니다. 모델 ID는 업스트림 프로바이더를 결정합니다.

프로바이더가 선택한 형식을 네이티브로 지원하면 게이트웨이는 해당 형식을 보존합니다.
그렇지 않으면 게이트웨이는 요청을 프로바이더가 지원하는 형식으로 변환하고, 스트리밍 응답을 포함해 응답을 다시 변환합니다.
변환은 대상 프로바이더 형식에서 표현할 수 없는 필드를 거부할 수 있습니다. 프로바이더 네이티브 동작이 필요하면 직접 모델 접근을 사용하세요.

모든 요청은 형식과 무관하게 동일한 Provider Secrets, 정책, 트레이싱 구성을 해석합니다.

모델 목록

GET /v1/models를 호출해 워크스페이스용으로 구성된 프로바이더와 Gateway Credits에서 사용 가능한 모델을 나열합니다. 게이트웨이는 단일 OpenAI 호환 목록을 반환합니다:

curl https://gateway.smith.langchain.com/v1/models \
    -H "Authorization: Bearer $LANGS..._KEY"

{
  "object": "list",
  "data": [
    {"id": "openai/gpt-5.4-mini", "object": "model"},
    {"id": "fireworks/accounts/fireworks/models/glm-5p2", "object": "model"},
    {"id": "anthropic/claude-opus-5", "object": "model"},
    {"id": "moonshotai/kimi-k3", "object": "model"}
  ]
}

자체 키 모델 ID는 <provider>/<model> 형태를 사용합니다. 호스팅 모델은 응답에 표시된 슬러그를 사용합니다. 호출 시 표시된 그대로의 ID를 전달하세요. 구성된 시크릿이 없는 자체 키 프로바이더는 생략됩니다. 호스팅 모델은 프로바이더 시크릿이 필요 없습니다.

오류 처리

Status or symptom	Meaning
`400 Bad Request`	The request is malformed, the model ID is unavailable or incorrectly formatted, or the request cannot be translated.
`401 Unauthorized`	The LangSmith API key is missing or invalid.
`403 Forbidden`	The key does not have the required gateway permissions.
`429 Too Many Requests`	A gateway rate limit or an upstream provider rate limit was reached.
No models with a provider prefix appear in `GET /v1/models`	The provider may not be configured or may not have returned a model catalog.

설정별 해결 방법은 퀵스타트를 참고하세요.

함께 보기

퀵스타트: 첫 요청을 만들고 트레이스 보기.
게이트웨이 동작 방식: 각 요청에 일어나는 일과 각 리전·BYOC에서 사용할 호스트 이름.
직접 모델 접근: 형식 변환 우회, 프로바이더 네이티브 API 사용.
모델 폴백: 백업 모델로 요청 재시도.

더 알아보기

퀵스타트 — 첫 요청과 트레이스.
모델 폴백 — 백업 모델로 재시도.