> ## 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

> دمج TokenLab مع Vercel AI SDK باستخدام مزودات متوافقة مع OpenAI أو مزودات Responses-native

## نظرة عامة

<Note>
  **النوع**: إطار عمل أو منصة

  **المسار الأساسي**: الافتراضي المتوافق مع OpenAI

  **مستوى دعم التكامل**: نمط تكامل موصى به
</Note>

بالنسبة لـ TokenLab، فإن الخيار الافتراضي الأكثر استقراراً في Vercel AI SDK هو **المزود المتوافق مع OpenAI (OpenAI-compatible provider)**.

إذا كنت تحتاج تحديداً إلى سلوك **Responses-native**، يمكنك التبديل إلى مزود OpenAI مع الاحتفاظ بنفس عنوان URL الأساسي لـ TokenLab.

يجب التعامل مع هذه الصفحة كنمط تكامل موصى به، وليس كضمان بأن كل أداة مساعدة في Vercel AI SDK مدعومة من قبل TokenLab.

## حزمة مزود TokenLab

تحتفظ TokenLab أيضاً بحزمة مزود خفيفة لـ 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);
```

## الخيار الافتراضي الموصى به: المزود المتوافق مع 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',
});
```

## توليد النصوص (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);
```

## بث النصوص (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);
}
```

## استدعاء الأدوات (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);
```

## المخرجات المهيكلة (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);
```

## إذا كنت تحتاج صراحةً إلى سلوك Responses-Native

```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>
  استخدم `@ai-sdk/openai-compatible` كخيار افتراضي آمن لتكاملات نمط الوكيل (proxy-style). انتقل إلى `@ai-sdk/openai` فقط عندما تحتاج صراحةً إلى مسار مزود مبني على `/v1/responses`.
</Note>

## متغيرات البيئة (Environment Variables)

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

## أفضل الممارسات

<AccordionGroup>
  <Accordion title="فضل استخدام openai-compatible أولاً">
    بالنسبة للبوابات الخارجية (gateways) وخلفيات الوكيل (proxy backends)، عادةً ما يكون `@ai-sdk/openai-compatible` هو نقطة البداية الأكثر أماناً وموثوقية.
  </Accordion>

  <Accordion title="انتقل إلى Responses فقط عند الحاجة">
    إذا كنت بحاجة إلى سلوك مزود مرتبط بـ `/v1/responses`، فقم بتبديل حزمة المزود بشكل متعمد بدلاً من خلط كلا النمطين في عميل واحد.
  </Accordion>

  <Accordion title="احتفظ بالأسرار على الخادم">
    لا تقم أبداً بكشف مفتاح API الخاص بـ TokenLab في كود جانب العميل (client-side). ضع إعدادات المزود في ملفات الخادم أو مسارات API.
  </Accordion>
</AccordionGroup>