Developer API Reference

Welcome to the EpesiCloud AI Platform API reference. This platform abstracts various AI service vendors (Google Gemini, Groq, Cloudflare) behind unified, reliable interfaces, ensuring high availability through tenant-scoped fallback routing and credentials management.

Authentication

To perform requests to the EpesiCloud AI Platform, you must present a valid API Key. Secure your key and provide it in all requests inside the Authorization header or the custom x-api-key header.

Header Format

Authorization: Bearer epesi_ai_your_api_key_here

Alternatively, use the custom header format:

x-api-key: epesi_ai_your_api_key_here

OpenAI SDK Compatibility

EpesiCloud AI provides native OpenAI API compatibility. If your applications, agents, or tools already use OpenAI's official SDKs, LangChain, LiteLLM, Cursor, or LibreChat, you can point them directly to EpesiCloud with zero code rewrites.

Python (Official OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://ai.epesicloud.com/v1",
    api_key="epesi_ai_your_api_key_here"
)

response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",  # Or virtual aliases: "default", "smart", "fast", "agent"
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Analyze our Q3 sales figures."}
    ],
    temperature=0.7
)

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

TypeScript / Node.js

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://ai.epesicloud.com/v1",
  apiKey: "epesi_ai_your_api_key_here",
});

const completion = await openai.chat.completions.create({
  model: "llama-3.3-70b-versatile",
  messages: [{ role: "user", content: "Hello from EpesiCloud!" }],
});

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

cURL Example (Chat Completions)

curl -X POST "https://ai.epesicloud.com/v1/chat/completions" \
  -H "Authorization: Bearer epesi_ai_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-versatile",
    "messages": [
      {"role": "user", "content": "Hello EpesiCloud!"}
    ]
  }'

Streaming (Server-Sent Events)

Pass stream: true to receive real-time token streaming using standard SSE (text/event-stream), fully compatible with OpenAI streaming parsers.

Available Virtual Aliases

• agent: Recommended for Algolia and AI Agents. Automatically routes through our function-calling and tool-calling model chain with multi-provider fallback.
• default: Default tenant-configured model chain with intelligent fallback.
• smart: High-reasoning model chain optimized for complex analysis and synthesis.
• fast: Ultra-low latency LPU model chain optimized for speed.

Connecting Third-Party Tools (Algolia, Cursor, Dify, LiteLLM)

Many modern AI and search platforms allow you to register external model providers using standard OpenAI Compatible configuration profiles. You can register EpesiCloud in any of these platforms using the settings below:

Model Registry

List all available LLM models configured on the platform, along with pricing rates and capability tags (e.g., whether a model supports image vision understanding).

cURL Example

curl -X GET "https://ai.epesicloud.com/api/v1/models" \
  -H "Authorization: Bearer epesi_ai_your_api_key"

Response Example (JSON)

[
  {
    "id": "gemini-2.0-flash",
    "key": "google/gemini-2.0-flash",
    "displayName": "Gemini 2.0 Flash",
    "pricingPrompt": "0.075",
    "pricingCompletion": "0.30",
    "capabilities": {
      "text.chat": true,
      "vision.understand": true
    }
  }
]

Text Completions

Single-turn model completions. Used for workflows like text classification, summarization, entity extraction, or structured data transformations.

Body Parameters

cURL Example

curl -X POST "https://ai.epesicloud.com/api/v1/text-generations" \
  -H "Authorization: Bearer epesi_ai_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Extract names of users: James and Maria",
    "jsonMode": true
  }'

Response Example (JSON)

{
  "content": "{\n  \"names\": [\"James\", \"Maria\"]\n}",
  "model": {
    "id": "gemini-2.0-flash",
    "displayName": "Gemini 2.0 Flash"
  },
  "latencyMs": 412
}

Conversation Chat (Multimodal)

Manage multi-turn chat sessions with vision/image input capabilities. The platform persists chat history internally, meaning you only need to submit the latest message along with the active conversation ID.

Start a Conversation

Attachment Structure

{
  "kind": "image",
  "url": "data:image/jpeg;base64,/9j/4AAQ...",
  "mimeType": "image/jpeg"
}

cURL Example

curl -X POST "https://ai.epesicloud.com/api/v1/conversations" \
  -H "Authorization: Bearer epesi_ai_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is in this image?",
    "attachments": [
      {
        "kind": "image",
        "url": "data:image/jpeg;base64,/9j/4AAQ...",
        "mimeType": "image/jpeg"
      }
    ]
  }'

Response Example (JSON)

{
  "conversationId": "e12a-442b-98bc-f8e12a",
  "content": "This image shows a standard farm animal word search puzzle."
}

Reply to an Existing Conversation

Appends a follow-up query to the conversation thread history.

Retrieve Thread History

Archive Conversation

Image Generation

POST /api/v1/image-generations
{
  "prompt": "A modern sleek glass workspace office",
  "aspectRatio": "16:9"
}

Video Generation

POST /api/v1/video-generations
{
  "prompt": "Cinematic flying view over rolling green hills",
  "durationSeconds": 5
}

Transcription & Audio

POST /api/v1/audio-transcriptions
{
  "fileUrl": "https://storage.epesicloud.com/records/call-189.mp3",
  "language": "en"
}