OpenAI Compatible API

UniCraft provides a fully compatible OpenAI API interface, allowing you to use it as a drop-in replacement for OpenAI with enhanced routing capabilities.

Overview

UniCraft’s OpenAI-compatible API allows you to:

Drop-in Replacement: Use existing OpenAI code without changes
Smart Routing: Automatically route to the best available model
Multi-Provider: Access multiple AI providers through one API
Cost Optimization: Reduce costs through intelligent model selection
Enhanced Reliability: Built-in failover and redundancy

API Compatibility

UniCraft supports the following OpenAI API endpoints:

/v1/chat/completions - Chat completions
/v1/completions - Text completions
/v1/embeddings - Text embeddings
/v1/models - List available models
/v1/fine-tunes - Fine-tuning operations

Quick Start

1. Update Your API Endpoint

Simply change your API endpoint from OpenAI to UniCraft:

// Before (OpenAI)
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://api.openai.com/v1",
});

// After (UniCraft)
const openai = new OpenAI({
  apiKey: process.env.UNICRAFT_API_KEY,
  baseURL: "https://api.unicraft.com/v1",
});

2. Use Existing Code

Your existing OpenAI code will work without changes:

// This code works with both OpenAI and UniCraft
const response = await openai.chat.completions.create({
  model: "gpt-3.5-turbo",
  messages: [{ role: "user", content: "Hello, world!" }],
  max_tokens: 100,
});

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

Enhanced Features

1. Smart Model Selection

Use “auto” to let UniCraft choose the best model:

const response = await openai.chat.completions.create({
  model: "auto", // UniCraft will choose the best model
  messages: [{ role: "user", content: "Hello, world!" }],
  max_tokens: 100,
});

2. Cost Optimization

Set cost limits for automatic optimization:

const response = await openai.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Hello, world!" }],
  max_tokens: 100,
  max_cost: 0.01, // Maximum cost per request
  quality_threshold: 0.8, // Minimum quality requirement
});

3. Provider Selection

Specify which providers to use:

const response = await openai.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Hello, world!" }],
  max_tokens: 100,
  providers: ["openai", "anthropic"], // Only use these providers
  fallback_providers: ["google"], // Fallback if primary providers fail
});

API Reference

Chat Completions

Endpoint

POST /v1/chat/completions

Parameters

Parameter	Type	Description
`model`	string	Model to use (or “auto” for smart routing)
`messages`	array	Array of message objects
`max_tokens`	integer	Maximum tokens to generate
`temperature`	number	Sampling temperature (0.0 to 1.0)
`top_p`	number	Nucleus sampling parameter
`frequency_penalty`	number	Frequency penalty (-2.0 to 2.0)
`presence_penalty`	number	Presence penalty (-2.0 to 2.0)
`max_cost`	number	Maximum cost per request
`quality_threshold`	number	Minimum quality requirement
`providers`	array	Preferred providers
`fallback_providers`	array	Fallback providers

Example Request

const response = await fetch("https://api.unicraft.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer your-unicraft-api-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "auto",
    messages: [{ role: "user", content: "Hello, world!" }],
    max_tokens: 100,
    temperature: 0.7,
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

Example Response

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-3.5-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  },
  "unicraft": {
    "provider": "openai",
    "cost": 0.000042,
    "response_time": 1250,
    "routing_decision": "cost_optimized"
  }
}

Text Completions

Endpoint

POST /v1/completions

Example Request

const response = await fetch("https://api.unicraft.com/v1/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer your-unicraft-api-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "auto",
    prompt: "The future of AI is",
    max_tokens: 100,
    temperature: 0.7,
  }),
});

Embeddings

Endpoint

POST /v1/embeddings

Example Request

const response = await fetch("https://api.unicraft.com/v1/embeddings", {
  method: "POST",
  headers: {
    Authorization: "Bearer your-unicraft-api-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "auto",
    input: "The text to embed",
  }),
});

Models

Endpoint

GET /v1/models

Example Request

const response = await fetch("https://api.unicraft.com/v1/models", {
  headers: {
    Authorization: "Bearer your-unicraft-api-key",
  },
});

const data = await response.json();
console.log(data.data); // Array of available models

SDK Integration

OpenAI Python SDK

import openai

# Configure UniCraft
openai.api_key = "your-unicraft-api-key"
openai.api_base = "https://api.unicraft.com/v1"

# Use existing code
response = openai.ChatCompletion.create(
    model="auto",
    messages=[
        {"role": "user", "content": "Hello, world!"}
    ],
    max_tokens=100
)

print(response.choices[0].message.content)

OpenAI Node.js SDK

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.UNICRAFT_API_KEY,
  baseURL: "https://api.unicraft.com/v1",
});

const response = await openai.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Hello, world!" }],
  max_tokens: 100,
});

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

LangChain Integration

from langchain.llms import OpenAI
from langchain.chat_models import ChatOpenAI

# Configure UniCraft
llm = OpenAI(
    openai_api_key="your-unicraft-api-key",
    openai_api_base="https://api.unicraft.com/v1",
    model_name="auto"
)

# Use with LangChain
response = llm("Hello, world!")
print(response)

Migration Guide

From OpenAI to UniCraft

Update API Endpoint

// Change from OpenAI to UniCraft
const baseURL = "https://api.unicraft.com/v1";

Update API Key

// Use your UniCraft API key
const apiKey = process.env.UNICRAFT_API_KEY;

Configure Providers

// Set up your AI providers in UniCraft dashboard
// No code changes needed

Test Compatibility

// Test with existing code
const response = await openai.chat.completions.create({
  model: "gpt-3.5-turbo",
  messages: [{ role: "user", content: "Test" }],
});

Gradual Migration

You can migrate gradually by using both APIs:

// Use UniCraft for new features
const unicraftResponse = await unicraft.chat.completions.create({
  model: "auto",
  messages: messages,
  max_cost: 0.01,
});

// Keep OpenAI for existing features
const openaiResponse = await openai.chat.completions.create({
  model: "gpt-3.5-turbo",
  messages: messages,
});

Advanced Configuration

1. Custom Routing Rules

const response = await openai.chat.completions.create({
  model: "auto",
  messages: messages,
  routing_rules: {
    content_generation: {
      preferred_models: ["gpt-4", "claude-3-sonnet"],
      max_cost: 0.05,
    },
    simple_qa: {
      preferred_models: ["gpt-3.5-turbo", "claude-3-haiku"],
      max_cost: 0.01,
    },
  },
});

2. A/B Testing

const response = await openai.chat.completions.create({
  model: "auto",
  messages: messages,
  ab_test: {
    enabled: true,
    variants: [
      { name: "cost_optimized", weight: 0.5 },
      { name: "quality_optimized", weight: 0.5 },
    ],
  },
});

3. Cost Monitoring

const response = await openai.chat.completions.create({
  model: "auto",
  messages: messages,
  cost_monitoring: {
    enabled: true,
    alert_threshold: 0.05,
    daily_limit: 100.0,
  },
});

Error Handling

Standard OpenAI Errors

UniCraft returns standard OpenAI error formats:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

UniCraft-Specific Errors

Additional error information for debugging:

{
  "error": {
    "message": "No providers available",
    "type": "provider_error",
    "code": "no_providers_available",
    "unicraft": {
      "provider_status": {
        "openai": "unavailable",
        "anthropic": "rate_limited",
        "google": "unavailable"
      }
    }
  }
}

Best Practices

1. Model Selection

Use “auto” for most cases
Specify models only when needed
Consider cost vs. quality trade-offs

2. Error Handling

Implement retry logic
Handle rate limiting
Use fallback providers

3. Cost Management

Set cost limits
Monitor usage
Use cost-optimized routing

4. Performance

Use appropriate max_tokens
Implement caching
Monitor response times

Troubleshooting

Common Issues

Authentication Errors
- Check API key
- Verify endpoint URL
- Test connection
Model Not Available
- Check provider configuration
- Use “auto” for smart routing
- Verify model availability
Rate Limiting
- Implement retry logic
- Use multiple providers
- Monitor usage
High Costs
- Use cost-optimized routing
- Set cost limits
- Monitor spending

Debug Mode

Enable debug mode for troubleshooting:

const response = await openai.chat.completions.create({
  model: "auto",
  messages: messages,
  debug: true,
});

console.log(response.unicraft.debug);

Support

For support with OpenAI compatibility:

Documentation: UniCraft Docs
API Reference: UniCraft API Docs
Community: UniCraft Community
Support: support@unicraft.com

Next Steps

After setting up OpenAI compatibility:

Test Migration: Test your existing code with UniCraft
Configure Providers: Set up your AI providers
Optimize Routing: Configure smart routing rules
Monitor Usage: Set up monitoring and alerts
Scale Gradually: Migrate features incrementally