본문으로 건너뛰기

OpenAI

OpenAI 어댑터는 GPT-4o, GPT-5, 이미지 생성(DALL-E), 텍스트 음성 변환(TTS), 오디오 전사(Whisper)를 비롯한 OpenAI 모델에 접근할 수 있게 합니다.

OpenAI API를 지원하는 서드파티 제공자(DeepSeek, Moonshot/Kimi, Together, Fireworks, 로컬 LM Studio/vLLM 서버 등)를 사용하나요? 일반적인 openaiCompatible({ baseURL, apiKey, models }) 팩토리는 OpenAI-Compatible Adapter를 참고하세요.

설치​

npm install @tanstack/ai-openai

기본 사용법​

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";

const stream = chat({
  adapter: openaiText("gpt-5.2"),
  messages: [{ role: "user", content: "Hello!" }],
});

채팅 완성 API​

@tanstack/ai-openai는 서로 다른 OpenAI 엔드포인트를 호출하는 두 가지 텍스트 어댑터를 제공합니다. openaiText(기본값)는 Responses API(/v1/responses)를 호출합니다. openaiChatCompletions는 이전 Chat Completions API(/v1/chat/completions)를 호출합니다.

와이어 형식과 기능 요구 사항에 맞는 것을 선택하세요.

openaiText (응답)openaiChatCompletions (채팅 완성)
Endpoint/v1/responses/v1/chat/completions
Reasoning summaries예 — modelOptions.reasoning.summary: 'auto'를 설정하면 REASONING_* 이벤트를 통해 추론 텍스트가 표시됩니다아니요 — 추론 토큰은 계속 사용되지만 노출할 수 없습니다
Wire-format compatibilityOpenAI 전용이전의 사실상 업계 표준 형식(Grok, Groq, OpenRouter 및 여러 로컬 모델 서버)과 일치합니다
구조화된 출력 스트리밍text.format: { type: 'json_schema', strict: true } + stream: trueresponse_format: { type: 'json_schema', strict: true } + stream: true

추론 요약 스트리밍이나 OpenAI 전용 Responses 기능이 필요하면 openaiText를 사용하세요. Chat Completions 방식 제공자에서 마이그레이션하거나, 스택의 다른 Chat Completions 어댑터와 요청 생성 코드를 공유하거나, 더 검증된 와이어 형식을 원하면 openaiChatCompletions를 사용하세요.

import { chat } from "@tanstack/ai";
import { openaiChatCompletions } from "@tanstack/ai-openai";

const stream = chat({
  adapter: openaiChatCompletions("gpt-5.2"),
  messages: [{ role: "user", content: "Hello!" }],
});

명시적인 API 키를 사용하려면 다음과 같이 합니다.

import { chat } from "@tanstack/ai";
import { createOpenaiChatCompletions } from "@tanstack/ai-openai";

const adapter = createOpenaiChatCompletions("gpt-5.2", process.env.OPENAI_API_KEY!, {
  // organization, baseURL, headers — all optional
});

const stream = chat({
  adapter,
  messages: [{ role: "user", content: "Hello!" }],
});

두 어댑터 모두 stream: true를 포함해 Structured Outputs와 동일하게 작동하며 같은 modelOptions(temperature, top_p, max_tokens, stop 등)를 받습니다. 아래 추론 섹션은 openaiText에 적용됩니다. openaiChatCompletions는 modelOptions.reasoning.effort를 받지만 요약 텍스트를 스트리밍할 수 없습니다.

기본 사용법 - 사용자 지정 API 키​

import { chat } from "@tanstack/ai";
import { createOpenaiChat } from "@tanstack/ai-openai";

const adapter = createOpenaiChat("gpt-5.2", process.env.OPENAI_API_KEY!, {
  // ... your config options
});

const stream = chat({
  adapter,
  messages: [{ role: "user", content: "Hello!" }],
});

구성​

import { createOpenaiChat, type OpenAITextConfig } from "@tanstack/ai-openai";

const config: Omit<OpenAITextConfig, "apiKey"> = {
  organization: "org-...", // Optional
  baseURL: "https://api.openai.com/v1", // Optional, for custom endpoints
};

const adapter = createOpenaiChat("gpt-5.2", process.env.OPENAI_API_KEY!, config);

예시: Chat Completion​

import { chat, toServerSentEventsResponse } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";

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

  const stream = chat({
    adapter: openaiText("gpt-5.2"),
    messages,
  });

  return toServerSentEventsResponse(stream);
}

예시: 도구 사용​

import { chat, toServerSentEventsResponse, toolDefinition } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { z } from "zod";

const getWeatherDef = toolDefinition({
  name: "get_weather",
  description: "Get the current weather",
  inputSchema: z.object({
    location: z.string(),
  }),
});

const getWeather = getWeatherDef.server(async ({ location }) => {
  // Fetch weather data
  return { temperature: 72, conditions: "sunny" };
});

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

  const stream = chat({
    adapter: openaiText("gpt-5.2"),
    messages,
    tools: [getWeather],
  });

  return toServerSentEventsResponse(stream);
}

모델 옵션​

OpenAI는 다양한 제공자별 옵션을 지원합니다. 샘플링 매개변수인 temperature, top_p, max_output_tokens(Responses API의 토큰 제한 키)도 chat()의 루트 수준 prop이 아니라 여기에 지정합니다.

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";

const stream = chat({
  adapter: openaiText("gpt-5.2"),
  messages: [{ role: "user", content: "Hello!" }],
  modelOptions: {
    temperature: 0.7,
    max_output_tokens: 1000,
    top_p: 0.9,
  },
});

openaiChatCompletions 어댑터는 /v1/chat/completions을 대상으로 하며, 여기서 토큰 제한 키는 max_tokens입니다(max_output_tokens 아님). 이전에 temperature / topP / maxTokens을 chat() 루트에 전달했다면, 샘플링 옵션을 modelOptions로 이동하기를 참조하세요.

추론​

이를 지원하는 모델(예: GPT-5, O3)에서 추론을 활성화하세요. 그러면 모델이 추론 과정을 표시하며, 이 과정은 thinking 청크로 스트리밍됩니다.

modelOptions: {
  reasoning: {
    effort: "medium", // "none" | "minimal" | "low" | "medium" | "high"
    summary: "detailed", // "auto" | "detailed" (optional)
  },
}

추론을 활성화하면 모델의 추론 과정이 응답 텍스트와 별도로 스트리밍되고 UI에 접을 수 있는 thinking 섹션으로 표시됩니다.

요약​

긴 텍스트 콘텐츠를 요약합니다.

import { summarize } from "@tanstack/ai";
import { openaiSummarize } from "@tanstack/ai-openai";

const result = await summarize({
  adapter: openaiSummarize("gpt-5-mini"),
  text: "Your long text to summarize...",
  maxLength: 100,
  style: "concise", // "concise" | "bullet-points" | "paragraph"
});

console.log(result.summary);

임베딩​

text-embedding-3 모델로 임베딩 벡터를 생성합니다.

import { embed } from "@tanstack/ai";
import { openaiEmbedding } from "@tanstack/ai-openai";

const result = await embed({
  adapter: openaiEmbedding("text-embedding-3-small"),
  input: ["a red guitar", "a blue drum kit"],
});

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

두 모델 모두 최상위 dimensions 옵션을 통한 Matryoshka 차원 축소를 지원합니다.

import { embed } from "@tanstack/ai";
import { openaiEmbedding } from "@tanstack/ai-openai";

const result = await embed({
  adapter: openaiEmbedding("text-embedding-3-large"),
  input: "a red guitar",
  dimensions: 1024,
});

전체 API는 Embeddings guide를 참고하세요.

이미지 생성​

이미지를 생성합니다.

import { generateImage } from "@tanstack/ai";
import { openaiImage } from "@tanstack/ai-openai";

const result = await generateImage({
  adapter: openaiImage("gpt-image-2"),
  prompt: "A futuristic cityscape at sunset",
  numberOfImages: 1,
  size: "1024x1024",
});

console.log(result.images);

이미지 모델 옵션​

import { generateImage } from "@tanstack/ai";
import { openaiImage } from "@tanstack/ai-openai";

const result = await generateImage({
  adapter: openaiImage("gpt-image-2"),
  prompt: "...",
  modelOptions: {
    quality: "high", // "high" | "medium" | "low" | "auto"
  },
});

텍스트 음성 변환​

텍스트에서 음성을 생성합니다.

import { generateSpeech } from "@tanstack/ai";
import { openaiSpeech } from "@tanstack/ai-openai";

const result = await generateSpeech({
  adapter: openaiSpeech("tts-1"),
  text: "Hello, welcome to TanStack AI!",
  voice: "alloy",
  format: "mp3",
});

// result.audio contains base64-encoded audio
console.log(result.format); // "mp3"

TTS 음성​

사용 가능한 음성: alloy, echo, fable, onyx, nova, shimmer, ash, ballad, coral, sage, verse

TTS 모델 옵션​

import { generateSpeech } from "@tanstack/ai";
import { openaiSpeech } from "@tanstack/ai-openai";

const result = await generateSpeech({
  adapter: openaiSpeech("tts-1-hd"),
  text: "High quality speech",
  modelOptions: {
    instructions: "Speak slowly and clearly.", // voice instructions (not supported by tts-1/tts-1-hd)
  },
});

전사​

오디오를 텍스트로 전사합니다.

import { generateTranscription } from "@tanstack/ai";
import { openaiTranscription } from "@tanstack/ai-openai";
import { audioFile } from "./audio";

const result = await generateTranscription({
  adapter: openaiTranscription("whisper-1"),
  audio: audioFile, // File object or base64 string
  language: "en",
});

console.log(result.text); // Transcribed text

전사 모델 옵션​

import { generateTranscription } from "@tanstack/ai";
import { openaiTranscription } from "@tanstack/ai-openai";
import { audioFile } from "./audio";

const result = await generateTranscription({
  adapter: openaiTranscription("whisper-1"),
  audio: audioFile,
  responseFormat: "verbose_json",
  prompt: "Technical terms: API, SDK",
  modelOptions: {
    temperature: 0,
    timestamp_granularities: ["word", "segment"],
  },
});

// Access the transcribed text
console.log(result.text);

화자 분리​

화자 레이블이 포함된 전사에는 gpt-4o-transcribe-diarize를 사용하세요.

import { generateTranscription } from "@tanstack/ai";
import { openaiTranscription } from "@tanstack/ai-openai";
import { meetingAudioFile } from "./audio";

const result = await generateTranscription({
  adapter: openaiTranscription("gpt-4o-transcribe-diarize"),
  audio: meetingAudioFile,
  modelOptions: {
    known_speaker_names: ["agent", "customer"],
    known_speaker_references: [
      "data:audio/wav;base64,...",
      "data:audio/wav;base64,...",
    ],
  },
});

for (const segment of result.segments ?? []) {
  console.log(segment.speaker, segment.start, segment.end, segment.text);
}

응답 형식을 지정하지 않으면 gpt-4o-transcribe-diarize 요청은 기본적으로 response_format: "diarized_json" 및 chunking_strategy: "auto"를 사용합니다. 최상위 responseFormat에 "json" 또는 "text"를 전달하면 화자 세그먼트를 사용하지 않습니다. known_speaker_names와 known_speaker_references는 함께 제공해야 하며(최대 4개, 길이가 일치해야 함), OpenAI는 화자 분리 전사에서 prompt, include, timestamp_granularities를 지원하지 않습니다.

환경 변수​

API 키를 환경 변수에 설정합니다.

OPENAI_API_KEY=sk-...

API 레퍼런스​

모든 팩토리 쌍은 같은 형태를 따릅니다. 짧은 팩토리(openaiText, openaiImage 등)는 환경 변수에서 OPENAI_API_KEY를 읽고, create* 변형은 명시적인 API 키를 받습니다. 두 방식 모두 첫 번째 인수로 model을 받습니다.

openaiText(model, config?)​

환경 변수의 OPENAI_API_KEY를 사용해 Responses API(/v1/responses)를 대상으로 하는 OpenAI 텍스트 어댑터를 생성합니다.

매개변수:

  • model - OpenAI 채팅 모델 ID(예: "gpt-5.2", "gpt-4o-mini")
  • config?.organization - 조직 ID(선택 사항)
  • config?.baseURL - 사용자 지정 기본 URL(선택 사항)

createOpenaiChat(model, apiKey, config?)​

명시적인 API 키로 OpenAI 텍스트 어댑터(Responses API)를 생성합니다.

openaiChatCompletions(model, config?)​

Responses API 대신 /v1/chat/completions를 대상으로 하는 OpenAI 텍스트 어댑터를 생성합니다. openaiText 대신 이를 사용해야 하는 경우는 Chat Completions API를 참고하세요.

createOpenaiChatCompletions(model, apiKey, config?)​

명시적인 API 키로 OpenAI chat-completions 어댑터를 생성합니다.

openaiSummarize(model, config?) / createOpenaiSummarize(model, apiKey, config?)​

OpenAI 요약 어댑터를 생성합니다.

openaiImage(model, config?) / createOpenaiImage(model, apiKey, config?)​

OpenAI 이미지 생성 어댑터(DALL-E, gpt-image)를 생성합니다.

openaiSpeech(model, config?) / createOpenaiSpeech(model, apiKey, config?)​

OpenAI 텍스트 음성 변환 어댑터를 생성합니다.

openaiTranscription(model, config?) / createOpenaiTranscription(model, apiKey, config?)​

Whisper, GPT-4o 전사 및 GPT-4o 화자 분리 전사 모델용 OpenAI 전사 어댑터를 생성합니다.

openaiVideo(model, config?) / createOpenaiVideo(model, apiKey, config?)​

OpenAI 동영상 생성 어댑터(Sora)를 생성합니다. 실험적 기능입니다.

openaiRealtime(...) / openaiRealtimeToken(...)​

실시간 음성 어댑터입니다. 사용법은 Realtime Voice Chat을 참고하세요.

다음 단계​

제공자 도구​

OpenAI는 사용자가 정의한 함수 호출 외에도 여러 기본 도구를 제공합니다. @tanstack/ai-openai/tools에서 가져와 chat({ tools: [...] }).

전체 개념, 비교 매트릭스 및 타입 제한 세부 사항은 Provider Tools.

webSearchTool​

모델이 웹 검색을 실행하고 인용이 포함된 근거 기반 결과를 반환할 수 있게 합니다. 도구를 구성하려면 OpenAI SDK에서 타입이 지정된 WebSearchToolConfig 객체를 전달하세요.

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { webSearchTool } from "@tanstack/ai-openai/tools";

const stream = chat({
  adapter: openaiText("gpt-5.2"),
  messages: [{ role: "user", content: "What's new in AI this week?" }],
  tools: [webSearchTool({ type: "web_search" })],
});

지원 모델: GPT-4o, GPT-5 및 Responses API를 지원하는 모델입니다. Provider Tools를 참고하세요.

webSearchPreviewTool​

검색 컨텍스트 크기와 사용자 위치를 제어하는 추가 옵션을 제공하는 웹 검색 미리보기 변형입니다. 모델에 전송하는 검색 컨텍스트를 세밀하게 제어하려면 사용하세요.

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { webSearchPreviewTool } from "@tanstack/ai-openai/tools";

const stream = chat({
  adapter: openaiText("gpt-5.2"),
  messages: [{ role: "user", content: "Latest news about TypeScript" }],
  tools: [
    webSearchPreviewTool({
      type: "web_search_preview_2025_03_11",
      search_context_size: "high",
    }),
  ],
});

지원 모델: GPT-4o 이상입니다. Provider Tools를 참고하세요.

fileSearchTool​

미리 채워 둔 OpenAI 벡터 저장소를 검색하여 모델이 관련 문서 청크를 가져올 수 있게 합니다. 검색할 vector_store_ids를 제공하고, 선택적으로 max_num_results(1–50)로 결과 수를 제한하세요.

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { fileSearchTool } from "@tanstack/ai-openai/tools";

const stream = chat({
  adapter: openaiText("gpt-5.2"),
  messages: [{ role: "user", content: "What does the handbook say about PTO?" }],
  tools: [
    fileSearchTool({
      type: "file_search",
      vector_store_ids: ["vs_abc123"],
      max_num_results: 5,
    }),
  ],
});

지원 모델: GPT-4o 이상입니다. Provider Tools를 참고하세요.

imageGenerationTool​

모델이 대화 중에 DALL-E/GPT-Image를 사용해 인라인으로 이미지를 생성할 수 있게 합니다. config 객체를 통해 품질, 크기 및 스타일 옵션을 전달하세요.

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { imageGenerationTool } from "@tanstack/ai-openai/tools";

const stream = chat({
  adapter: openaiText("gpt-5.2"),
  messages: [{ role: "user", content: "Draw a logo for my app" }],
  tools: [
    imageGenerationTool({
      quality: "high",
      size: "1024x1024",
    }),
  ],
});

지원 모델: GPT-5 및 GPT-Image를 지원하는 모델입니다. Provider Tools를 참고하세요.

codeInterpreterTool​

모델에 샌드박스 처리된 Python 실행 환경을 제공합니다. container 필드로 실행 환경을 구성하며, 전체 CodeInterpreterToolConfig 객체를 전달하세요.

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { codeInterpreterTool } from "@tanstack/ai-openai/tools";

const stream = chat({
  adapter: openaiText("gpt-5.2"),
  messages: [{ role: "user", content: "Analyse this CSV and plot a chart" }],
  tools: [
    codeInterpreterTool({ type: "code_interpreter", container: { type: "auto" } }),
  ],
});

지원 모델: GPT-4o 이상입니다. Provider Tools를 참고하세요.

mcpTool​

모델을 원격 MCP(Model Context Protocol) 서버에 연결하여 모든 기능을 호출 가능한 도구로 노출합니다. server_url 또는 connector_id 중 하나만 제공하세요.

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { mcpTool } from "@tanstack/ai-openai/tools";

const stream = chat({
  adapter: openaiText("gpt-5.2"),
  messages: [{ role: "user", content: "List my GitHub issues" }],
  tools: [
    mcpTool({
      server_url: "https://mcp.example.com",
      server_label: "github",
    }),
  ],
});

지원 모델: GPT-4o 이상입니다. Provider Tools를 참고하세요.

computerUseTool​

모델이 스크린샷으로 가상 데스크톱을 관찰하고 키보드 및 마우스 이벤트로 상호작용할 수 있게 합니다. 디스플레이 크기와 실행 환경 유형을 제공하세요.

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { computerUseTool } from "@tanstack/ai-openai/tools";

const stream = chat({
  adapter: openaiText("computer-use-preview"),
  messages: [{ role: "user", content: "Open Chrome and navigate to example.com" }],
  tools: [
    computerUseTool({
      type: "computer_use_preview",
      display_width: 1024,
      display_height: 768,
      environment: "browser",
    }),
  ],
});

지원 모델: computer-use-preview입니다. Provider Tools를 참고하세요.

localShellTool​

모델에 시스템 명령을 실행할 수 있는 로컬 셸을 제공합니다. 인수를 받지 않으며 tools 배열에 포함하는 것만으로 활성화됩니다.

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { localShellTool } from "@tanstack/ai-openai/tools";

const stream = chat({
  adapter: openaiText("gpt-5.2"),
  messages: [{ role: "user", content: "Run the test suite and summarise failures" }],
  tools: [localShellTool()],
});

지원 모델: GPT-5.x 및 다른 에이전트 지원 모델입니다. Provider Tools를 참고하세요.

shellTool​

셸 실행을 구조화된 함수 호출로 노출하는 함수 방식 셸 도구입니다. 컨테이너 구성과 호스팅된 스킬을 연결하려면 environment 객체를 전달하세요.

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { shellTool } from "@tanstack/ai-openai/tools";

const stream = chat({
  adapter: openaiText("gpt-5.2"),
  messages: [{ role: "user", content: "Count lines in all JS files" }],
  tools: [shellTool()],
});

지원 모델: GPT-5.x 및 다른 에이전트 지원 모델입니다. Responses API 전용이며 Chat Completions는 셸 도구를 지원하지 않습니다. Provider Tools를 참고하세요.

호스팅된 스킬 연결​

제공자가 관리하는 스킬 번들을 셸 컨테이너에 로드하려면 environment.skills를 전달하세요(Responses API 전용).

import { chat, toServerSentEventsResponse } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { shellTool } from "@tanstack/ai-openai/tools";

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

  const stream = chat({
    adapter: openaiText("gpt-5.2"),
    messages,
    tools: [
      shellTool({
        environment: {
          type: "container_auto",
          skills: [
            { type: "skill_reference", skill_id: "skill_abc", version: "2" },
          ],
        },
      }),
    ],
  });

  return toServerSentEventsResponse(stream);
}

전체 레퍼런스(스킬 형식, version 문자열 형식 및 Anthropic 대응 기능)는 Provider Skills를 참고하세요.

applyPatchTool​

모델이 unified-diff 패치를 적용하여 파일을 직접 수정할 수 있게 합니다. 인수를 받지 않으며 패치 적용을 활성화하려면 tools 배열에 포함하세요.

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { applyPatchTool } from "@tanstack/ai-openai/tools";

const stream = chat({
  adapter: openaiText("gpt-5.2"),
  messages: [{ role: "user", content: "Fix the import paths in src/index.ts" }],
  tools: [applyPatchTool()],
});

지원 모델: GPT-5.x 및 다른 에이전트 지원 모델입니다. Provider Tools를 참고하세요.

customTool​

명시적인 이름, 설명 및 형식을 사용하는 사용자 지정 Responses API 도구를 정의합니다. 구조화된 도구 유형 중 사용 사례에 맞는 것이 없을 때 사용하세요. 브랜드가 있는 제공자 도구와 달리 customTool은 일반 Tool을 반환하며 모든 채팅 모델에서 사용할 수 있습니다.

import { chat } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";
import { customTool } from "@tanstack/ai-openai/tools";

const stream = chat({
  adapter: openaiText("gpt-5.2"),
  messages: [{ role: "user", content: "Look up order #1234" }],
  tools: [
    customTool({
      type: "custom",
      name: "lookup_order",
      description: "Look up the status of a customer order by order ID",
    }),
  ],
});

지원 모델: 모든 Responses API 모델입니다. Provider Tools를 참고하세요.