Developer Documentation

API Documentation

Everything you need to integrate Frux into your applications. Build powerful AI-powered solutions with our comprehensive API.

Getting Started

The Frux API provides programmatic access to our AI platform. Use it to build chatbots, analyze documents, process images, and more - all while benefiting from our Token Value Preservation technology.

Base URL

https://api.frux.pro

Quick Start Example

curl -X POST "https://api.frux.pro/api/v1/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Conversation"
  }'

Save up to 80% with TVP

Our Token Value Preservation technology automatically caches and reuses token patterns. The more you use the API, the more you save!

Authentication

The Frux API supports two authentication methods: API Keys for programmatic access and JWT tokens for user sessions.

API Key Authentication

Use API keys for server-to-server communication. Keys start with th_live_ for production or th_test_ for testing.

Authorization: Bearer th_live_xxxxxxxxxxxxxxxxxx

JWT Token Authentication

For user-facing applications, authenticate users and receive a JWT token to make requests on their behalf.

# Login to get JWT token
curl -X POST "https://api.frux.pro/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your_password"}'

# Use the token
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API Key Management

POST
/api/v1/api-keys

Create a new API key

GET
/api/v1/api-keys

List all your API keys

DELETE
/api/v1/api-keys/:keyId

Revoke an API key

Drop-in Proxy

Keep your existing code and save 20-40% on AI costs. Just change one line to route requests through Frux - we optimize automatically.

Zero Code Changes Required

Your existing Anthropic or OpenAI code works unchanged. Just update the baseURL and start saving immediately.

Anthropic SDK

Use the standard Anthropic SDK with your existing API key. Add one line to enable savings.

// Before - Direct Anthropic call
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: 'sk-ant-xxxxx'
});

// After - Add just ONE line to save 20-40%
const client = new Anthropic({
  apiKey: 'sk-ant-xxxxx',  // Your key stays the same!
  baseURL: 'https://api.frux.pro/v1-proxy'
});

// Your code stays exactly the same
const message = await client.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }]
});

OpenAI SDK

Works with the OpenAI SDK exactly the same way. Compatible with all GPT models.

// Before - Direct OpenAI call
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-xxxxx'
});

// After - Same simple change
const client = new OpenAI({
  apiKey: 'sk-xxxxx',
  baseURL: 'https://api.frux.pro/v1-proxy'
});

// Everything works identically
const completion = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }]
});

Use a Frux API Key

Alternatively, use a Frux API key for consolidated billing and enhanced tracking.

// Use a Frux API key instead of provider key
const client = new Anthropic({
  apiKey: 'th_live_xxxxx',  // Frux API key
  baseURL: 'https://api.frux.pro/v1-proxy'
});

// Same API, same code, managed billing through Frux

Savings Metrics in Response

Every response includes headers showing exactly how many tokens were saved and the percentage reduction.

# Every response includes savings metrics
X-Frux-Tokens-Original: 10000
X-Frux-Tokens-Optimized: 6000
X-Frux-Tokens-Saved: 4000
X-Frux-Savings-Percent: 40

Supported SDKs

  • • Anthropic SDK (Python & JS)
  • • OpenAI SDK (Python & JS)
  • • LangChain
  • • Any HTTP client

Benefits

  • • 20-40% cost reduction
  • • Zero code changes
  • • Rollback in seconds
  • • Real-time savings tracking

Smart Routing

Intelligent request routing that automatically selects the best service and model for your task. Uses local Qwen model when available for maximum cost savings.

Free Local AI Processing

When preferLocal is enabled (default), requests are routed to our local Qwen2.5-7B model at near-zero cost. Perfect for development, testing, and cost-sensitive applications.

Endpoint

POST
/api/v1/smart

Process a message with automatic service routing and local model optimization

Example Request

# Smart routing with local Qwen model
curl -X POST "https://api.frux.pro/api/v1/smart" \
  -H "Authorization: Bearer th_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Explain quantum computing in simple terms",
    "preferLocal": true
  }'

Request Parameters

ParameterTypeDescription
messagestringThe message or prompt to process (required)
conversationIduuid?UUID of existing conversation to maintain context
preferLocalboolean?Use local Qwen model when available (default: true)
attachmentsarray?Array of file attachments for vision/document processing
forceServicestring?Force a specific service: chat, vision, document, data

Example Response

{
  "success": true,
  "detectedIntent": {
    "service": "chat",
    "confidence": 1,
    "reasoning": "General question suitable for text conversation"
  },
  "routedTo": "chat",
  "result": {
    "message": "Quantum computing is like having a super-powerful calculator...",
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "isLocal": true
  },
  "metrics": {
    "totalTimeMs": 6074,
    "tokensUsed": { "total": 910, "input": 155, "output": 33 }
  },
  "pricing": {
    "costCharged": 0.000013,
    "costWithTvp": 0,
    "costWithoutTvp": 0.000022,
    "userSavings": 0.000009
  }
}

Available Services

  • • chat - Text conversations and Q&A
  • • vision - Image analysis and understanding
  • • document - PDF and document processing
  • • data - Data analysis and queries

Key Benefits

  • • Automatic intent detection
  • • Free local model (Qwen2.5-7B)
  • • Up to 40% cost savings
  • • Persistent conversation context

Chat & Conversations

Create conversations and send messages to AI models. Supports streaming responses for real-time interactions.

Endpoints

POST
/api/v1/conversations

Create a new conversation

GET
/api/v1/conversations

List all conversations

GET
/api/v1/conversations/:id

Get conversation details with messages

POST
/api/v1/conversations/:id/messages

Send a message and get AI response

POST
/api/v1/conversations/:id/messages/stream

Send a message with streaming response (SSE)

DELETE
/api/v1/conversations/:id

Delete a conversation

Example: Send a Message

# Send a message and get AI response
curl -X POST "https://api.frux.pro/api/v1/conversations/conv_123/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Explain quantum computing in simple terms",
    "model": "claude-3-5-sonnet-20241022"
  }'

File Management

Upload and manage files to use in conversations. Supports PDFs, images, and text files up to 50MB.

POST
/api/v1/files/upload

Upload a file (multipart/form-data)

GET
/api/v1/files

List all uploaded files

GET
/api/v1/files/:fileId

Get file metadata

GET
/api/v1/files/:fileId/content

Download file content

DELETE
/api/v1/files/:fileId

Delete a file

Example: Upload a File

# Upload a file
curl -X POST "https://api.frux.pro/api/v1/files/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"

# Response
{
  "success": true,
  "data": {
    "fileId": "file_abc123",
    "filename": "document.pdf",
    "size": 1024000,
    "mimeType": "application/pdf"
  }
}

TVP - Token Value Preservation

Process images, documents, and videos with our proprietary TVP technology. Content is cached as TVP Cards for massive savings on repeated use.

How TVP Saves You Money

When you process a document or image, we create a TVP Card that caches the token representation. Future references to the same content use the cached version, reducing tokens sent to the AI provider by up to 80%.

Image Processing

POST
/api/v1/tvp/visual/process

Process an image synchronously

POST
/api/v1/tvp/visual/process/async

Process an image asynchronously (for large files)

GET
/api/v1/tvp/visual/jobs/:jobId

Get async job status

Document Processing

POST
/api/v1/tvp/doc/process

Process a document with OCR

POST
/api/v1/tvp/doc/process/async

Process a document asynchronously

Video Processing

POST
/api/v1/tvp/video/process

Process a video file

POST
/api/v1/tvp/video/process-url

Process a video from URL

TVP Cards Management

GET
/api/v1/tvp/cards

List all your TVP cards

GET
/api/v1/tvp/cards/:cardId

Get a specific TVP card

DELETE
/api/v1/tvp/cards/:cardId

Delete a TVP card

Example: Process an Image

# Analyze an image with TVP
curl -X POST "https://api.frux.pro/api/v1/tvp/visual/process" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "file_abc123",
    "prompt": "Describe this image in detail"
  }'

# Response includes TVP Card for future savings
{
  "success": true,
  "data": {
    "response": "This image shows...",
    "tvpCard": {
      "cardId": "tvp_xyz789",
      "tokensSaved": 0,
      "tokensProcessed": 1500
    },
    "cost": {
      "withTVP": 0.02,
      "withoutTVP": 0.02,
      "savings": 0
    }
  }
}

# Subsequent calls with same content use cached tokens
# and show significant savings!

Available Models

Access multiple AI models through a single API. All models are included in your pricing tier with no additional cost.

GET
/api/v1/models

List all available models with pricing

Supported Models

Anthropic Claude

  • claude-3-5-sonnet-20241022
  • claude-3-opus-20240229
  • claude-3-haiku-20240307

OpenAI GPT

  • gpt-4o
  • gpt-4o-mini
  • gpt-4-turbo

Google Gemini

  • gemini-1.5-pro
  • gemini-1.5-flash

Meta Llama

  • llama-3.2-90b-vision
  • llama-3.1-70b

Errors & Rate Limits

The API uses standard HTTP status codes and returns detailed error messages in JSON format.

CodeStatusDescription
400Bad RequestInvalid request parameters or malformed JSON
401UnauthorizedMissing or invalid authentication credentials
403ForbiddenValid credentials but insufficient permissions
404Not FoundRequested resource does not exist
429Too Many RequestsRate limit exceeded, slow down requests
500Internal Server ErrorInternal server error, please retry or contact support

Error Response Format

{
  "success": false,
  "error": "Error message here",
  "code": "ERROR_CODE",
  "timestamp": "2025-12-31T00:00:00.000Z"
}

Rate Limiting

The API includes rate limit information in response headers. Default limit is 100 requests per minute.

# Rate limit headers in response
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1735689600

Ready to Start Building?

Create your free account to get API access and start building AI-powered applications today.

Get Your API Key
API Documentation - Frux