> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Vercel AI SDK

> Tích hợp TokenLab với Vercel AI SDK sử dụng các provider tương thích với OpenAI hoặc Responses-native

## Tổng quan

<Note>
  **Loại**: Framework hoặc Platform

  **Đường dẫn chính**: Mặc định tương thích với OpenAI

  **Độ tin cậy hỗ trợ**: Mô hình tích hợp được khuyến nghị
</Note>

Đối với TokenLab, mặc định ổn định nhất trong Vercel AI SDK là **provider tương thích với OpenAI**.

Nếu bạn đặc biệt cần hành vi **Responses-native**, bạn có thể chuyển sang provider OpenAI và giữ nguyên base URL của TokenLab.

Hãy coi trang này là một mô hình tích hợp được khuyến nghị, không phải là sự đảm bảo rằng mọi helper trong Vercel AI SDK đều được TokenLab hỗ trợ.

## Gói Provider TokenLab

TokenLab cũng duy trì một trình bao bọc (wrapper) provider nhẹ cho Vercel AI SDK:

```bash theme={null}
npm install ai @tokenlabai/ai-sdk-provider
```

```typescript theme={null}
import { generateText } from 'ai';
import { tokenlab } from '@tokenlabai/ai-sdk-provider';

const { text } = await generateText({
  model: tokenlab.chatModel('gpt-5.4'),
  prompt: 'Explain TokenLab in one sentence.',
});

console.log(text);
```

## Mặc định được khuyến nghị: Provider tương thích với OpenAI

```bash theme={null}
npm install ai @ai-sdk/openai-compatible
```

```typescript theme={null}
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';

export const tokenlab = createOpenAICompatible({
  name: 'tokenlab',
  apiKey: process.env.TOKENLAB_API_KEY,
  baseURL: 'https://api.tokenlab.sh/v1',
});
```

## Tạo văn bản (Generate Text)

```typescript theme={null}
import { generateText } from 'ai';
import { tokenlab } from './tokenlab';

const { text } = await generateText({
  model: tokenlab.chatModel('gpt-5.4'),
  prompt: 'Explain TokenLab in one sentence.',
});

console.log(text);
```

## Truyền phát văn bản (Stream Text)

```typescript theme={null}
import { streamText } from 'ai';
import { tokenlab } from './tokenlab';

const result = await streamText({
  model: tokenlab.chatModel('gpt-5.4'),
  prompt: 'Write a short poem about coding.',
});

for await (const textPart of result.textStream) {
  process.stdout.write(textPart);
}
```

## Gọi công cụ (Tool Calling)

```typescript theme={null}
import { generateText, tool } from 'ai';
import { z } from 'zod';
import { tokenlab } from './tokenlab';

const result = await generateText({
  model: tokenlab.chatModel('gpt-5.4'),
  prompt: 'What is the weather in San Francisco?',
  tools: {
    weather: tool({
      description: 'Get weather in a location',
      parameters: z.object({
        location: z.string(),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 72,
        condition: 'sunny',
      }),
    }),
  },
});

console.log(result.text);
```

## Đầu ra có cấu trúc (Structured Output)

```typescript theme={null}
import { generateObject } from 'ai';
import { z } from 'zod';
import { tokenlab } from './tokenlab';

const { object } = await generateObject({
  model: tokenlab.chatModel('gpt-5.4'),
  schema: z.object({
    name: z.string(),
    role: z.string(),
  }),
  prompt: 'Generate a fake developer profile.',
});

console.log(object);
```

## Nếu bạn cần hành vi Responses-Native một cách rõ ràng

```bash theme={null}
npm install ai @ai-sdk/openai
```

```typescript theme={null}
import { createOpenAI } from '@ai-sdk/openai';

export const tokenlabResponses = createOpenAI({
  apiKey: process.env.TOKENLAB_API_KEY,
  baseURL: 'https://api.tokenlab.sh/v1',
});
```

```typescript theme={null}
import { generateText } from 'ai';
import { tokenlabResponses } from './tokenlab-responses';

const { text } = await generateText({
  model: tokenlabResponses('gpt-5.4'),
  prompt: 'Explain TokenLab in one sentence.',
});
```

<Note>
  Sử dụng `@ai-sdk/openai-compatible` làm mặc định an toàn cho các tích hợp kiểu proxy. Chỉ chuyển sang `@ai-sdk/openai` khi bạn muốn một đường dẫn provider được xây dựng trên `/v1/responses`.
</Note>

## Biến môi trường (Environment Variables)

```bash theme={null}
# .env.local
TOKENLAB_API_KEY=sk-your-tokenlab-key
```

## Các phương pháp tốt nhất (Best Practices)

<AccordionGroup>
  <Accordion title="Ưu tiên sử dụng openai-compatible trước">
    Đối với các cổng kết nối (gateway) của bên thứ ba và backend proxy, `@ai-sdk/openai-compatible` thường là điểm khởi đầu ít gây bất ngờ nhất.
  </Accordion>

  <Accordion title="Chỉ chuyển sang Responses khi cần thiết">
    Nếu bạn cần hành vi provider gắn liền với `/v1/responses`, hãy chuyển đổi gói provider một cách có chủ đích thay vì trộn lẫn cả hai mô hình trong cùng một client.
  </Accordion>

  <Accordion title="Giữ bí mật trên server">
    Không bao giờ để lộ API key TokenLab của bạn trong mã phía client. Hãy đặt cấu hình provider trong các tệp server hoặc các API route.
  </Accordion>
</AccordionGroup>