본문으로 건너뛰기

Grok (xAI)

Grok 텍스트 및 요약 어댑터는 grok-4.3과 grok-build-0.1을 위한 xAI Responses API에 액세스하며, Grok Imagine 이미지 생성과 Grok Imagine 동영상 생성도 제공합니다.

설치​

npm install @tanstack/ai-grok

기본 사용법​

import { chat } from "@tanstack/ai";
import { grokText } from "@tanstack/ai-grok";

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

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

import { chat } from "@tanstack/ai";
import { createGrokText } from "@tanstack/ai-grok";

const adapter = createGrokText("grok-build-0.1", process.env.XAI_API_KEY!);

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

구성​

import { createGrokText, type GrokTextConfig } from "@tanstack/ai-grok";

const config: Omit<GrokTextConfig, "apiKey"> = {
  baseURL: "https://api.x.ai/v1", // Optional, this is the default
};

const adapter = createGrokText("grok-build-0.1", process.env.XAI_API_KEY!, config);

Vertex에서 Grok 사용​

Grok을 Vertex AI에서 실행해야 할 때는 @tanstack/ai-grok/vertex를 사용합니다. 이 경로는 Google Cloud 자격 증명과 Vertex 리전별 또는 글로벌 엔드포인트를 사용합니다.

npm install @tanstack/ai-grok google-auth-library
import { chat } from "@tanstack/ai";
import { grokVertexText } from "@tanstack/ai-grok/vertex";

const stream = chat({
  adapter: grokVertexText("grok-4.3", {
    project: "my-project",
    location: "global",
  }),
  messages: [{ role: "user", content: "Hello!" }],
});

project와 location은 @tanstack/ai-vertex와 동일한 이름을 사용합니다. location을 생략하면 팩토리는 global을 사용합니다.

grokVertexText는 Vertex에 나열된 Grok 채팅 모델만 허용합니다:

  • grok-4.3
  • grok-4.20-reasoning
  • grok-4.20-non-reasoning
  • grok-4.1-fast-reasoning
  • grok-4.1-fast-non-reasoning

grok-4.6 및 grok-build-0.1과 같은 xAI API 모델은 Vertex에 없습니다.

어댑터는 Vertex 모델 ID xai/grok-4.3을 전송합니다. Application Default Credentials를 사용하려면 google-auth-library를 설치하거나 authClient 또는 getAccessToken을 전달합니다.

Vertex에서 요약해야 할 때는 동일한 진입점의 grokVertexSummarize를 사용합니다.

Vertex의 Gemini는 @tanstack/ai-vertex에 있습니다.

예제: 채팅 완성​

import { chat, toServerSentEventsResponse } from "@tanstack/ai";
import { grokText } from "@tanstack/ai-grok";

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

  const stream = chat({
    adapter: grokText("grok-build-0.1"),
    messages,
  });

  return toServerSentEventsResponse(stream);
}

예제: 도구 사용​

import { chat, toServerSentEventsResponse, toolDefinition } from "@tanstack/ai";
import { grokText } from "@tanstack/ai-grok";
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: grokText("grok-build-0.1"),
    messages,
    tools: [getWeather],
  });

  return toServerSentEventsResponse(stream);
}

모델 옵션​

Grok은 xAI Responses API 옵션을 지원합니다. 샘플링 매개변수인 temperature, top_p, max_output_tokens도 chat()의 루트 수준 prop이 아니라 여기에 지정합니다:

import { chat, toServerSentEventsResponse } from "@tanstack/ai";
import { grokText } from "@tanstack/ai-grok";

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

  const stream = chat({
    adapter: grokText("grok-build-0.1"),
    messages,
    modelOptions: {
      temperature: 0.7,
      top_p: 0.9,
      max_output_tokens: 1024,
      store: false,
      include: ["reasoning.encrypted_content"],
    },
  });

  return toServerSentEventsResponse(stream);
}

이전에 chat()의 루트에 temperature / topP / maxTokens를 전달했다면 샘플링 옵션을 modelOptions로 이동을 참조하세요.

요약​

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

<!-- 무시됨: grokSummarize()의 확인된 provider-options 타입은 SummarizeAdapter에서 반공변 위치에 있으므로 현재 Grok 모델의 summarize() adapter 매개변수에 할당할 수 없습니다. #821에서 추적 중이며, adapter 타입이 수정되면 무시를 해제합니다. -->

import { summarize } from "@tanstack/ai";
import { grokSummarize } from "@tanstack/ai-grok";

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

console.log(result.summary);

이미지 생성​

Grok 2 Image로 이미지를 생성합니다:

import { generateImage } from "@tanstack/ai";
import { grokImage } from "@tanstack/ai-grok";

const result = await generateImage({
  adapter: grokImage("grok-2-image-1212"),
  prompt: "A futuristic cityscape at sunset",
  numberOfImages: 1,
});

console.log(result.images);

grok-imagine 모델(grok-imagine-image, grok-imagine-image-2.0, grok-imagine-image-quality)은 화면 비율 기반 크기를 사용합니다. size에는 "16:9_2k"와 같은 aspectRatio_resolution 템플릿을 지정합니다(_2k 접미사는 선택 사항). grok-imagine-image-2.0은 xAI가 권장하는 모델이며, 2.0 전용 quality provider 옵션('low' | 'medium', 기본값 'medium')을 추가합니다:

import { generateImage } from "@tanstack/ai";
import { grokImage } from "@tanstack/ai-grok";

const result = await generateImage({
  adapter: grokImage("grok-imagine-image-2.0"),
  prompt: "A futuristic cityscape at sunset",
  size: "16:9_2k",
  modelOptions: { quality: "medium" },
});

이미지 편집 (image-to-image)​

grok-imagine 모델은 이미지 조건부 생성을 위한 이미지 프롬프트 부분을 허용합니다. xAI 의 /v1/images/edits 엔드포인트를 통한 생성 — 최대 3 개의 소스 이미지, 프롬프트에 나타나는 순서대로 xAI 가 처리합니다. xAI 의 문서에 따르면, 프롬프트 내부 참조 구문은 없으므로 프롬프트를 자연스럽게 작성합니다. 텍스트가 그대로 전송됩니다:

import { generateImage } from "@tanstack/ai";
import { grokImage } from "@tanstack/ai-grok";

const result = await generateImage({
  adapter: grokImage("grok-imagine-image"),
  prompt: [
    {
      type: "text",
      content: "Render the product in the style of the second image",
    },
    {
      type: "image",
      source: { type: "url", value: "https://example.com/product.png" },
    },
    {
      type: "image",
      source: { type: "url", value: "https://example.com/style.png" },
    },
  ],
});

URL 소스는 xAI 서버가 가져오므로 공개적으로 접근할 수 있어야 합니다. 비공개 이미지에는 data 소스를 사용합니다. grok-2-image-1212는 텍스트-이미지 변환만 지원합니다. 이미지 프롬프트 파트는 컴파일 시 타입 오류가 발생하고 런타임에는 예외를 던집니다.

동영상 생성 (실험적)​

xAI의 비동기 작업/폴링 API를 통해 Grok Imagine 동영상 모델로 짧은 동영상 클립(오디오 포함, 1~15초)을 생성합니다.

사용 가능한 모델:

  • grok-imagine-video (v1.0) — 텍스트-동영상, 이미지-동영상, 소스 동영상 편집/확장을 지원하며 동영상 1초당 $0.05입니다.
  • grok-imagine-video-1.5 — xAI가 권장하는 기본 모델이며 동영상 1초당 $0.08입니다. 텍스트-동영상(네이티브 1080p 포함), 이미지-동영상, reference-to-video를 지원하지만 소스 동영상은 허용하지 않습니다.

텍스트-동영상:

import { generateVideo, getVideoJobStatus } from "@tanstack/ai";
import { grokVideo } from "@tanstack/ai-grok";

const adapter = grokVideo("grok-imagine-video-1.5");

// 1. Create the job
const { jobId } = await generateVideo({
  adapter,
  prompt: "A red panda balancing on a bamboo stalk in the rain",
  size: "16:9_720p", // "aspectRatio" or "aspectRatio_resolution"
  duration: 5, // integer seconds, 1–15
});

// 2. Poll until complete, then read the video URL
let status = await getVideoJobStatus({ adapter, jobId });
while (status.status !== "completed" && status.status !== "failed") {
  await new Promise((r) => setTimeout(r, 5000));
  status = await getVideoJobStatus({ adapter, jobId });
}

console.log(status.url); // hosted .mp4 URL

이미지-비디오의 경우 image 프롬프트 부분을 시작 프레임으로 포함하고 텍스트 부분에서 원하는 동작을 설명합니다. URL 소스는 xAI 의 서버에서 가져오므로 (공식적으로 접근 가능해야 함) data 소스를 사용하여 base64 시작 프레임을 지정합니다:

import { generateVideo } from "@tanstack/ai";
import { grokVideo } from "@tanstack/ai-grok";

const { jobId } = await generateVideo({
  adapter: grokVideo("grok-imagine-video-1.5"),
  prompt: [
    {
      type: "text",
      content: "Make the waterfall crash down and slowly pan out the camera",
    },
    {
      type: "image",
      source: { type: "url", value: "https://example.com/waterfall-still.png" },
    },
  ],
  size: "16:9_720p",
  duration: 10,
});

Grok Imagine 이미지 모델과 마찬가지로 크기는 종횡비 기반입니다: size 옵션은 aspectRatio_resolution 템플릿을 사용합니다. 지원되는 종횡비는 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 및 2:3 이며 지원되는 해상도는 480p, 720p, 및 ( grok-imagine-video-1.5 텍스트-비디오 / 이미지-비디오 전용) 1080p (예: "9:16_1080p") 입니다. 해상도 접미사는 선택 사항입니다.

참조에서 비디오​

grok-imagine-video-1.5 에서 metadata.role: 'reference' (또는 'character') 를 가진 이미지 프롬프트 부분은 reference_images 으로 변환됩니다 — 첫 프레임을 고정하지 않고 주제와 스타일을 안내하며 <IMAGE_0>, <IMAGE_1>, … 요청 순서대로 프롬프트 텍스트에서 참조합니다. 생성된 음성을 위해 최대 3 개까지의 프리셋 TTS 음성을 modelOptions.reference_audios 를 통해 참조할 수 있으며 <AUDIO_0>, <AUDIO_1>, <AUDIO_2> 로 참조합니다. 참조-비디오 출력은 720p 로 제한됩니다. 시작 프레임 이미지와 참조 입력을 결합할 수 없습니다 — xAI 는 400 으로 해당 혼합을 거부합니다. 참조 입력은 1.5 전용 기능이며 어댑터는 grok-imagine-video 에서 이를 거부합니다:

import { generateVideo } from "@tanstack/ai";
import { grokVideo } from "@tanstack/ai-grok";

const { jobId } = await generateVideo({
  adapter: grokVideo("grok-imagine-video-1.5"),
  prompt: [
    {
      type: "text",
      content: "<IMAGE_0> walks through a neon-lit alley while <AUDIO_0> narrates",
    },
    {
      type: "image",
      source: { type: "url", value: "https://example.com/character.png" },
      metadata: { role: "reference" },
    },
  ],
  size: "16:9_720p",
  modelOptions: {
    reference_audios: [{ voice_id: "eve" }],
  },
});

동영상 편집 및 확장​

grok-imagine-video (v1.0)은 기존 클립을 다시 작성하거나 이어갈 수 있습니다. grok-imagine-video-1.5에는 동영상 입력이 없으므로 해당 모델에서 어댑터는 소스 동영상 부분이나 mode를 거부합니다. 소스 클립을 video 프롬프트 부분으로 전달하고 modelOptions.mode로 모드를 선택합니다:

  • mode: 'edit'는 /v1/videos/edits로 전송되어 프롬프트가 요청한 부분만 수정하고 나머지 클립은 유지합니다. 길이, 화면 비율, 해상도는 소스에서 상속되므로(720p로 제한) 이 모드에서는 API가 무시할 필드를 보내지 않고 어댑터가 size, aspect_ratio, resolution, duration을 거부합니다.
  • mode: 'extend'는 /v1/videos/extensions로 전송되어 클립을 이어갑니다. duration은 전체 길이가 아니라 추가되는 끝부분의 길이입니다. duration: 5로 10초 클립을 확장하면 15초가 됩니다. 출력 형상은 소스에서 상속되므로 여기서도 size / aspect_ratio / resolution이 거부됩니다.
import { generateVideo } from "@tanstack/ai";
import { grokVideo } from "@tanstack/ai-grok";

const adapter = grokVideo("grok-imagine-video");

// Edit: change the clip in place
const edit = await generateVideo({
  adapter,
  prompt: [
    { type: "text", content: "Make the sky stormy with distant lightning" },
    {
      type: "video",
      source: { type: "url", value: "https://example.com/clip.mp4" },
    },
  ],
  modelOptions: { mode: "edit" },
});

// Extend: append 5 more seconds
const extension = await generateVideo({
  adapter,
  prompt: [
    { type: "text", content: "The camera keeps panning right across the bay" },
    {
      type: "video",
      source: { type: "url", value: "https://example.com/clip.mp4" },
    },
  ],
  duration: 5, // added seconds, not the total
  modelOptions: { mode: "extend" },
});

둘 다 일반적인 { jobId } 을 반환하며, 다른 Grok 비디오 작업과 마찬가지로 폴링됩니다.

작업이 완료되면 어댑터가 결과에 대한 사용량을 보고합니다: usage.billed 은 { quantity, unit: 'seconds' } 의 비디오 청구 초수를, usage.cost 은 USD 단위의 정확한 비용을 담고 있으며, 둘 다 xAI API 가 반환한 값입니다.

Video Generation에 대한 전체 작업/轮询 흐름, 스트리밍 모드 및 useGenerateVideo 후크를 확인하세요.

텍스트 음성 변환​

Grok TTS로 음성을 생성합니다:

import { generateSpeech } from "@tanstack/ai";
import { grokSpeech } from "@tanstack/ai-grok";

const result = await generateSpeech({
  adapter: grokSpeech("grok-tts"),
  text: "Hello from Grok!",
  voice: "default",
  format: "mp3",
});

console.log(result.audio); // Base64-encoded audio

전사​

Grok STT로 오디오를 전사합니다:

import { generateTranscription } from "@tanstack/ai";
import { grokTranscription } from "@tanstack/ai-grok";
import { audioFile } from "./audio";

const result = await generateTranscription({
  adapter: grokTranscription("grok-stt"),
  audio: audioFile,
});

console.log(result.text);

실시간 음성​

Grok 또한 저지연 음성 대화에 대해 grokRealtime 실시간 음성 어댑터와 grokRealtimeToken 토큰 발급자를 노출합니다. 기본 모델은 grok-voice-think-fast-2.0 (xAI 의 현재 권장 음성-음성 모델)이며, grok-voice-latest 는 항상 최신 모델을 가리킵니다. 1.0 ID 는 호환성을 위해 계속 허용되지만, xAI 는 grok-voice-think-fast-1.0 를 더 이상 사용하지 않습니다. Realtime Voice Chat에 대한 엔드투엔드 흐름을 확인하세요.

환경 변수​

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

XAI_API_KEY=xai-...

구현 참고 사항​

Responses API​

Grok 텍스트 및 요약 어댑터는 xAI 의 Responses API (/v1/responses) 를 사용합니다. 요청은 기본적으로 store: false 로 설정되며 include: ["reasoning.encrypted_content"] 가 포함된 암호화된 추론 내용을 포함합니다. 둘 다 modelOptions 를 통해 재정의할 수 있습니다.

공유된 Responses 구현은 text.format 를 통한 스트리밍 텍스트, 추론 이벤트, 구조화된 출력 및 사용자 정의 함수 도구를 지원합니다.

API 참조​

grokText(model, config?)​

환경 변수를 사용해 Grok 텍스트 어댑터를 생성합니다.

매개변수:

  • model - 모델 이름 ('grok-4.3' 또는 'grok-build-0.1')
  • config.baseURL? - 사용자 지정 기본 URL(선택 사항)

반환값: Grok 텍스트 어댑터 인스턴스입니다.

createGrokText(model, apiKey, config?)​

명시적 API 키를 사용해 Grok 텍스트 어댑터를 생성합니다.

매개변수:

  • model - 모델 이름
  • apiKey - xAI API 키
  • config.baseURL? - 커스텀 기본 URL (선택 사항)

반환값: Grok 텍스트 어댑터 인스턴스입니다.

grokSummarize(model, config?)​

환경 변수를 사용해 Grok 요약 어댑터를 생성합니다.

반환값: Grok 요약 어댑터 인스턴스입니다.

createGrokSummarize(model, apiKey, config?)​

명시적 API 키를 사용해 Grok 요약 어댑터를 생성합니다.

반환값: Grok 요약 어댑터 인스턴스입니다.

grokImage(model, config?) / createGrokImage(model, apiKey, config?)​

Grok 이미지 생성 어댑터를 생성합니다.

grokVideo(model, config?) / createGrokVideo(model, apiKey, config?)​

Grok Imagine 비디오 모델 ('grok-imagine-video', 'grok-imagine-video-1.5') 을 위한 Grok 비디오 생성 어댑터 (실험적) 를 생성합니다.

grokSpeech(model, config?) / createGrokSpeech(model, apiKey, config?)​

Grok 텍스트-발음 어댑터를 생성합니다.

grokTranscription(model, config?) / createGrokTranscription(model, apiKey, config?)​

Grok 음성-텍스트 어댑터를 생성합니다.

grokRealtime(...) / grokRealtimeToken(...)​

Realtime 음성 어댑터와 토큰 발급자입니다. 사용법은 Realtime Voice Chat을 참조하세요.

다음 단계​

공급자 도구​

Grok은 현재 provider별 도구 팩토리를 제공하지 않습니다. toolDefinition()에서 @tanstack/ai을 사용하여 자체 도구를 정의합니다.

일반적인 도구 정의 흐름에 대해서는 Tools를 참조하거나, 다른 제공자의 Provider Tools를 참조합니다. 네이티브 도구 오퍼링입니다.