xAI Grok 프로바이더

프로바이더 인스턴스 (Provider Instance)

@ai-sdk/xai에서 기본 프로바이더 인스턴스 xai를 가져올 수 있어요:

import { xai } from '@ai-sdk/xai';

커스터마이즈된 설정이 필요하다면 @ai-sdk/xai에서 createXai를 가져와 자신의 설정으로 프로바이더 인스턴스를 만들 수 있어요:

import { createXai } from '@ai-sdk/xai';

const xai = createXai({
  apiKey: ***
});

xAI 프로바이더 인스턴스를 커스터마이즈하려면 다음의 선택적 설정을 사용할 수 있어요:

• baseURL string

  API 호출에 다른 URL 접두사를 사용해요. 예를 들어 프록시 서버를 사용할 때 유용해요. 기본 접두사는 https://api.x.ai/v1이에요.

• apiKey string

  Authorization 헤더로 전송되는 API 키예요. 기본값은 XAI_API_KEY 환경 변수예요.

• headers Record<string,string>

  요청에 포함할 커스텀 헤더예요.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  커스텀 fetch 구현. 기본값은 전역 fetch 함수예요. 요청을 가로채는 미들웨어로 사용하거나, 예를 들어 테스트를 위한 커스텀 fetch 구현을 제공하는 데 쓸 수 있어요.

언어 모델 (Language Models)

프로바이더 인스턴스를 사용해 xAI 모델을 만들 수 있어요. 첫 번째 인자는 모델 id예요 (예: grok-4.7).

const model = xai('grok-4.7');

예시 (Example)

generateText 함수로 xAI 언어 모델을 사용해 텍스트를 생성할 수 있어요:

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text } = await generateText({
  model: xai('grok-4.7'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

xAI 언어 모델은 streamText 함수에서도 사용할 수 있고 Output로 구조화된 데이터 생성을 지원해요 (AI SDK Core 참고).

추론 노력 (Reasoning Effort)

추론을 설정할 수 있는 모델의 경우 providerOptions.xai.reasoningEffort로 응답 전에 모델이 사고에 쓰는 노력을 제어할 수 있어요.

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text } = await generateText({
  model: xai('grok-4.3'),
  prompt: 'Explain quantum entanglement.',
  providerOptions: {
    xai: { reasoningEffort: 'medium' },
  },
});

AI SDK 옵션은 다음 값을 받지만, 각 xAI 모델은 일부만 지원해요:

• 'none' — 추론을 완전히 비활성화해요. thinking 토큰을 전혀 사용하지 않아요. 거의 즉각적인 응답이 필요한 단순한 사용 사례에 가장 좋아요.
• 'low' — 일부 reasoning 토큰을 사용하지만 여전히 빠르고 일반적인 에이전트 작업과 툴 호출에 좋아요.
• 'medium' — 지연 시간에 덜 민감한 애플리케이션(복잡한 데이터 분석, 긴 컨텍스트 추론 등)에 더 많은 사고를 적용해요.
• 'high' — 더 깊은 사고를 위해 더 많은 reasoning 토큰을 사용해요. 매우 어려운 문제, 복잡한 수학, 다단계 논리, 경쟁 수준의 작업에 적합해요.
• 'xhigh' — 가장 어려운 작업에 가장 많은 reasoning 토큰을 사용해요. 이 수준은 grok-4.6만 지원해요.

우선 처리 (Priority Processing)

providerOptions.xai.serviceTier는 더 높은 스케줄링 우선순위를 요청하며, 일반적으로 첫 토큰까지의 시간(time-to-first-token)을 줄이고 토큰 간 지연을 단축시켜요.

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { providerMetadata } = await generateText({
  model: xai('grok-4.7'),
  prompt: 'Explain quantum entanglement.',
  providerOptions: {
    xai: { serviceTier: 'priority' },
  },
});

// 'priority' when the request was served at the priority tier,
// 'default' when priority capacity was unavailable.
console.log(providerMetadata?.xai?.serviceTier);

우선 요청은 토큰당 프리미엄 요금으로 청구되며, xAI는 응답이 우선 등급을 확인한 경우에만 그 요금을 청구해요 — 따라서 보낸 요청이 곧 받은 등급이라고 가정하지 말고 providerMetadata.xai.serviceTier에서 적용된 등급을 다시 읽어야 해요. 옵션을 생략하면 'default'와 동일해요. xAI의 priority processing docs를 참고하세요.

실시간 모델 (Realtime Models)

Realtime은 실험적 기능이에요.

.experimental_realtime() 팩토리 메서드로 xAI Realtime API를 호출하는 모델을 만들 수 있어요.

import { xai } from '@ai-sdk/xai';

const model = xai.experimental_realtime('grok-voice-latest');

Realtime 세션은 브라우저에서 실행되며, 서버에서 xai.experimental_realtime.getToken()으로 만든 단기 토큰이 필요해요:

const token = await xai.experimental_realtime.getToken({
  model: 'grok-voice-latest',
});

전체 설정과 툴 호출 패턴은 Realtime을 참고하세요.

Responses API (에이전트 툴)

xAI Responses API는 (AI SDK 7부터) xai(modelId)를 사용할 때의 기본이에요. xai.responses(modelId)로 명시적으로 사용할 수도 있어요. 이를 통해 모델이 xAI 서버에서 툴 호출과 리서치를 자율적으로 오케스트레이션할 수 있어요.

const model = xai.responses('grok-4.7');

Responses API는 모델이 추론 과정 중 자율적으로 실행할 수 있는 서버 측 툴을 제공해요:

• web_search: 실시간 웹 검색 및 페이지 브라우징
• x_search: X(Twitter) 게시물, 사용자, 스레드 검색
• code_execution: 계산과 데이터 분석을 위한 Python 코드 실행
• view_image: 이미지 보기 및 분석
• view_x_video: X 게시물의 영상 보기 및 분석
• mcp_server: 원격 MCP 서버에 연결해 해당 툴 사용
• file_search: 벡터 스토어(컬렉션)의 문서 검색

비전 (Vision)

Responses API는 비전 모델로 이미지 입력을 지원해요:

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What do you see in this image?' },
        {
          type: 'file',
          mediaType: 'image',
          data: fs.readFileSync('./image.png'),
        },
      ],
    },
  ],
});

이미지 파트의 imageDetail 프로바이더 옵션으로 모델이 이미지를 처리하는 해상도를 제어할 수 있어요:

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text } = await generateText({
  model: xai('grok-4.7'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What do you see in this image?' },
        {
          type: 'file',
          mediaType: 'image/png',
          data: fs.readFileSync('./image.png'),
          providerOptions: {
            xai: { imageDetail: 'low' },
          },
        },
      ],
    },
  ],
});

지원되는 이미지 디테일 값은 다음과 같아요:

• low: 감소된 해상도로 이미지를 처리하고 입력 토큰을 더 적게 소비해요.
• high: 전체 해상도로 이미지를 처리해요.
• auto: xAI API가 결정하게 해요.

설정하지 않으면 이미지는 전체 해상도로 처리돼요.

웹 검색 툴 (Web Search Tool)

웹 검색 툴은 선택적 도메인 필터링과 이미지 이해로 자율적인 웹 리서치를 가능하게 해요:

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text, sources } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'What are the latest developments in AI?',
  tools: {
    web_search: xai.tools.webSearch({
      allowedDomains: ['arxiv.org', 'openai.com'],
      enableImageUnderstanding: true,
    }),
  },
});

console.log(text);
console.log('Citations:', sources);

웹 검색 파라미터

• allowedDomains string[]

  지정된 도메인 내에서만 검색해요 (최대 5개). excludedDomains와 함께 사용할 수 없어요.

• excludedDomains string[]

  지정된 도메인을 검색에서 제외해요 (최대 5개). allowedDomains와 함께 사용할 수 없어요.

• enableImageSearch boolean

  답변에 이미지가 유용할 때 별도의 웹 검색 모드로 이미지 검색을 수행하도록 모델을 허용해요. 모델은 일반 웹 검색과 이미지 검색 사이에서 선택할 수 있으며, 관련될 때 응답에 Markdown 이미지 임베드를 포함할 수 있어요.

• enableImageUnderstanding boolean

  검색 중 발견한 이미지를 모델이 보고 분석하도록 해요. 토큰 사용량이 증가해요. 이미지를 명시적으로 검색하려면 enableImageSearch를 사용하세요.

X 검색 툴 (X Search Tool)

X 검색 툴은 핸들과 날짜 범위로 필터링해 X(Twitter)에서 게시물을 검색할 수 있게 해요:

const { text, sources } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'What are people saying about AI on X this week?',
  tools: {
    x_search: xai.tools.xSearch({
      allowedXHandles: ['elonmusk', 'xai'],
      fromDate: '2025-10-23',
      toDate: '2025-10-30',
      enableImageUnderstanding: true,
      enableVideoUnderstanding: true,
    }),
  },
});

X 검색 파라미터

• allowedXHandles string[]

  지정된 X 핸들의 게시물만 검색해요 (최대 10개). excludedXHandles와 함께 사용할 수 없어요.

• excludedXHandles string[]

  지정된 X 핸들의 게시물을 제외해요 (최대 10개). allowedXHandles와 함께 사용할 수 없어요.

• fromDate string

  게시물 시작 날짜 (ISO8601 형식, YYYY-MM-DD).

• toDate string

  게시물 종료 날짜 (ISO8601 형식, YYYY-MM-DD).

• enableImageUnderstanding boolean

  X 게시물의 이미지를 모델이 보고 분석하도록 해요.

• enableVideoUnderstanding boolean

  X 게시물의 영상을 모델이 보고 분석하도록 해요.

코드 실행 툴 (Code Execution Tool)

코드 실행 툴은 계산과 데이터 분석을 위해 모델이 Python 코드를 작성하고 실행할 수 있게 해요:

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt:
    'Calculate the compound interest for $10,000 at 5% annually for 10 years',
  tools: {
    code_execution: xai.tools.codeExecution(),
  },
});

이미지 보기 툴 (View Image Tool)

이미지 보기 툴은 모델이 이미지를 보고 분석할 수 있게 해요:

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'Describe what you see in the image',
  tools: {
    view_image: xai.tools.viewImage(),
  },
});

X 영상 보기 툴 (View X Video Tool)

X 영상 보기 툴은 X(Twitter) 게시물의 영상을 모델이 보고 분석할 수 있게 해요:

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'Summarize the content of this X video',
  tools: {
    view_x_video: xai.tools.viewXVideo(),
  },
});

이미지 생성 툴 (Image Generation Tool)

이미지 생성 툴은 대화의 일부로 Grok Imagine으로 모델이 이미지를 만들고 편집하게 해요. 모델이 툴을 호출할 시점을 결정하고, 이미지 프롬프트를 작성하며, 텍스트 응답과 함께 완성된 이미지를 반환해요:

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const result = await generateText({
  model: xai.responses('grok-4.7'),
  prompt:
    'Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print',
  tools: {
    image_generation: xai.tools.imageGeneration(),
  },
});

for (const toolResult of result.staticToolResults) {
  if (toolResult.toolName === 'image_generation') {
    const base64Image = toolResult.output.result;
  }
}

툴 결과에는 모델이 이미지 모델용으로 작성한 프롬프트도 포함되어 있어, 무엇이 생성됐는지 이해하고 디버깅하는 데 유용해요.

이미지 생성 파라미터

• action 'auto' | 'generate' | 'edit'

  툴이 할 수 있는 일을 제한해요. 기본값은 'auto'예요.

  • 'auto': 모델이 이미지를 생성하고 편집할 수 있어요.
  • 'generate': 텍스트-이미지 생성만.
  • 'edit': 이미지 편집만 (대화에 이미 있는 이미지, 모델이 이전에 생성한 이미지 포함을 편집).

MCP 서버 툴 (MCP Server Tool)

MCP 서버 툴은 원격 Model Context Protocol (MCP) 서버에 연결해 해당 툴을 사용할 수 있게 해요:

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'Use the weather tool to check conditions in San Francisco',
  tools: {
    weather_server: xai.tools.mcpServer({
      serverUrl: 'https://example.com/mcp',
      serverLabel: 'weather-service',
      serverDescription: 'Weather data provider',
      allowedTools: ['get_weather', 'get_forecast'],
    }),
  },
});

MCP 서버 파라미터

• serverUrl string (필수)

  원격 MCP 서버의 URL.

• serverLabel string

  MCP 서버를 식별하는 라벨.

• serverDescription string

  MCP 서버가 제공하는 것에 대한 설명.

• allowedTools string[]

  모델이 MCP 서버에서 사용할 수 있는 툴 이름 목록. 지정하지 않으면 모든 툴이 허용돼요.

• headers Record<string, string>

  MCP 서버에 연결할 때 포함할 커스텀 헤더.

• authorization string

  MCP 서버 인증을 위한 Authorization 헤더 값 (예: 'Bearer token123').

파일 검색 툴 (File Search Tool)

파일 검색 툴은 xAI 벡터 스토어(컬렉션)에 저장된 문서를 검색할 수 있게 해요:

import { xai, type XaiLanguageModelResponsesOptions } from '@ai-sdk/xai';
import { streamText } from 'ai';

const result = streamText({
  model: xai.responses('grok-4.7'),
  prompt: 'What documents do you have access to?',
  tools: {
    file_search: xai.tools.fileSearch({
      vectorStoreIds: ['collection_your-collection-id'],
      maxNumResults: 10,
    }),
  },
  providerOptions: {
    xai: {
      include: ['file_search_call.results'],
    } satisfies XaiLanguageModelResponsesOptions,
  },
});

파일 검색 파라미터

• vectorStoreIds string[] (필수)

  검색할 벡터 스토어(컬렉션)의 ID.

• maxNumResults number

  검색에서 반환할 최대 결과 수.

파일 검색용 프로바이더 옵션

• include Array<'file_search_call.results'>

  응답에 파일 검색 결과를 포함해요. ['file_search_call.results']로 설정하면 응답에 실제 검색 결과(파일 내용과 점수 포함)가 담겨요.

여러 툴 (Multiple Tools)

포괄적인 리서치를 위해 여러 서버 측 툴을 결합할 수 있어요:

import { xai } from '@ai-sdk/xai';
import { streamText } from 'ai';

const { stream } = streamText({
  model: xai.responses('grok-4.7'),
  prompt: 'Research AI safety developments and calculate risk metrics',
  tools: {
    web_search: xai.tools.webSearch(),
    x_search: xai.tools.xSearch(),
    code_execution: xai.tools.codeExecution(),
    file_search: xai.tools.fileSearch({
      vectorStoreIds: ['collection_your-documents'],
    }),
    data_service: xai.tools.mcpServer({
      serverUrl: 'https://data.example.com/mcp',
      serverLabel: 'data-service',
    }),
  },
});

for await (const part of stream) {
  if (part.type === 'text-delta') {
    process.stdout.write(part.text);
  } else if (part.type === 'source' && part.sourceType === 'url') {
    console.log('\nSource:', part.url);
  }
}

프로바이더 옵션 (Provider Options)

Responses API는 다음 프로바이더 옵션을 지원해요:

import { xai, type XaiLanguageModelResponsesOptions } from '@ai-sdk/xai';
import { generateText } from 'ai';

const result = await generateText({
  model: xai.responses('grok-4.7'),
  providerOptions: {
    xai: {
      reasoningEffort: 'high',
    } satisfies XaiLanguageModelResponsesOptions,
  },
  // ...
});

다음 프로바이더 옵션을 사용할 수 있어요:

• reasoningEffort 'none' | 'low' | 'medium' | 'high'

  지원되는 모델의 추론 노력을 제어해요. 모델별 값과 기본값은 Reasoning Effort 참고.

• logprobs boolean

  출력 토큰에 대한 로그 확률을 반환해요. grok-4.20 및 이후 모델에서는 자동으로 무시돼요.

• topLogprobs number

  토큰 위치마다 반환할 가장 가능성 높은 토큰 수 (0-8). 설정하면 logprobs가 자동으로 활성화돼요. grok-4.20 및 이후 모델에서는 무시돼요.

• minP number

  min-p 샘플링 임계값을 0과 1 사이로 설정해요. 가장 가능성 높은 토큰 확률의 minP배 미만인 토큰은 제외돼요. 표준 AI SDK topK 옵션과 달리 minP는 xAI 고유의 것으로 providerOptions.xai에 설정해야 해요.

• maxTurns number

  xAI가 한 API 요청 안에서 수행할 수 있는 어시스턴트/서버 측 툴 턴의 최대 수를 설정해요. 웹 검색과 같은 프로바이더 실행 툴에 대한 xAI 내부 루프를 제한하며, AI SDK 단계와 API 요청의 바깥 루프를 제한하는 AI SDK의 stopWhen과는 별개예요.

• parallelToolCalls boolean

  모델이 툴을 병렬로 호출하게 해요. 기본값은 true예요.

• promptCacheKey string

  공유 프롬프트 접두사를 가진 요청을 라우팅해 캐시 재사용을 개선해요.

• safetyIdentifier string

  안전 모니터링을 위한 안정적이고 가급적 해시된 최종 사용자 식별자를 제공해요.

• user string

  남용 모니터링을 위한 최종 사용자 식별자를 제공해요.

• include Array<'file_search_call.results' | 'web_search_call.action.sources' | 'code_interpreter_call.outputs' | 'reasoning.encrypted_content' | 'no_inline_citations'>

  파일 검색 결과, 웹 검색 소스, 코드 인터프리터 출력 또는 암호화된 reasoning 콘텐츠를 포함하거나 인라인 인용을 비활성화해요.

• store boolean

  나중에 검색할 수 있도록 입력 메시지와 모델 응답을 저장할지 여부. 기본값은 true예요.

• previousResponseId string

  이전 모델 응답의 ID. 대화를 이어가는 데 사용할 수 있어요.

• serviceTier 'default' | 'priority'

  요청의 스케줄링 우선순위. 'priority'는 토큰당 프리미엄 가격으로 더 낮은 time-to-first-token과 더 빠른 토큰 간 지연을 제공해요. xAI가 실제로 적용한 등급은 providerMetadata.xai.serviceTier로 돌아오며, 우선 용량을 사용할 수 없으면 'default'예요. Priority Processing 참고.

배치 (Batch)

xAI 프로바이더는 Batch API을 통해 비동기 텍스트 생성을 지원해요. 폴링, 지속성, 결과 처리를 포함한 전체 워크플로는 xAI 프로바이더를 AI SDK의 Batch API에 전달하세요.

각 요청은 type과 model을 지정해요. xAI는 같은 배치 내에서 서로 다른 텍스트 모델 사용을 지원해요.

모델 기능 (Model Capabilities)

음성 모델 (Speech Models)

.speech() 팩토리 메서드로 xAI Text to Speech API를 호출하는 모델을 만들 수 있어요. xAI의 텍스트-음성 엔드포인트는 모델 식별자가 필요하지 않아요.

const model = xai.speech();

generateSpeech 함수로 xAI 음성 모델을 사용하세요:

import { xai } from '@ai-sdk/xai';
import { generateSpeech } from 'ai';

const result = await generateSpeech({
  model: xai.speech(),
  text: 'Hello from the AI SDK!',
  voice: 'ara',
  language: 'en',
  outputFormat: 'mp3',
  speed: 1.1,
});

지원 파라미터

• text string (필수)

  합성할 텍스트. [pause], [laugh], <whisper>...</whisper> 같은 xAI 음성 태그를 텍스트에 직접 포함할 수 있어요.

• voice string

  xAI 음성 ID. 기본값은 'eve'예요. 기본 제공 음성 ID는 'eve', 'ara', 'rex', 'sal', 'leo'이며 커스텀 음성 ID도 허용돼요.

• language string

  BCP-47 언어 코드 또는 자동 감지를 위한 'auto'. 생략하면 기본값은 'auto'예요.

• speed number

  0.7에서 1.5 사이의 음성 속도 배율.

• outputFormat string

  생성할 오디오 코덱. 지원 값은 'mp3', 'wav', 'pcm', 'mulaw', 'alaw'예요. 기본값은 'mp3'예요.

프로바이더 옵션 (Provider Options)

providerOptions.xai로 xAI 고유 제어를 전달할 수 있어요:

import { xai, type XaiSpeechModelOptions } from '@ai-sdk/xai';
import { generateSpeech } from 'ai';

const result = await generateSpeech({
  model: xai.speech(),
  text: 'A high fidelity narration sample.',
  outputFormat: 'mp3',
  providerOptions: {
    xai: {
      sampleRate: 44100,
      bitRate: 192000,
      optimizeStreamingLatency: 1,
      textNormalization: true,
    } satisfies XaiSpeechModelOptions,
  },
});

• sampleRate 8000 | 16000 | 22050 | 24000 | 44100 | 48000

  출력 오디오의 샘플 레이트 (Hz).

• bitRate 32000 | 64000 | 96000 | 128000 | 192000

  MP3 비트 레이트 (bps). outputFormat이 'mp3'일 때만 적용돼요.

• optimizeStreamingLatency 0 | 1 | 2

  지연 최적화 수준. 값이 높을수록 첫 오디오까지 시간이 줄어들지만 청크 경계에서 품질 트레이드오프가 있어요.

• textNormalization boolean

  음성 합성 전에 쓰여진 입력 텍스트를 정규화할지 여부.

• withTimestamps boolean

  오디오와 함께 문자 수준 타이밍 메타데이터를 반환해요. 타이밍 데이터와 총 지속 시간은 providerMetadata.xai로 노출돼요 (아래 참고).

• replace Record<string, string>

  합성 전에 적용할 구절-발음 치환 맵. 값은 재철자({ 'Acme Mobile': 'Acme Mobull' }) 또는 IPA 발음({ nginx: '/ˈɛndʒɪn ˈɛks/' })일 수 있어요.

프로바이더 메타데이터 (Provider Metadata)

xAI 음성 결과는 providerMetadata.xai 아래에 프로바이더 고유 메타데이터를 포함해요:

• traceId string — 요청의 xAI trace ID. xAI 지원과 함께 디버깅할 때 유용해요.
• duration number — 총 오디오 지속 시간(초) (withTimestamps일 때만).
• contentType string — 디코딩된 오디오의 MIME 타입 (예: 'audio/mpeg') (withTimestamps일 때만).
• audioTimestamps { graphChars: string[]; graphTimes: [number, number][] } — 문자별 정렬 데이터 (withTimestamps일 때만). graphChars[i]는 [start, end] 구간 graphTimes[i](초) 동안 말해진 문자예요.

const result = await generateSpeech({
  model: xai.speech(),
  text: 'Hello world.',
  providerOptions: {
    xai: { withTimestamps: true } satisfies XaiSpeechModelOptions,
  },
});

const { traceId, duration, audioTimestamps } = result.providerMetadata.xai;

모델 기능 (Model Capabilities)

전사 모델 (Transcription Models)

.transcription() 팩토리 메서드로 xAI Speech to Text API를 호출하는 모델을 만들 수 있어요. xAI의 배치 전사 엔드포인트는 모델 식별자가 필요하지 않아요.

const model = xai.transcription();

transcribe 함수로 xAI 전사 모델을 사용하세요:

import { xai } from '@ai-sdk/xai';
import { transcribe } from 'ai';
import { readFile } from 'fs/promises';

const result = await transcribe({
  model: xai.transcription(),
  audio: await readFile('meeting.mp3'),
});

프로바이더 옵션 (Provider Options)

providerOptions.xai로 xAI 고유 제어를 전달할 수 있어요:

import { xai, type XaiTranscriptionModelOptions } from '@ai-sdk/xai';
import { transcribe } from 'ai';
import { readFile } from 'fs/promises';

const result = await transcribe({
  model: xai.transcription(),
  audio: await readFile('meeting.mp3'),
  providerOptions: {
    xai: {
      language: 'en',
      format: true,
      keyterm: ['AI SDK', 'Grok'],
      diarize: true,
    } satisfies XaiTranscriptionModelOptions,
  },
});

• audioFormat pcm | mulaw | alaw

  헤더가 없는(raw) 입력 오디오의 인코딩.

• sampleRate 8000 | 16000 | 22050 | 24000 | 44100 | 48000

  입력 오디오의 샘플 레이트 (Hz).

• language string

  역 텍스트 정규화(inverse text normalization)에 사용하는 언어 코드.

• format boolean

  역 텍스트 정규화를 활성화해요. language가 필요해요.

• multichannel boolean

  인터리브된 다채널 오디오의 채널별 전사를 활성화해요.

• channels 2 | 3 | 4 | 5 | 6 | 7 | 8

  인터리브된 오디오 채널 수.

• diarize boolean

  화자 분리(diarization)를 활성화해요.

• keyterm string | string[]

  전사를 특정 용어 쪽으로 편향시키는 하나 이상의 용어.

• fillerWords boolean

  전사문에 uh, um 같은 필러 단어를 포함해요.

• streaming object

  WebSocket을 통한 스트리밍 음성-텍스트 옵션. experimental_streamTranscribe와 함께 사용해요.

  • interimResults boolean

    음성 처리 중 부분 전사문을 방출해요.

  • endpointing number

    발화 종료 이벤트 이전의 침묵 지속 시간(밀리초). 범위: 0-5000.

  • smartTurn number

    발화 종료 감지 임계값. 설정하면 Smart Turn을 활성화해요. 범위: 0.0-1.0.

  • smartTurnTimeout number

    speech_final을 강제하기 전의 최대 침묵 지속 시간(밀리초). 범위: 1-5000.

모델 기능 (Model Capabilities)

이미지 모델 (Image Models)

.image() 팩토리 메서드로 xAI 이미지 모델을 만들 수 있어요. AI SDK로 이미지 생성에 대한 자세한 내용은 generateImage()를 참고하세요.

import { xai } from '@ai-sdk/xai';
import { generateImage } from 'ai';

const { image } = await generateImage({
  model: xai.image('grok-imagine-image'),
  prompt: 'A futuristic cityscape at sunset',
});

이미지 편집 (Image Editing)

xAI는 grok-imagine-image 모델을 통한 이미지 편집을 지원해요. prompt.images로 입력 이미지를 전달해 기존 이미지를 변형하거나 편집해요.

기본 이미지 편집

텍스트 프롬프트로 기존 이미지를 변형하세요:

import { xai } from '@ai-sdk/xai';
import { generateImage } from 'ai';
import { readFileSync } from 'fs';

const imageBuffer = readFileSync('./input-image.png');

const { images } = await generateImage({
  model: xai.image('grok-imagine-image'),
  prompt: {
    text: 'Turn the cat into a golden retriever dog',
    images: [imageBuffer],
  },
});

다중 이미지 편집

프롬프트에서 여러 입력 이미지를 결합하거나 참조하세요:

import { xai } from '@ai-sdk/xai';
import { generateImage } from 'ai';
import { readFileSync } from 'fs';

const cat = readFileSync('./cat.png');
const dog = readFileSync('./dog.png');

const { images } = await generateImage({
  model: xai.image('grok-imagine-image'),
  prompt: {
    text: 'Combine these two animals into a group photo',
    images: [cat, dog],
  },
});

스타일 전이 (Style Transfer)

이미지에 예술적 스타일을 적용하세요:

const imageBuffer = readFileSync('./input-image.png');

const { images } = await generateImage({
  model: xai.image('grok-imagine-image'),
  prompt: {
    text: 'Transform this into a watercolor painting style',
    images: [imageBuffer],
  },
  aspectRatio: '1:1',
});

이미지 프로바이더 옵션 (Image Provider Options)

providerOptions.xai로 프로바이더별 설정으로 이미지 생성 동작을 커스터마이즈할 수 있어요:

import { xai, type XaiImageModelOptions } from '@ai-sdk/xai';
import { generateImage } from 'ai';

const { images } = await generateImage({
  model: xai.image('grok-imagine-image-pro'),
  prompt: 'A futuristic cityscape at sunset',
  aspectRatio: '16:9',
  providerOptions: {
    xai: {
      resolution: '2k',
      quality: 'high',
    } satisfies XaiImageModelOptions,
  },
});

• resolution '1k' | '2k'

  출력 해상도. 1k는 약 1024×1024 이미지, 2k는 약 2048×2048 이미지를 생성해요 (실제 크기는 화면 비율에 따라 달라져요). grok-imagine-image-pro에서 사용 가능해요.

• quality 'low' | 'medium' | 'high'

  이미지 품질 수준. 더 높은 품질은 생성 시간을 늘릴 수 있어요.

이미지 모델 기능 (Image Model Capabilities)

비디오 모델 (Video Models)

.video() 팩토리 메서드로 xAI 비디오 모델을 만들 수 있어요. AI SDK로 비디오 생성에 대한 자세한 내용은 generateVideo()를 참고하세요.

이 프로바이더는 텍스트 프롬프트나 이미지 입력의 표준 비디오 생성과 함께 명시적 비디오 편집, 비디오 확장, 참조-비디오(reference-to-video, R2V) 작업을 지원해요.

텍스트-비디오 (Text-to-Video)

텍스트 프롬프트로 비디오를 생성하세요:

import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: xai.video('grok-imagine-video-1.5'),
  prompt: 'A chicken flying into the sunset in the style of 90s anime.',
  aspectRatio: '16:9',
  duration: 5,
  providerOptions: {
    xai: {
      user: 'user-123',
      pollTimeoutMs: 600000, // 10 minutes
    } satisfies XaiVideoModelOptions,
  },
});

이미지 입력으로 생성 (Generation with Image Input)

이미지를 시작 프레임으로, 선택적으로 텍스트 프롬프트와 함께 비디오를 생성해요. 별도의 프로바이더 모드가 아닌 표준 생성 경로를 사용해요:

import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: xai.video('grok-imagine-video-1.5'),
  prompt: {
    image: 'https://example.com/start-frame.png',
    text: 'The cat slowly turns its head and blinks',
  },
  duration: 5,
  providerOptions: {
    xai: {
      pollTimeoutMs: 600000, // 10 minutes
    } satisfies XaiVideoModelOptions,
  },
});

또는 최상위 frameImages 옵션으로 first_frame 역할을 사용해 시작 프레임을 전달할 수 있어요. 이는 프로바이더에 구애받지 않으며 파일 데이터(예: Buffer)나 { type: 'url', url } 객체를 받아요:

import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
import { experimental_generateVideo as generateVideo } from 'ai';
import fs from 'node:fs';

const { video } = await generateVideo({
  model: xai.video('grok-imagine-video-1.5'),
  prompt: 'The cat slowly turns its head and blinks',
  frameImages: [
    {
      image: fs.readFileSync('./start-frame.png'),
      frameType: 'first_frame',
    },
  ],
  duration: 5,
  providerOptions: {
    xai: {
      pollTimeoutMs: 600000, // 10 minutes
    } satisfies XaiVideoModelOptions,
  },
});

비디오 편집 (Video Editing)

프로바이더 옵션으로 소스 비디오 URL을 제공해 텍스트 프롬프트로 기존 비디오를 편집하세요:

import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: xai.video('grok-imagine-video-1.5'),
  prompt: 'Give the person sunglasses and a hat',
  providerOptions: {
    xai: {
      mode: 'edit-video',
      videoUrl: 'https://example.com/source-video.mp4',
      pollTimeoutMs: 600000, // 10 minutes
    } satisfies XaiVideoModelOptions,
  },
});

체이닝 및 동시 편집 (Chaining and Concurrent Edits)

xAI 호스팅 비디오 URL은 providerMetadata.xai.videoUrl에서 사용할 수 있어요. Promise.all을 사용해 순차 편집 체이닝이나 동시 편집 분기(branch)에 사용할 수 있어요:

import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
import { experimental_generateVideo as generateVideo } from 'ai';

const providerOptions = {
  xai: {
    mode: 'edit-video',
    videoUrl: 'https://example.com/source-video.mp4',
    pollTimeoutMs: 600000,
  } satisfies XaiVideoModelOptions,
};

// Step 1: Apply an initial edit
const step1 = await generateVideo({
  model: xai.video('grok-imagine-video-1.5'),
  prompt: 'Add a party hat to the person',
  providerOptions,
});

// Get the xAI-hosted URL from provider metadata
const step1VideoUrl = step1.providerMetadata?.xai?.videoUrl as string;

// Step 2: Apply two more edits concurrently, building on step 1
const [withSunglasses, withScarf] = await Promise.all([
  generateVideo({
    model: xai.video('grok-imagine-video-1.5'),
    prompt: 'Add sunglasses',
    providerOptions: {
      xai: {
        mode: 'edit-video',
        videoUrl: step1VideoUrl,
        pollTimeoutMs: 600000,
      },
    },
  }),
  generateVideo({
    model: xai.video('grok-imagine-video-1.5'),
    prompt: 'Add a scarf',
    providerOptions: {
      xai: {
        mode: 'edit-video',
        videoUrl: step1VideoUrl,
        pollTimeoutMs: 600000,
      },
    },
  }),
]);

비디오 확장 (Video Extension)

마지막 프레임에서 기존 비디오를 확장해요. duration은 전체 출력이 아니라 확장 길이만 제어해요. 출력은 소스 비디오의 aspectRatio와 resolution을 상속해요.

import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
import { experimental_generateVideo as generateVideo } from 'ai';

// Step 1: Generate a source video
const source = await generateVideo({
  model: xai.video('grok-imagine-video-1.5'),
  prompt: 'A cat sitting on a sunlit windowsill, tail gently swishing.',
  duration: 5,
  aspectRatio: '16:9',
  providerOptions: {
    xai: {
      pollTimeoutMs: 600000,
    } satisfies XaiVideoModelOptions,
  },
});

const sourceUrl = source.providerMetadata?.xai?.videoUrl as string;

// Step 2: Extend the video with a new scene
const extended = await generateVideo({
  model: xai.video('grok-imagine-video-1.5'),
  prompt: 'The cat turns its head, notices a butterfly, and leaps off.',
  duration: 6,
  providerOptions: {
    xai: {
      mode: 'extend-video',
      videoUrl: sourceUrl,
      pollTimeoutMs: 600000,
    } satisfies XaiVideoModelOptions,
  },
});

참조-비디오 (Reference-to-Video, R2V)

비디오의 스타일과 콘텐츠를 안내하도록 참조 이미지를 제공해요. 이미지-비디오와 달리 참조 이미지는 첫 프레임으로 사용되지 않아요 — 모델이 생성된 비디오에 시각적 요소를 통합해요. 각 참조 이미지는 공개 HTTPS URL 또는 base64 데이터 URI일 수 있어요.

import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: xai.video('grok-imagine-video-1.5'),
  prompt:
    'The comic cat from <IMAGE_1> and the comic dog from <IMAGE_2> ' +
    'are having a playful chase through a sunlit park. ' +
    'Cinematic slow-motion, warm afternoon light.',
  duration: 8,
  aspectRatio: '16:9',
  providerOptions: {
    xai: {
      mode: 'reference-to-video',
      referenceImageUrls: [
        'https://example.com/comic-cat.png',
        'https://example.com/comic-dog.png',
      ],
      pollTimeoutMs: 600000,
    } satisfies XaiVideoModelOptions,
  },
});

특정 이미지를 참조하려면 프롬프트에서 <IMAGE_1>, <IMAGE_2> 등을 사용하세요. 요청당 최대 7개의 참조 이미지가 지원돼요.

또는 프로바이더에 구애받지 않는 최상위 inputReferences 옵션을 사용하세요. 이를 제공하면 자동으로 참조-비디오 모드가 선택되며, 파일 데이터(예: Buffer)나 { type: 'url', url } 객체를 받아요:

import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
import { experimental_generateVideo as generateVideo } from 'ai';
import fs from 'node:fs';

const { video } = await generateVideo({
  model: xai.video('grok-imagine-video-1.5'),
  prompt:
    'The comic cat and the comic dog are having a playful chase ' +
    'through a sunlit park. Cinematic slow-motion, warm afternoon light.',
  inputReferences: [
    fs.readFileSync('./comic-cat.png'),
    fs.readFileSync('./comic-dog.png'),
  ],
  duration: 8,
  aspectRatio: '16:9',
  providerOptions: {
    xai: {
      pollTimeoutMs: 600000,
    } satisfies XaiVideoModelOptions,
  },
});

inputReferences는 이미지와 오디오 참조를 받아요. 오디오 참조는 오디오 미디어 타입을 선언해야 하며, 단독으로 또는 이미지와 함께 제공될 수 있어요. reference_audios로 전송돼요. 미디어 타입이 없는 참조는 이미지로 처리돼요. 비디오 참조는 경고와 함께 무시돼요.

참조 오디오 (Reference Audio)

참조-비디오는 피사체에 목소리를 줄 수도 있어요. 호출자가 제공한 오디오 클립에는 inputReferences를, 최대 3개의 xAI 프리셋 음성 id에는 referenceVoiceIds를 사용하세요. 전달 순서대로 <AUDIO_0>, <AUDIO_1>, <AUDIO_2>로 프롬프트에서 참조하세요.

import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: xai.video('grok-imagine-video-1.5'),
  prompt:
    'The person from <IMAGE_0> stands in the room from <IMAGE_1> and speaks ' +
    'to the camera with the voice from <AUDIO_0>.',
  aspectRatio: '9:16',
  duration: 10,
  providerOptions: {
    xai: {
      mode: 'reference-to-video',
      referenceImageUrls: [
        'https://example.com/person.png',
        'https://example.com/room.png',
      ],
      referenceVoiceIds: ['eve'],
      resolution: '720p',
      pollTimeoutMs: 600000,
    } satisfies XaiVideoModelOptions,
  },
});

유효한 음성 id는 xAI text-to-speech 음성 목록에서 나와요. id는 대소문자를 구분하지 않으며, 알 수 없는 id는 사용 가능한 음성을 나열하는 400 응답을 반환해요. 결정된 작업이 참조-비디오가 아니면 referenceVoiceIds는 경고와 함께 무시돼요.

비디오 프로바이더 옵션 (Video Provider Options)

providerOptions.xai로 다음 프로바이더 옵션을 사용할 수 있어요. 프로바이더 옵션은 XaiVideoModelOptions 타입으로 검증할 수 있어요.

• pollIntervalMs number

  작업 상태 확인용 폴링 간격(밀리초). 기본값은 5000이에요.

• pollTimeoutMs number

  비디오 생성의 최대 대기 시간(밀리초). 기본값은 600000 (10분)이에요.

• resolution '480p' | '720p' | '1080p'

  비디오 해상도. SDK의 표준 resolution 파라미터를 사용하면 1920x1080은 1080p, 1280x720은 720p, 854x480은 480p에 매핑돼요. 네이티브 형식을 직접 전달하려면 이 프로바이더 옵션을 사용하세요. 1080p는 grok-imagine-video-1.5 모델이 필요하며 텍스트-비디오와 이미지-비디오에서 사용할 수 있어요. 참조-비디오는 720p로 제한돼요 (a 1080p 요청은 경고와 함께 다운그레이드).

• user string

  요청을 담당하는 최종 사용자를 위한 선택적 식별자. xAI는 남용 모니터링에 이 값을 사용해요. 비디오 생성(참조-비디오 포함)과 비디오 편집 요청에 그대로 전송되며, 설정하지 않으면 생략돼요. 비디오 확장 요청에는 전송되지 않아요. 불투명한 안정 식별자를 사용하고 불필요한 개인 정보는 보내지 마세요.

• mode 'edit-video' | 'extend-video' | 'reference-to-video'

  명시적 비디오 작업을 선택해요. 각 모드는 상호 배타적이에요:

  • 'edit-video' — 기존 비디오 편집 (videoUrl 필요)
  • 'extend-video' — 마지막 프레임에서 비디오 확장 (videoUrl 필요)
  • 'reference-to-video' — 참조 이미지에서 생성 (referenceImageUrls 필요)

  생략하면 표준 생성이 사용돼요. 레거시 입력은 호환성을 위해 필드에서 자동 감지돼요.

• videoUrl string

  소스 비디오의 URL. 비디오 편집에는 mode: 'edit-video', 비디오 확장에는 mode: 'extend-video'와 함께 사용돼요.

• referenceImageUrls string[]

  참조-비디오(R2V) 생성을 위한 참조 이미지 URL(1-7개) 또는 base64 데이터 URI 배열. 모델은 이 이미지들의 시각적 요소를 첫 프레임으로 사용하지 않고 통합해요. 특정 이미지를 참조하려면 프롬프트에서 <IMAGE_1>, <IMAGE_2> 등을 사용하세요. mode: 'reference-to-video'와 함께 사용돼요.

• referenceVoiceIds string[]

  참조-비디오(R2V) 생성에서 피사체에 목소리를 주는 최대 3개의 xAI 프리셋 음성 id. 프리셋 음성만 — 오디오 클립은 업로드할 수 없어요. id는 대소문자를 구분하지 않으며 text-to-speech 음성 목록에서 나와요. 알 수 없는 id는 사용 가능한 음성을 나열하는 400을 반환해요. 음성을 참조하려면 프롬프트에서 <AUDIO_0>, <AUDIO_1>, <AUDIO_2> 태그를 사용하세요. 참조-비디오 외에서는 경고와 함께 무시돼요. 참조 오디오는 미국 전용이며 신뢰된 파트너로 제한돼요.

• storageOptions object

  생성된 비디오를 xAI Files API에 저장해요. filename과 선택적으로 expiresAfter(최대 30일)와 publicUrl을 설정하세요. 저장된 파일 세부 정보와 스토리지 오류는 providerMetadata.xai.fileOutput와 providerMetadata.xai.storageError로 반환돼요.

• keyframes Array\<\{ imageUrl: string; timestampSeconds: number \}\>

  최대 4개의 중간 비디오 이미지 앵커. 각 타임스탬프는 비디오 지속 시간 내에 엄격히 있어야 해요. 키프레임은 grok-imagine-video-1.5가 지원하며 편집 및 확장 작업에서는 경고와 함께 무시돼요.

오디오 및 프레임 제어 (Audio and Frame Controls)

프로바이더 중립적인 generateAudio 옵션으로 생성된 오디오를 요청하거나 비활성화해요. 정확한 엔드포인트 프레임에는 frameImages를 사용하세요:

const { video } = await generateVideo({
  model: xai.video('grok-imagine-video-1.5'),
  prompt: 'A paper boat drifting down a rain-soaked street',
  generateAudio: false,
  frameImages: [
    {
      frameType: 'last_frame',
      image: 'https://example.com/final-frame.png',
    },
  ],
});

last_frame은 grok-imagine-video-1.5만 지원해요. 프로바이더는 다른 모델 ID에는 지원하지 않는 기능 경고를 방출하고 필드를 생략해요. first_frame은 xAI의 표준 image 입력으로 전송돼요.

화면 비율과 해상도 (Aspect Ratio and Resolution)

텍스트-비디오의 경우 aspectRatio와 resolution을 모두 지정할 수 있어요. 기본 화면 비율은 16:9, 기본 해상도는 480p예요. grok-imagine-video-1.5 모델은 추가로 텍스트-비디오와 이미지-비디오에서 네이티브 1080p를 지원해요.

이미지-비디오의 경우 출력은 입력 이미지의 화면 비율을 기본값으로 해요. aspectRatio를 지정하면 이를 덮어쓰고 이미지를 원하는 비율로 늘려요.

비디오 편집의 경우 출력은 입력 비디오의 화면 비율과 해상도와 일치해요. 커스텀 duration, aspectRatio, resolution은 지원되지 않아요 — 출력 해상도는 720p로 제한돼요 (예: 1080p 입력은 720p로 축소).

비디오 확장의 경우 출력은 소스 비디오에서 aspectRatio와 resolution을 상속해요. duration은 지원되며 확장 길이만 제어해요.

**참조-비디오(R2V)**의 경우 duration, aspectRatio, resolution을 지정할 수 있어요. 텍스트-비디오와 달리 R2V는 720p로 제한돼요 — 1080p 요청은 경고와 함께 720p로 다운그레이드돼요.

비디오 모델 기능 (Video Model Capabilities)

\* 네이티브 1080p는 텍스트-비디오와 이미지-비디오에 적용돼요. 참조-비디오는 720p로 제한돼요 — 1080p 요청은 경고와 함께 다운그레이드돼요.

더 알아보기 (Learn more)

• AI Gateway
• xAI Grok
• OpenAI
• Azure OpenAI
• Anthropic
• Open Responses
• Claude Platform on AWS
• Amazon Bedrock
• Groq
• Fal
• AssemblyAI
• GMI Cloud
• TypeSafe
• DeepInfra
• Deepgram
• Black Forest Labs
• Gladia
• Google
• Hume
• Google Vertex AI
• Rev.ai
• Baseten
• Hugging Face
• QuiverAI
• Fish Audio
• Mistral AI
• Z.AI
• Together.ai
• Cohere
• Fireworks
• Voyage AI
• DeepSeek
• Moonshot AI
• Alibaba
• MiniMax
• Cerebras
• Replicate
• Prodia
• Perplexity
• Luma
• ByteDance
• Kling AI
• ElevenLabs
• Cartesia

전체 사이트맵