xsAI

https://xsai.js.org/docs
Admin
xsAI is an extra-small AI SDK for using OpenAI or OpenAI-compatible APIs with a significantly...
Tokens:18,741
Snippets:148
Trust Score:8.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install @xsai/generate-speech

Source: https://xsai.js.org/docs/packages/generate/speech

Install the @xsai/generate-speech package using npm.

```bash
npm i @xsai/generate-speech
```

--------------------------------

### Install xsSchema

Source: https://xsai.js.org/docs/packages-top/xsschema

Install the xsSchema package using npm.

```bash
npm i xsschema
```

--------------------------------

### Install xsai/stream-text

Source: https://xsai.js.org/docs/packages/stream/text

Install the xsai/stream-text package using npm.

```bash
npm i @xsai/stream-text
```

--------------------------------

### Install xsfetch

Source: https://xsai.js.org/docs/packages-top/xsfetch

Install the xsfetch package using npm. This is the first step to using its features.

```bash
npm i xsfetch
```

--------------------------------

### Install @xsai/embed

Source: https://xsai.js.org/docs/packages/embed

Install the xsai-embed package using npm.

```bash
npm i @xsai/embed
```

--------------------------------

### Install @xsai/model Package

Source: https://xsai.js.org/docs/packages/model

Install the @xsai/model package using npm, pnpm, yarn, or bun.

```bash
npm i @xsai/model
```

--------------------------------

### Install @xsai/generate-text

Source: https://xsai.js.org/docs/packages/generate/text

Install the xsai-generate-text package using npm.

```bash
npm i @xsai/generate-text
```

--------------------------------

### Install @xsai/generate-image

Source: https://xsai.js.org/docs/packages/generate/image

Install the image generation package using npm. Ensure you have Node.js and npm installed.

```bash
npm i @xsai/generate-image
```

--------------------------------

### Install xsAI Utils Reasoning

Source: https://xsai.js.org/docs/packages/utils/reasoning

Install the xsAI Utils Reasoning package using npm, pnpm, yarn, or bun.

```bash
npm i @xsai/utils-reasoning
```

--------------------------------

### Install xsAI Tool Package

Source: https://xsai.js.org/docs/packages/tool

Install the xsAI tool package using npm.

```bash
npm i @xsai/tool
```

--------------------------------

### Install @xsai/generate-object

Source: https://xsai.js.org/docs/packages/generate/object

Install the necessary package for generating structured data.

```bash
npm i @xsai/generate-object
```

--------------------------------

### Define and Use a Standard Tool with Valibot

Source: https://xsai.js.org/docs/packages/tool

Define a tool using `tool` which automatically infers parameter types from a Valibot schema. This example shows how to get weather information.

```typescript
import { generateText } from '@xsai/generate-text'
import { stepCountAtLeast } from '@xsai/generate-text/shared-chat'
import { tool } from '@xsai/tool'
import { env } from 'node:process'
import * as v from 'valibot'

const weather = await tool({
  description: 'Get the weather in a location',
  execute: ({ location }) => JSON.stringify({
    location,
    temperature: 42,
  }),
  name: 'weather',
  parameters: v.object({
    location: v.pipe(
      v.string(),
      v.description('The location to get the weather for'),
    ),
  }),
})

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'You are a helpful assistant.',
      role: 'system',
    },
    {
      content: 'What is the weather in San Francisco?',
      role: 'user',
    },
  ],
  model: 'gpt-4o',
  stopWhen: stepCountAtLeast(2), 
  tools: [weather], 
})
```

--------------------------------

### Install @xsai/generate-transcription

Source: https://xsai.js.org/docs/packages/generate/transcription

Install the transcription package using npm, pnpm, yarn, or bun.

```bash
npm i @xsai/generate-transcription
```

--------------------------------

### Install xsai Package

Source: https://xsai.js.org/docs/packages-top/xsai

Install the xsai package using npm. This is the first step to using the core xsAI tools.

```bash
npm i xsai
```

--------------------------------

### Install xsAI Chat Utils

Source: https://xsai.js.org/docs/packages/utils/chat

Install the xsAI chat utilities package using npm, pnpm, yarn, or bun.

```bash
npm i @xsai/utils-chat
```

--------------------------------

### Install @xsai/stream-transcription

Source: https://xsai.js.org/docs/packages/stream/transcription

Install the stream transcription package using npm. This is the first step before using the transcription functionality.

```bash
npm i @xsai/stream-transcription
```

--------------------------------

### Install @xsai/generate-speech

Source: https://xsai.js.org/docs/packages/generate/speech

Install the speech generation package using npm, pnpm, yarn, or bun.

```APIDOC
npm i @xsai/generate-speech
pnpm i @xsai/generate-speech
yarn add @xsai/generate-speech
bun add @xsai/generate-speech
```

--------------------------------

### Install @xsai/stream-transcription

Source: https://xsai.js.org/docs/packages/stream/transcription

Install the transcription package using npm, pnpm, yarn, or bun.

```APIDOC
## Installation

```bash
npm i @xsai/stream-transcription
```
```

--------------------------------

### Generate Array of Structured Objects with Valibot

Source: https://xsai.js.org/docs/packages/generate/object

Generates an array of structured objects using Valibot schema. This example demonstrates generating multiple hero descriptions for a fantasy game. Ensure you have installed a standard schema to JSON schema parser.

```typescript
import { generateObject } from '@xsai/generate-object'
import { env } from 'node:process'
import * as v from 'valibot'

const { object: objects } = await generateObject({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'Generate 3 hero descriptions for a fantasy role playing game.',
      role: 'user'
    }
  ],
  model: 'gpt-4o',
  output: 'array', 
  schema: v.object({
    name: v.string(),
    class: v.pipe(
      v.string(),
      v.description('Character class, e.g. warrior, mage, or thief.'),
    ),
    description: v.string(),
  })
})

for (const object of objects) { 
  console.log(object)
}
```

--------------------------------

### Install Telemetry Package

Source: https://xsai.js.org/docs/packages-ext/telemetry

Install the telemetry package using npm. This package provides telemetry features for xsAI.

```bash
npm i @xsai-ext/telemetry
```

--------------------------------

### Install xsAI Providers Package

Source: https://xsai.js.org/docs/packages-ext/providers

Install the xsAI providers package using npm. This package is not recommended for xsAI-based libraries.

```bash
npm i @xsai-ext/providers
```

--------------------------------

### Stream Text Generation with xsAI

Source: https://xsai.js.org/docs/packages/stream/text

Basic example of streaming text from a prompt using xsAI. Ensure your OPENAI_API_KEY is set in the environment.

```typescript
import { streamText } from '@xsai/stream-text'
import { env } from 'node:process'

const { textStream } = streamText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'You are a helpful assistant.',
      role: 'system',
    },
    {
      content: 'This is a test, so please answer'
        + '
'The quick brown fox jumps over the lazy dog.'
        + 'and nothing else.',
      role: 'user',
    },
  ],
  model: 'gpt-4o',
})

const text: string[] = []

for await (const textPart of textStream) {
  text.push(textPart)
}

// "The quick brown fox jumps over the lazy dog."
console.log(text)
```

--------------------------------

### Basic Transcription Example

Source: https://xsai.js.org/docs/packages/stream/transcription

Demonstrates how to transcribe an audio file using the streamTranscription function. Ensure your provider supports streaming.

```APIDOC
## Basic Usage

Before using this package, please verify that your provider supports `"stream": true`.

```javascript
import { streamTranscription } from '@xsai/stream-transcription'
import { openAsBlob } from 'node:fs'

const { textStream } = streamTranscription({
  apiKey: '',
  baseURL: 'https://api.openai.com/v1/',
  file: await openAsBlob('./test/fixtures/basic.wav', { type: 'audio/wav' }),
  fileName: 'basic.wav',
  language: 'en',
  model: 'gpt-4o-transcribe',
})
```
```

--------------------------------

### Stream Text with Audio Input using xsAI

Source: https://xsai.js.org/docs/packages/stream/text

Example of streaming text from a prompt that includes an audio input. Ensure the model supports multi-modal input and check compatibility.

```typescript
import { streamText } from '@xsai/stream-text'
import { Buffer } from 'node:buffer'
import { env } from 'node:process'

const data = await fetch('https://cdn.openai.com/API/docs/audio/alloy.wav')
  .then(res => res.arrayBuffer())
  .then(buffer => Buffer.from(buffer).toString('base64'))

const { textStream } = streamText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'What is in this recording?' },
      { type: 'input_audio', input_audio: { data, format: 'wav' }}
    ],
  }],
  model: 'gpt-4o-audio-preview',
  modalities: ['text', 'audio'],
})
```

--------------------------------

### Define and Use a Raw Tool with Manual Parameters

Source: https://xsai.js.org/docs/packages/tool

Define a tool using `rawTool` where parameter types are manually specified as a JSON schema. This example retrieves weather information.

```typescript
import { generateText } from '@xsai/generate-text'
import { stepCountAtLeast } from '@xsai/generate-text/shared-chat'
import { rawTool } from '@xsai/tool'
import { env } from 'node:process'

const weather = rawTool<{ location: string }>({
  description: 'Get the weather in a location',
  execute: ({ location }) => JSON.stringify({
    location,
    temperature: 42,
  }),
  name: 'weather',
  parameters: {
    additionalProperties: false,
    properties: {
      location: {
        description: 'The location to get the weather for',
        type: 'string',
      },
    },
    required: [
      'location',
    ],
    type: 'object',
  },
})

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'You are a helpful assistant.',
      role: 'system',
    },
    {
      content: 'What is the weather in San Francisco?',
      role: 'user',
    },
  ],
  model: 'gpt-4o',
  stopWhen: stepCountAtLeast(2), 
  tools: [weather], 
})
```

--------------------------------

### Using the `tool` function with Valibot

Source: https://xsai.js.org/docs/packages/tool

This example demonstrates how to use the `tool` function to define a weather tool with Valibot for schema validation. The `tool` function automatically infers the schema type.

```APIDOC
## Tool Definition with `tool` and Valibot

### Description
Defines a tool for getting weather information using Valibot for parameter validation.

### Method
`tool`

### Parameters
- `name` (string): The name of the tool ('weather').
- `description` (string): A description of the tool's purpose ('Get the weather in a location').
- `parameters` (Valibot Schema): The schema for the tool's input parameters, including a `location` string.
- `execute` (function): A function that executes the tool's logic, taking parameters like `location` and returning a JSON string with weather data.

### Request Example
```javascript
import { tool } from '@xsai/tool'
import * as v from 'valibot'

const weather = tool({
  description: 'Get the weather in a location',
  execute: ({ location }) => JSON.stringify({
    location,
    temperature: 42,
  }),
  name: 'weather',
  parameters: v.object({
    location: v.pipe(
      v.string(),
      v.description('The location to get the weather for'),
    ),
  }),
})
```

### Usage with `generateText`

### Description
This example shows how to use the defined `weather` tool with the `generateText` function from `@xsai/generate-text`.

### Method
`generateText`

### Parameters
- `apiKey` (string): Your OpenAI API key.
- `baseURL` (string): The base URL for the API.
- `messages` (Array): An array of message objects for the conversation.
- `model` (string): The language model to use (e.g., 'gpt-4o').
- `stopWhen` (function): A function to determine when to stop generation.
- `tools` (Array): An array of tool definitions to be used by the model.

### Request Example
```javascript
import { generateText } from '@xsai/generate-text'
import { stepCountAtLeast } from '@xsai/generate-text/shared-chat'
import { env } from 'node:process'

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'You are a helpful assistant.',
      role: 'system',
    },
    {
      content: 'What is the weather in San Francisco?',
      role: 'user',
    },
  ],
  model: 'gpt-4o',
  stopWhen: stepCountAtLeast(2), 
  tools: [weather], 
})
```
```

--------------------------------

### Stream Text with Image Input using xsAI

Source: https://xsai.js.org/docs/packages/stream/text

Example of streaming text from a prompt that includes an image. Verify model compatibility for multi-modal input before use.

```typescript
import { streamText } from '@xsai/stream-text'
import { env } from 'node:process'

const { textStream } = streamText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'What\'s in this image?' },
      {
        type: 'image_url',
        image_url: {
          url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg',
        },
      },
    ],
  }],
  model: 'gpt-4o',
})
```

--------------------------------

### Using `rawTool` with Zod and `toJSONSchema`

Source: https://xsai.js.org/docs/packages/tool

This example shows an alternative way to use `rawTool` by defining the schema with Zod and then converting it to a JSON Schema using `z.toJSONSchema`. This approach helps avoid asynchronous contagion.

```APIDOC
## Tool Definition with `rawTool`, Zod, and `toJSONSchema`

### Description
Defines a tool for getting weather information using Zod for schema definition and `z.toJSONSchema` to convert it to a JSON Schema. This method helps in avoiding asynchronous contagion.

### Method
`rawTool`

### Parameters
- `name` (string): The name of the tool ('weather').
- `description` (string): A description of the tool's purpose ('Get the weather in a location').
- `parameters` (JsonSchema): The JSON Schema derived from Zod for the tool's input parameters.
- `execute` (function): A function that executes the tool's logic, taking parameters like `location` and returning a JSON string with weather data.

### Request Example
```javascript
import { rawTool } from '@xsai/tool'
import type { RawToolOptions } from '@xsai/tool'
import * as z from 'zod'

const weatherSchema = z.object({
  location:
    z.string()
    .describe('The location to get the weather for'),
})

const weather = rawTool<z.input<typeof weatherSchema>>({
  description: 'Get the weather in a location',
  execute: ({ location }) => JSON.stringify({
    location,
    temperature: 42,
  }),
  name: 'weather',
  parameters: z.toJSONSchema(weatherSchema) as unknown as RawToolOptions['parameters'],
})
```
```

--------------------------------

### Using the `rawTool` function with JSON Schema

Source: https://xsai.js.org/docs/packages/tool

This example demonstrates how to use the `rawTool` function to define a weather tool with a raw JSON Schema for parameter validation. The `rawTool` function requires manual definition of the execute function's parameter types.

```APIDOC
## Tool Definition with `rawTool` and JSON Schema

### Description
Defines a tool for getting weather information using a raw JSON Schema for parameter validation. The `execute` function's parameter types must be explicitly defined.

### Method
`rawTool`

### Parameters
- `name` (string): The name of the tool ('weather').
- `description` (string): A description of the tool's purpose ('Get the weather in a location').
- `parameters` (JsonSchema): The raw JSON Schema for the tool's input parameters, including a `location` string.
- `execute` (function): A function that executes the tool's logic, taking parameters like `location` and returning a JSON string with weather data.

### Request Example
```javascript
import { rawTool } from '@xsai/tool'

const weather = rawTool({
  description: 'Get the weather in a location',
  execute: ({ location }) => JSON.stringify({
    location,
    temperature: 42,
  }),
  name: 'weather',
  parameters: {
    additionalProperties: false,
    properties: {
      location: {
        description: 'The location to get the weather for',
        type: 'string',
      },
    },
    required: [
      'location',
    ],
    type: 'object',
  },
})
```

### Usage with `generateText`

### Description
This example shows how to use the defined `weather` tool with the `generateText` function from `@xsai/generate-text`.

### Method
`generateText`

### Parameters
- `apiKey` (string): Your OpenAI API key.
- `baseURL` (string): The base URL for the API.
- `messages` (Array): An array of message objects for the conversation.
- `model` (string): The language model to use (e.g., 'gpt-4o').
- `stopWhen` (function): A function to determine when to stop generation.
- `tools` (Array): An array of tool definitions to be used by the model.

### Request Example
```javascript
import { generateText } from '@xsai/generate-text'
import { stepCountAtLeast } from '@xsai/generate-text/shared-chat'
import { env } from 'node:process'

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'You are a helpful assistant.',
      role: 'system',
    },
    {
      content: 'What is the weather in San Francisco?',
      role: 'user',
    },
  ],
  model: 'gpt-4o',
  stopWhen: stepCountAtLeast(2), 
  tools: [weather], 
})
```
```

--------------------------------

### Configure Telemetry with GenAI Attributes

Source: https://xsai.js.org/docs/packages-ext/telemetry

Configure additional telemetry options, including GenAI attributes for tracking agent details. This example shows how to set agent name and description.

```typescript
import { generateText } from '@xsai-ext/telemetry'
import { env } from 'node:process'

const instructions = 'You\'re a helpful assistant.'

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: instructions, 
      role: 'system'
    },
    {
      content: 'Why is the sky blue?',
      role: 'user'
    }
  ],
  model: 'gpt-4o',
  telemetry: { 
    attributes: { 
      'gen_ai.agent.name': 'weather-assistant', 
      'gen_ai.agent.description': instructions, 
    }, 
  }, 
})

```

--------------------------------

### Generate Speech

Source: https://xsai.js.org/docs/packages/generate/speech

Example of generating speech from text using the `generateSpeech` function. This function takes an object with `baseURL`, `input` text, `model`, and `voice` as parameters and returns the audio data.

```APIDOC
## Generate Speech

Generates audio from the input text.

### Method Signature

```javascript
async generateSpeech({
  baseURL: string,
  input: string,
  model: string,
  voice: string
}): Promise<ArrayBuffer>
```

### Parameters

- **baseURL** (string) - The base URL for the speech generation service.
- **input** (string) - The text to convert into speech.
- **model** (string) - The speech synthesis model to use (e.g., 'tts-1').
- **voice** (string) - The voice to use for speech synthesis (e.g., 'en-US-AnaNeural').

### Request Example

```javascript
import { generateSpeech } from '@xsai/generate-speech'
import { Buffer } from 'node:buffer'

const speech = await generateSpeech({
  baseURL: 'http://localhost:5050',
  input: 'Hello, I am your AI assistant! Just let me know how I can help bring your ideas to life.',
  model: 'tts-1',
  voice: 'en-US-AnaNeural',
})

const audio = Buffer.from(speech)
```

### Response

- **audio** (ArrayBuffer) - The generated audio data.
```

--------------------------------

### Extract Reasoning from Text

Source: https://xsai.js.org/docs/packages/utils/reasoning

Use extractReasoning to get XML-tagged reasoning sections from raw text. Ensure you have the necessary imports for generateText and extractReasoning.

```typescript
import { generateText } from '@xsai/generate-text'
import { extractReasoning } from '@xsai/utils-reasoning'
import { env } from 'node:process'

const { text: rawText } = await generateText({
  baseURL: 'http://localhost:11434/v1/',
  messages: [
    {
      content: 'You\'re a helpful assistant.',
      role: 'system'
    },
    {
      content: 'Why is the sky blue?',
      role: 'user'
    },
  ],
  model: 'qwen3',
})

const { reasoning, text } = extractReasoning(rawText!)
```

--------------------------------

### Generate Multiple Images with DALL-E 3

Source: https://xsai.js.org/docs/packages/generate/image

Generates multiple images (up to 4 in this example) from a single text prompt using the DALL-E 3 model. This is useful for exploring variations of a concept.

```typescript
import { generateImage } from '@xsai/generate-image'
import { env } from 'node:process'

const { images } = await generateImage({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'http://api.openai.com/v1/',
  n: 4, 
  model: 'dall-e-3',
  prompt: 'A cute baby sea otter'
})
```

--------------------------------

### Stream Structured Object with Valibot Schema

Source: https://xsai.js.org/docs/packages/stream/object

Use this to extract structured object data from a prompt based on a Valibot schema. Ensure you have installed a schema-to-JSON-schema parser.

```typescript
import { streamObject } from '@xsai/stream-object'
import { env } from 'node:process'
import * as v from 'valibot'

const { partialObjectStream } = await streamObject({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'Extract the event information.',
      role: 'system'
    },
    {
      content: 'Alice and Bob are going to a science fair on Friday.',
      role: 'user'
    }
  ],
  model: 'gpt-4o',
  schema: v.object({
    name: v.string(),
    date: v.string(),
    participants: v.array(v.string()),
  })
})

for await (const partialObject of partialObjectStream) { 
  console.log(partialObject)
}
```

--------------------------------

### Generate Structured Object with Valibot

Source: https://xsai.js.org/docs/packages/generate/object

Generates a structured object based on a Valibot schema. Ensure you have installed a standard schema to JSON schema parser as Valibot does not provide this natively.

```typescript
import { generateObject } from '@xsai/generate-object'
import { env } from 'node:process'
import * as v from 'valibot'

const { object } = await generateObject({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'Extract the event information.',
      role: 'system'
    },
    {
      content: 'Alice and Bob are going to a science fair on Friday.',
      role: 'user'
    }
  ],
  model: 'gpt-4o',
  schema: v.object({
    name: v.string(),
    date: v.string(),
    participants: v.array(v.string()),
  })
})
```

--------------------------------

### createFetch with generateText

Source: https://xsai.js.org/docs/packages-top/xsfetch

Demonstrates using createFetch with the generateText function from '@xsai/generate-text'.

```APIDOC
## createFetch with generateText

### Description
Demonstrates using createFetch with the generateText function from '@xsai/generate-text'. This example shows how to integrate xsfetch with an AI text generation service.

### Method
`generateText(options)`

### Parameters
- **apiKey** (string) - Required - Your API key for the AI service.
- **baseURL** (string) - Required - The base URL of the AI service API.
- **fetch** (Function) - Required - The fetch instance created by `createFetch`.
- **messages** (Array<Object>) - Required - An array of message objects for the AI conversation.
- **model** (string) - Required - The AI model to use for generation.

### Request Example
```javascript
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'
import { createFetch } from 'xsfetch'

const fetch = createFetch({
  retry: 3,
  retryDelay: 1000,
})

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  fetch,
  messages: [
    {
      content: 'You\'re a helpful assistant.',
      role: 'system'
    },
    {
      content: 'Why is the sky blue?',
      role: 'user'
    }
  ],
  model: 'gpt-4o',
})
```

### Response
- **text** (string) - The generated text from the AI.
```

--------------------------------

### Verbose Transcription with Word Timestamps

Source: https://xsai.js.org/docs/packages/generate/transcription

Get detailed transcription results with word-level timestamps. Set responseFormat to 'verbose_json' and timestampGranularities to 'word'.

```typescript
import { generateTranscription } from '@xsai/generate-transcription'
import { openAsBlob } from 'node:fs'

const { duration, language, text, words } = await generateTranscription({
  apiKey: '',
  baseURL: 'http://localhost:8000/v1/',
  file: await openAsBlob('./test/fixtures/basic.wav', { type: 'audio/wav' }),
  fileName: 'basic.wav',
  language: 'en',
  model: 'deepdml/faster-whisper-large-v3-turbo-ct2',
  responseFormat: 'verbose_json',
  timestampGranularities: 'word',
})
```

--------------------------------

### Retrieve a Specific Model

Source: https://xsai.js.org/docs/packages/model

Use the `retrieveModel` function to get details about a specific model by its ID. Requires an API key and base URL.

```typescript
import { retrieveModel } from '@xsai/model'
import { env } from 'node:process'

// {
//   "id": "gpt-4o",
//   "object": "model",
//   "created": 1686935002,
//   "owned_by": "openai"
// }
const model = await retrieveModel({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  model: 'gpt-4o'
})
```

--------------------------------

### Create Chat Messages with xsAI

Source: https://xsai.js.org/docs/packages/utils/chat

Demonstrates how to create system and user messages using the `message` utility from `@xsai/utils-chat` in conjunction with `generateText` from `@xsai/generate-text`. Ensure your API key and base URL are correctly configured.

```typescript
import { generateText } from '@xsai/generate-text'
import { message } from '@xsai/utils-chat'
import { env } from 'node:process'

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'You\'re a helpful assistant.',
      role: 'system'
    },
    message.system('You\'re a helpful assistant.'),
    {
      content: 'Why is the sky blue?',
      role: 'user'
    },
    message.user('Why is the sky blue?'),
  ],
  model: 'gpt-4o',
})
```

--------------------------------

### createFetch

Source: https://xsai.js.org/docs/packages-top/xsfetch

Initializes a fetch instance with configurable retry options.

```APIDOC
## createFetch

### Description
Initializes a fetch instance with configurable retry options.

### Method
`createFetch(options?: FetchOptions)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **retry** (number) - Optional - The number of times to retry the request.
- **retryDelay** (number) - Optional - The delay in milliseconds between retries.

### Request Example
```javascript
import { createFetch } from 'xsfetch'

const fetch = createFetch({
  retry: 3,
  retryDelay: 1000,
})
```

### Response
Returns a fetch function with retry capabilities.
```

--------------------------------

### Generate a single text embedding

Source: https://xsai.js.org/docs/packages/embed

Use the `embed` function to get a vector representation for a single piece of text. Ensure your API key and base URL are correctly configured.

```typescript
import { embed } from '@xsai/embed'
import { env } from 'node:process'

const { embedding } = await embed({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  input: 'sunny day at the beach',
  model: 'text-embedding-3-large',
})
```

--------------------------------

### Define and Use a Weather Tool

Source: https://xsai.js.org/docs/packages/tool

Define a custom tool for fetching weather information and use it with `generateText`. Ensure necessary imports are included.

```typescript
import type { Tool } from '@xsai/shared-chat'

import { generateText } from '@xsai/generate-text'
import { stepCountAtLeast } from '@xsai/generate-text/shared-chat'
import { env } from 'node:process'

const weather = {
  execute: (({ location }) => JSON.stringify({
    location,
    temperature: 42,
  })) as Tool['execute'], 
  function: {
    description: 'Get the weather in a location',
    name: 'weather',
    parameters: {
      additionalProperties: false,
      properties: {
        location: {
          description: 'The location to get the weather for',
          type: 'string',
        },
      },
      required: [
        'location',
      ],
      type: 'object',
    },
    strict: true,
  },
  type: 'function',
} satisfies Tool

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'You are a helpful assistant.',
      role: 'system',
    },
    {
      content: 'What is the weather in San Francisco?',
      role: 'user',
    },
  ],
  model: 'gpt-4o',
  stopWhen: stepCountAtLeast(2), 
  tools: [weather], 
})
```

--------------------------------

### Create Runtime-Agnostic Google Provider

Source: https://xsai.js.org/docs/packages-ext/providers

Create a runtime-agnostic Google provider using the create function, which allows for flexibility in different environments. Replace 'YOUR_API_KEY_HERE' with your actual API key.

```typescript
// import { google } from '@xsai-ext/providers'
import { createGoogleGenerativeAI } from '@xsai-ext/providers/create'
import { generateText } from '@xsai/generate-text'

const google = createGoogleGenerativeAI('YOUR_API_KEY_HERE') 

const { text } = await generateText({
  ...google.chat('gemini-2.5-flash'),
  messages: [{
    content: 'Why is the sky blue?',
    role: 'user'
  }],
})
```

--------------------------------

### Basic Text Generation

Source: https://xsai.js.org/docs/packages/generate/text

Generate text using a system prompt and a user query. Ensure your OPENAI_API_KEY is set in your environment variables.

```typescript
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'You\'re a helpful assistant.',
      role: 'system'
    },
    {
      content: 'Why is the sky blue?',
      role: 'user'
    }
  ],
  model: 'gpt-4o',
})
```

--------------------------------

### Import Telemetry Enabled Functions

Source: https://xsai.js.org/docs/packages-ext/telemetry

Switch your imports from 'xsai' to '@xsai-ext/telemetry' to enable telemetry. Currently supports generateText and streamText.

```typescript
- import { generateText, streamText } from 'xsai'
+ import { generateText, streamText } from '@xsai-ext/telemetry'
```

--------------------------------

### Use xsfetch with generateText

Source: https://xsai.js.org/docs/packages-top/xsfetch

Integrate xsfetch with the generateText function from '@xsai/generate-text'. This allows making API calls for text generation using the configured fetch instance.

```typescript
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'
import { createFetch } from 'xsfetch'

const fetch = createFetch({
  retry: 3,
  retryDelay: 1000,
})

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  fetch,
  messages: [
    {
      content: 'You\'re a helpful assistant.',
      role: 'system'
    },
    {
      content: 'Why is the sky blue?',
      role: 'user'
    }
  ],
  model: 'gpt-4o',
})
```

--------------------------------

### Basic Transcription with xsai/generate-transcription

Source: https://xsai.js.org/docs/packages/generate/transcription

Perform a basic audio transcription. Ensure you have the necessary imports and provide your API key, base URL, file, file name, language, and model.

```typescript
import { generateTranscription } from '@xsai/generate-transcription'
import { openAsBlob } from 'node:fs'

const { text } = await generateTranscription({
  apiKey: '',
  baseURL: 'http://localhost:8000/v1/',
  file: await openAsBlob('./test/fixtures/basic.wav', { type: 'audio/wav' }),
  fileName: 'basic.wav',
  language: 'en',
  model: 'deepdml/faster-whisper-large-v3-turbo-ct2',
})
```

--------------------------------

### Create Fetch Instance with Retry

Source: https://xsai.js.org/docs/packages-top/xsfetch

Create a custom fetch instance with automatic retry configured. Set the number of retries and the delay between retries.

```typescript
import { createFetch } from 'xsfetch'

const fetch = createFetch({
  retry: 3,
  retryDelay: 1000,
})
```

--------------------------------

### Text Generation with Audio Input

Source: https://xsai.js.org/docs/packages/generate/text

Generate text by providing an audio recording along with a text prompt. Ensure the model supports audio input and specify modalities.

```typescript
import { generateText } from '@xsai/generate-text'
import { Buffer } from 'node:buffer'
import { env } from 'node:process'

const data = await fetch('https://cdn.openai.com/API/docs/audio/alloy.wav')
  .then(res => res.arrayBuffer())
  .then(buffer => Buffer.from(buffer).toString('base64'))

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'What is in this recording?' },
      { type: 'input_audio', input_audio: { data, format: 'wav' }}
    ],
  }],
  model: 'gpt-4o-audio-preview',
  modalities: ['text', 'audio'],
})
```

--------------------------------

### List Available Models

Source: https://xsai.js.org/docs/packages/model

Use the `listModels` function to retrieve a list of available models. Requires an API key and base URL for the service.

```typescript
import { listModels } from '@xsai/model'
import { env } from 'node:process'

// [
//   {
//     "id": "model-id-0",
//     "object": "model",
//     "created": 1686935002,
//     "owned_by": "organization-owner"
//   },
//   {
//     "id": "model-id-1",
//     "object": "model",
//     "created": 1686935002,
//     "owned_by": "organization-owner",
//   },
//   {
//     "id": "model-id-2",
//     "object": "model",
//     "created": 1686935002,
//     "owned_by": "openai"
//   },
// ]
const models = await listModels({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/'
})
```

--------------------------------

### listModels

Source: https://xsai.js.org/docs/packages/model

Fetches a list of available models from the API. This function requires an API key and a base URL for the API endpoint.

```APIDOC
## listModels

### Description
Fetches a list of available models from the API.

### Method
```javascript
listModels(options: {
  apiKey: string
  baseURL: string
}): Promise<Array<object>>
```

### Parameters
#### Request Body
- **apiKey** (string) - Required - The API key for authentication.
- **baseURL** (string) - Required - The base URL of the API endpoint.

### Request Example
```javascript
import { listModels } from '@xsai/model'
import { env } from 'node:process'

const models = await listModels({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/'
})
```

### Response
#### Success Response (200)
- **models** (Array<object>) - A list of model objects, each containing id, object, created, and owned_by fields.
```

--------------------------------

### Basic Text Generation

Source: https://xsai.js.org/docs/packages/generate/text

Generates text based on a prompt using the generateText function. Requires an API key, base URL, messages, and a model.

```APIDOC
## Basic Text Generation

### Description
Generates text for a given prompt.

### Method
`generateText` (function)

### Parameters
- `apiKey` (string) - Required - API key for authentication.
- `baseURL` (string) - Required - Base URL for the API endpoint.
- `messages` (Array<Object>) - Required - An array of message objects, each with a `role` (system/user) and `content`.
- `model` (string) - Required - The model to use for generation (e.g., 'gpt-4o').

### Request Example
```javascript
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [
    {
      content: 'You\'re a helpful assistant.',
      role: 'system'
    },
    {
      content: 'Why is the sky blue?',
      role: 'user'
    }
  ],
  model: 'gpt-4o',
})
```

### Response
#### Success Response
- `text` (string) - The generated text content.
```

--------------------------------

### Usage with Predefined Google Provider

Source: https://xsai.js.org/docs/packages-ext/providers

Use a predefined Google provider by importing it and configuring it with an API key. This method reads the API Key from environment variables and cannot be used in a browser.

```typescript
import { google } from '@xsai-ext/providers'
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'

const { text } = await generateText({
  ...google.chat('gemini-2.5-flash'), 
  apiKey: env.GEMINI_API_KEY!,
  baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai/', 
  messages: [{
    content: 'Why is the sky blue?',
    role: 'user'
  }],
  model: 'gemini-2.5-flash', 
})
```

--------------------------------

### Text Generation with Audio Input

Source: https://xsai.js.org/docs/packages/generate/text

Generates text by processing an audio file along with a text prompt. Requires specifying modalities and ensuring the model supports audio input.

```APIDOC
## Text Generation with Audio Input

### Description
Generates text by analyzing an audio file provided in the prompt.

### Method
`generateText` (function)

### Parameters
- `apiKey` (string) - Required - API key for authentication.
- `baseURL` (string) - Required - Base URL for the API endpoint.
- `messages` (Array<Object>) - Required - An array of message objects. The user message can contain an array of content parts, including text and audio input.
  - `content` (Array<Object>) - Content parts for the user message.
    - `type` (string) - Type of content ('text' or 'input_audio').
    - `text` (string) - Text content.
    - `input_audio` (Object) - Object containing the audio data and format.
      - `data` (string) - Base64 encoded audio data.
      - `format` (string) - The format of the audio (e.g., 'wav').
- `model` (string) - Required - The model to use for generation (e.g., 'gpt-4o-audio-preview').
- `modalities` (Array<string>) - Required - Specifies the modalities to be used (e.g., ['text', 'audio']).

### Request Example
```javascript
import { generateText } from '@xsai/generate-text'
import { Buffer } from 'node:buffer'
import { env } from 'node:process'

const data = await fetch('https://cdn.openai.com/API/docs/audio/alloy.wav')
  .then(res => res.arrayBuffer())
  .then(buffer => Buffer.from(buffer).toString('base64'))

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'What is in this recording?' },
      { type: 'input_audio', input_audio: { data, format: 'wav' }}
    ],
  }],
  model: 'gpt-4o-audio-preview', 
  modalities: ['text', 'audio'], 
})
```

### Response
#### Success Response
- `text` (string) - The generated text content based on the audio and prompt.
```

--------------------------------

### Text Generation with Image Input

Source: https://xsai.js.org/docs/packages/generate/text

Generate text based on an image and a text prompt. Verify that the model supports multi-modal input before use.

```typescript
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'What\'s in this image?' },
      {
        type: 'image_url',
        image_url: {
          url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg',
        },
      },
    ],
  }],
  model: 'gpt-4o',
})
```

--------------------------------

### Generate a Single Image with DALL-E 3

Source: https://xsai.js.org/docs/packages/generate/image

Generates a single image based on a text prompt using the DALL-E 3 model. Requires an OpenAI API key and specifies the base URL.

```typescript
import { generateImage } from '@xsai/generate-image'
import { env } from 'node:process'

const { image } = await generateImage({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'http://api.openai.com/v1/',
  model: 'dall-e-3',
  prompt: 'A cute baby sea otter'
})
```

--------------------------------

### Simulate a Readable Stream - TypeScript

Source: https://xsai.js.org/docs/packages/utils/stream

Use `simulateReadableStream` to create a mock readable stream for testing or demonstration purposes. Specify chunks and delays to control stream behavior.

```typescript
import { simulateReadableStream } from '@xsai/utils-stream'

const stream = simulateReadableStream<number>({
  chunks: [1, 2, 3],
  chunkDelay: 100,
  initialDelay: 0,
})
```

--------------------------------

### Text Generation with Image Input

Source: https://xsai.js.org/docs/packages/generate/text

Generates text by processing an image along with a text prompt. Ensure the model supports multi-modal input.

```APIDOC
## Text Generation with Image Input

### Description
Generates text by analyzing an image provided in the prompt.

### Method
`generateText` (function)

### Parameters
- `apiKey` (string) - Required - API key for authentication.
- `baseURL` (string) - Required - Base URL for the API endpoint.
- `messages` (Array<Object>) - Required - An array of message objects. The user message can contain an array of content parts, including text and image URLs.
  - `content` (Array<Object>) - Content parts for the user message.
    - `type` (string) - Type of content ('text' or 'image_url').
    - `text` (string) - Text content.
    - `image_url` (Object) - Object containing the image URL.
      - `url` (string) - The URL of the image.
- `model` (string) - Required - The model to use for generation (e.g., 'gpt-4o').

### Request Example
```javascript
import { generateText } from '@xsai/generate-text'
import { env } from 'node:process'

const { text } = await generateText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'What\'s in this image?' },
      { 
        type: 'image_url', 
        image_url: { 
          url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg', 
        }, 
      }, 
    ],
  }],
  model: 'gpt-4o',
})
```

### Response
#### Success Response
- `text` (string) - The generated text content based on the image and prompt.
```
Tokens:
Raw