---
title: AI SDK Reference
description: AI chat completions and image generation with the InsForge SDK
---

import Installation from '/snippets/sdk-installation.mdx';

<Installation />

## chat.completions.create()

Create AI chat completions with streaming support.

### Parameters

- `model` (string, required) - AI model (e.g., 'anthropic/claude-3.5-haiku', 'openai/gpt-4'), call `mcp__insforge__get-backend-metadata` tool to get available models
- `messages` (array, required) - Array of message objects: `{role: "user"|"system"|"assistant", content: string}`
- `temperature` (number, optional) - Sampling temperature 0-2
- `maxTokens` (number, optional) - Max tokens to generate
- `topP` (number, optional) - Top-p sampling 0-1
- `stream` (boolean, optional) - Enable streaming mode

### Returns (non-streaming)

```typescript
{
  id: string,
  object: 'chat.completion',
  created: number,
  model: string,
  choices: [{
    index: number,
    message: { role: "system"|"user"|"assistant", content: string },
    finish_reason: string
  }],
  usage: { prompt_tokens: number, completion_tokens: number, total_tokens: number }
}
```

### Returns (streaming)

```typescript
AsyncIterableIterator<{
  id: string;
  object: 'chat.completion.chunk';
  choices: [
    {
      delta: { content: string };
      finish_reason: string | null;
    },
  ];
}>;
```

### Example (non-streaming)

```javascript
const completion = await insforge.ai.chat.completions.create({
  model: 'anthropic/claude-3.5-haiku',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What do you see in this image?' },
        {
          type: 'image_url',
          image_url: {
            url: 'https://example.com/photo.jpg', // or base64: 'data:image/jpeg;base64,...'
          },
        },
      ],
    },
  ],
});

console.log(completion.choices[0].message.content);
```

### Output (non-streaming)

```json
{
  "id": "chatcmpl-1705315200000",
  "object": "chat.completion",
  "created": 1705315200,
  "model": "anthropic/claude-3.5-haiku",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 8,
    "total_tokens": 23
  }
}
```

### Example (streaming)

```javascript
const stream = await insforge.ai.chat.completions.create({
  model: 'openai/gpt-4',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true,
});

for await (const chunk of stream) {
  if (chunk.choices[0]?.delta?.content) {
    process.stdout.write(chunk.choices[0].delta.content);
  }
}
```

### Output (streaming)

```json
{
  "id": "chatcmpl-1705315200000",
  "object": "chat.completion.chunk",
  "choices": [
    {
      "delta": { "content": "Once upon" },
      "finish_reason": null
    }
  ]
}
```

---

## images.generate()

Generate images using AI models.

### Parameters

- `model` (string, required) - Image model (e.g., 'google/gemini-2.5-flash-image-preview')
- `prompt` (string, required) - Text description of image
- `images` (array, optional) - Input images for image-to-image (url or base64)
- `width` (number, optional) - Image width in pixels
- `height` (number, optional) - Image height in pixels
- `size` (string, optional) - Predefined size ('1024x1024', '512x512')
- `numImages` (number, optional) - Number of images to generate
- `quality` ('standard' | 'hd', optional) - Image quality
- `style` ('vivid' | 'natural', optional) - Image style

### Returns

```typescript
{
  created: number,
  data: Array<{
    b64_json?: string,  // Base64 encoded image
    content?: string    // Text response from model
  }>,
  usage?: {
    total_tokens: number,
    input_tokens: number,
    output_tokens: number
  }
}
```

### Example

```javascript
const response = await insforge.ai.images.generate({
  model: 'google/gemini-2.5-flash-image-preview',
  prompt: 'A serene mountain landscape at sunset',
  size: '1024x1024',
});

// Get base64 image and upload to storage
const base64Image = response.data[0].b64_json;
const buffer = Buffer.from(base64Image, 'base64');
const blob = new Blob([buffer], { type: 'image/png' });

const { data: uploadData } = await insforge.storage.from('ai-images').uploadAuto(blob);

// Save URL to database
await insforge.database.from('generated_images').insert([
  {
    prompt: 'A serene mountain landscape',
    image_url: uploadData.url,
  },
]);
```

### Output

```json
{
  "created": 1705315200,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
      "content": "A beautiful mountain landscape at sunset with orange and purple hues."
    }
  ],
  "usage": {
    "total_tokens": 150,
    "input_tokens": 20,
    "output_tokens": 130
  }
}
```