AI Integration - InsForge

Overview

InsForge provides an OpenAI-compatible AI API powered by OpenRouter, giving you access to multiple AI providers and models through a single interface.

Key Features

Multiple Providers - OpenAI, Anthropic, Google, Meta, and more
Chat Completions - Text generation with streaming support
Image Generation - DALL-E, Stable Diffusion, and other models
Embeddings - Vector embeddings for semantic search
Function Calling - Tool use and structured outputs
Web Search - AI with internet access
File Parser - Process PDFs and documents
Extended Thinking - Deep reasoning capabilities

Architecture

Chat Completions

Basic Chat

import { createClient } from '@insforge/sdk';

const client = createClient({
  baseUrl: 'https://your-app.region.insforge.app',
  anonKey: 'your-anon-key'
});

const { data, error } = await client.ai.chat.completions.create({
  model: 'openai/gpt-4',
  messages: [
    { role: 'user', content: 'What is InsForge?' }
  ]
});

if (error) {
  console.error('AI error:', error);
} else {
  console.log('Response:', data.text);
}

Response:

{
  "text": "InsForge is a backend-as-a-service platform...",
  "metadata": {
    "model": "openai/gpt-4",
    "usage": {
      "promptTokens": 15,
      "completionTokens": 42,
      "totalTokens": 57
    }
  }
}

Conversation History

const messages = [
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user', content: 'What is 2+2?' },
  { role: 'assistant', content: '2+2 equals 4.' },
  { role: 'user', content: 'What about 3+3?' }
];

const { data } = await client.ai.chat.completions.create({
  model: 'openai/gpt-4',
  messages
});

Streaming Responses

Stream responses for real-time output:

const { data, error } = await client.ai.chat.completions.create({
  model: 'openai/gpt-4',
  messages: [
    { role: 'user', content: 'Write a short story.' }
  ],
  stream: true
});

if (!error) {
  for await (const chunk of data) {
    process.stdout.write(chunk);
  }
}

Model Parameters

// Control randomness (0 = deterministic, 2 = creative)
const { data } = await client.ai.chat.completions.create({
  model: 'openai/gpt-4',
  messages: [{ role: 'user', content: 'Be creative!' }],
  temperature: 1.5
});

Available Models

Text Models

Provider	Model ID	Context	Use Case
OpenAI	`openai/gpt-4`	8K	High quality
OpenAI	`openai/gpt-4-turbo`	128K	Long context
OpenAI	`openai/gpt-3.5-turbo`	16K	Fast, cheap
Anthropic	`anthropic/claude-3.5-sonnet`	200K	Long documents
Google	`google/gemini-pro`	32K	Multimodal
Meta	`meta-llama/llama-3-70b`	8K	Open source

Get All Models

curl https://your-app.region.insforge.app/api/ai/models \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Function Calling

Use AI to call structured functions:

const tools = [
  {
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get the current weather for a location',
      parameters: {
        type: 'object',
        properties: {
          location: {
            type: 'string',
            description: 'City name'
          },
          unit: {
            type: 'string',
            enum: ['celsius', 'fahrenheit']
          }
        },
        required: ['location']
      }
    }
  }
];

Web Search

Enable AI with internet access:

const { data } = await client.ai.chat.completions.create({
  model: 'openai/gpt-4',
  messages: [
    { role: 'user', content: 'What are the latest AI developments?' }
  ],
  webSearch: {
    enabled: true,
    engine: 'native' // Uses provider's built-in search
  }
});

Image Generation

const { data, error } = await client.ai.images.generate({
  model: 'openai/dall-e-3',
  prompt: 'A serene landscape with mountains and a lake at sunset'
});

if (!error) {
  console.log('Image URL:', data.images[0].image_url.url);
}

Response:

{
  "model": "openai/dall-e-3",
  "images": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://..."
      }
    }
  ],
  "count": 1,
  "metadata": {
    "model": "openai/dall-e-3",
    "revisedPrompt": "...",
    "usage": {
      "totalTokens": 1
    }
  }
}

Image Models

Provider	Model ID	Size	Style
OpenAI	`openai/dall-e-3`	1024x1024	Photorealistic
Stability	`stability-ai/stable-diffusion-xl`	Various	Artistic

Embeddings

Generate vector embeddings for semantic search:

const { data, error } = await client.ai.embeddings.create({
  model: 'openai/text-embedding-3-small',
  input: 'InsForge is a backend platform'
});

if (!error) {
  const embedding = data.data[0].embedding;
  console.log('Vector dimension:', embedding.length);
  
  // Store in database with pgvector
  await client.database
    .from('documents')
    .insert([{
      content: 'InsForge is a backend platform',
      embedding: embedding
    }]);
}

Embedding Models

Provider	Model ID	Dimensions	Cost
OpenAI	`openai/text-embedding-3-small`	1536	Low
OpenAI	`openai/text-embedding-3-large`	3072	Medium
Google	`google/gemini-embedding-001`	768	Low

File Processing

Process PDFs and documents:

const { data } = await client.ai.chat.completions.create({
  model: 'openai/gpt-4',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Summarize this document' },
        {
          type: 'file',
          file: {
            filename: 'document.pdf',
            file_data: 'https://example.com/document.pdf'
          }
        }
      ]
    }
  ],
  fileParser: {
    enabled: true,
    pdf: {
      engine: 'mistral-ocr' // Best for scanned docs
    }
  }
});

Extended Thinking

Enable deep reasoning for complex problems:

const { data } = await client.ai.chat.completions.create({
  model: 'anthropic/claude-3.5-sonnet',
  messages: [
    { role: 'user', content: 'Solve this complex math problem: ...' }
  ],
  thinking: true // Appends :thinking to model ID
});

Extended thinking is only available for Anthropic models with the :thinking suffix.

Usage Tracking

Check Credits

curl https://your-app.region.insforge.app/api/ai/credits \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Response:

{
  "credits": 10.50,
  "usage": 2.35
}

Usage Summary

curl "https://your-app.region.insforge.app/api/ai/usage/summary?startDate=2024-01-01" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

API Reference

Endpoints

# Chat
POST   /api/ai/chat/completion

# Images
POST   /api/ai/image/generation

# Embeddings
POST   /api/ai/embeddings

# Admin
GET    /api/ai/models
GET    /api/ai/credits
GET    /api/ai/usage/summary
GET    /api/ai/usage

Response Structure

interface ChatCompletionResponse {
  text: string;
  tool_calls?: ToolCall[];
  annotations?: UrlCitationAnnotation[];
  metadata: {
    model: string;
    usage: {
      promptTokens: number;
      completionTokens: number;
      totalTokens: number;
    };
  };
}

Best Practices

Choose the Right Model

Use cheaper models (GPT-3.5) for simple tasks, premium models (GPT-4) for complex reasoning

Use System Prompts

Set consistent AI behavior with system prompts

Stream for UX

Stream responses for better user experience in chat interfaces

Store Embeddings

Save embeddings in PostgreSQL with pgvector for similarity search

Monitor Usage

Track API usage and costs with usage endpoints

Next Steps

Database

Store AI-generated content and embeddings

Functions

Build custom AI workflows

Storage

Store generated images

Real-time

Stream AI responses in real-time

Get Started

Core Features

SDKs & Integration

Platform

Resources

Documentation Index

​Overview

​Key Features

​Architecture

​Chat Completions

​Basic Chat

​Conversation History

​Streaming Responses

​Model Parameters

​Available Models

​Text Models

​Get All Models

​Function Calling

​Web Search

​Image Generation

​Image Models

​Embeddings

​Embedding Models

​File Processing

​Extended Thinking

​Usage Tracking

​Check Credits

​Usage Summary

​API Reference

​Endpoints

​Response Structure

​Best Practices

Choose the Right Model

Use System Prompts

Stream for UX

Store Embeddings

Monitor Usage

​Next Steps

Database

Functions

Storage

Real-time

Overview

Key Features

Architecture

Chat Completions

Basic Chat

Conversation History

Streaming Responses

Model Parameters

Available Models

Text Models

Get All Models

Function Calling

Web Search

Image Generation

Image Models

Embeddings

Embedding Models

File Processing

Extended Thinking

Usage Tracking

Check Credits

Usage Summary

API Reference

Endpoints

Response Structure

Best Practices

Next Steps