AI API

OpenRouter-powered AI services for chat completions, image generation, and embeddings

The AI API provides OpenAI-compatible endpoints for chat completions, image generation, and embeddings, powered by OpenRouter with support for multiple AI providers.

Base URL

All AI endpoints are prefixed with /api/ai

---

Chat Completions

Generate Chat Completion

POST /api/ai/chat/completion

curl -X POST https://your-app.region.insforge.app/api/ai/chat/completion \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4",
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ],
    "temperature": 0.7,
    "maxTokens": 1000
  }'

Generate chat completion with any supported model.

Body Parameters

model · string · required

OpenRouter model identifier (e.g., “openai/gpt-4”, “anthropic/claude-3-opus”)

messages · array · required

Array of message objects

Show Message properties

role · string · required

Message role: user, assistant, system, or tool

content · string

Message content (nullable for assistant messages with tool_calls)

tool_calls · array

Tool calls made by assistant (assistant messages only)

tool_call_id · string

ID of tool call being responded to (tool messages only)

stream · boolean · default: "false"

Enable streaming response via Server-Sent Events

temperature · number

Controls randomness (0-2)

maxTokens · integer

Maximum tokens to generate

topP · number

Nucleus sampling parameter (0-1)

systemPrompt · string

System prompt to guide model behavior

thinking · boolean

Enable extended reasoning (appends :thinking to model ID, Anthropic models only)

webSearch · object

Enable web search integration

Show Web search properties

enabled · boolean · required

Enable web search

engine · string

Search engine: native (provider built-in), exa (Exa API), or undefined (auto-select)

maxResults · integer · default: "5"

Maximum search results (1-10)

searchPrompt · string

Custom prompt for search results

fileParser · object

Enable PDF file parsing

Show File parser properties

enabled · boolean · required

Enable file parsing

pdf.engine · string

PDF engine: pdf-text (free), mistral-ocr ($2/1000 pages), or native (charged as tokens)

tools · array

Tool definitions for function calling

toolChoice · string | object

Tool usage control: auto, none, required, or specific function

parallelToolCalls · boolean

Allow parallel tool calls

Response

text · string

AI model response content

tool_calls · array

Tool calls requested by model (when using function calling)

annotations · array

URL citations from web search results

metadata · object

Response metadata

Show properties

model · string

Model used for generation

usage · object

Token usage information

Basic Response

{
  "text": "The capital of France is Paris. It's located in the north-central part of the country on the Seine River.",
  "metadata": {
    "model": "openai/gpt-4",
    "usage": {
      "promptTokens": 15,
      "completionTokens": 28,
      "totalTokens": 43
    }
  }
}

Streaming Chat Completion

POST /api/ai/chat/completion (Streaming)

curl -X POST https://your-app.region.insforge.app/api/ai/chat/completion \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4",
    "messages": [{"role": "user", "content": "Tell me a story"}],
    "stream": true
  }'

Set stream: true to receive Server-Sent Events (SSE) for real-time token streaming.

Response Format

data: {"text": "Once", "done": false}

data: {"text": " upon", "done": false}

data: {"text": " a", "done": false}

data: {"text": " time", "done": false}

data: {"done": true, "metadata": {"usage": {...}}}

---

Image Generation

Generate Images

POST /api/ai/image/generation

curl -X POST https://your-app.region.insforge.app/api/ai/image/generation \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/dall-e-3",
    "prompt": "A serene landscape with mountains and a lake at sunset, photorealistic style"
  }'

Generate images using AI models.

Body Parameters

model · string · required

Image generation model (e.g., “openai/dall-e-3”, “stability-ai/stable-diffusion-xl”)

prompt · string · required

Text description of desired image

Response

model · string

Model used for generation

images · array

Generated images (URLs or base64 data)

text · string

Text content from multimodal models

count · integer

Number of images generated

metadata · object

Generation metadata including usage

{
  "model": "openai/dall-e-3",
  "images": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://oaidalleapiprodscus.blob.core.windows.net/private/..."
      }
    }
  ],
  "count": 1,
  "metadata": {
    "model": "openai/dall-e-3",
    "revisedPrompt": "A photorealistic image of a serene mountain landscape...",
    "usage": {
      "promptTokens": 12,
      "completionTokens": 0,
      "totalTokens": 12
    }
  },
  "nextActions": "Images have been generated successfully. Use the returned URLs to access them."
}

---

Embeddings

Generate Embeddings

POST /api/ai/embeddings

curl -X POST https://your-app.region.insforge.app/api/ai/embeddings \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-ada-002",
    "input": "Hello world"
  }'

Generate vector embeddings for text.

Body Parameters

model · string · required

Embedding model identifier (e.g., “openai/text-embedding-ada-002”, “google/gemini-embedding-001”)

input · string | array · required

Single text string or array of strings to embed

encoding_format · string · default: "float"

Format: float or base64

dimensions · integer

Number of dimensions (model-specific)

Response

Single Input

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.0023064255,
        -0.009327292,
        0.015797347,
        // ... 1536 dimensions total
      ],
      "index": 0
    }
  ],
  "metadata": {
    "model": "text-embedding-ada-002",
    "usage": {
      "promptTokens": 2,
      "completionTokens": 0,
      "totalTokens": 2
    }
  }
}

---

Model Management

List Available Models

GET /api/ai/models

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

Get all available text and image models from OpenRouter (admin only).

Response

{
  "text": [
    {
      "provider": "openrouter",
      "configured": true,
      "models": [
        {
          "id": "openai/gpt-4",
          "name": "GPT-4",
          "created": 1687882411,
          "description": "GPT-4 by OpenAI",
          "context_length": 8192,
          "pricing": {
            "prompt": "0.00003",
            "completion": "0.00006"
          },
          "architecture": {
            "input_modalities": ["text"],
            "output_modalities": ["text"]
          }
        }
      ]
    }
  ],
  "image": [
    {
      "provider": "openrouter",
      "configured": true,
      "models": [
        {
          "id": "openai/dall-e-3",
          "name": "DALL-E 3",
          "description": "Image generation by OpenAI",
          "pricing": {
            "image": "0.04"
          },
          "architecture": {
            "input_modalities": ["text"],
            "output_modalities": ["image"]
          }
        }
      ]
    }
  ]
}

Get Remaining Credits

GET /api/ai/credits

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

Get remaining credits from OpenRouter (admin only).

Response

{
  "credits": 25.50,
  "usage": 74.50
}

---

AI Configuration (Admin)

Create AI Configuration

POST /api/ai/configurations

curl -X POST https://your-app.region.insforge.app/api/ai/configurations \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputModality": ["text"],
    "outputModality": ["text"],
    "provider": "openrouter",
    "modelId": "openai/gpt-4",
    "systemPrompt": "You are a helpful assistant."
  }'

Create AI configuration (admin only).

Body Parameters

inputModality · array · required

Input types: ["text"], ["image"], or both

outputModality · array · required

Output types: ["text"], ["image"], or both

provider · string · required

Provider name (e.g., “openrouter”)

modelId · string · required

Model identifier

systemPrompt · string

System prompt for configuration

List AI Configurations

GET /api/ai/configurations

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

Get all AI configurations (admin only).

Update AI Configuration

PATCH /api/ai/configurations/{id}

curl -X PATCH https://your-app.region.insforge.app/api/ai/configurations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "You are a helpful coding assistant."
  }'

Update configuration system prompt (admin only).

Delete AI Configuration

DELETE /api/ai/configurations/{id}

curl -X DELETE https://your-app.region.insforge.app/api/ai/configurations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN"

Delete AI configuration (admin only).

---

Usage Tracking

Get Usage Summary

GET /api/ai/usage/summary

curl "https://your-app.region.insforge.app/api/ai/usage/summary?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN"

Get AI usage summary statistics (admin only).

Query Parameters

configId · string

Filter by configuration ID

startDate · string

Start date (ISO 8601)

endDate · string

End date (ISO 8601)

Response

{
  "totalRequests": 1250,
  "totalTokens": 45000,
  "totalCost": 12.50,
  "byModel": {
    "openai/gpt-4": {
      "requests": 800,
      "tokens": 35000,
      "cost": 10.50
    },
    "openai/gpt-3.5-turbo": {
      "requests": 450,
      "tokens": 10000,
      "cost": 2.00
    }
  }
}

Get Usage Records

GET /api/ai/usage

curl "https://your-app.region.insforge.app/api/ai/usage?limit=50&offset=0" \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN"

Get detailed usage records with pagination (admin only).