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.

Tip: All APIs respond with standard HTTP status codes. Successful responses will possess a status of 200 OK or 201 Created and output JSON payloads.

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

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).

GET /api/v1/models

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.

POST /api/v1/text-generations

Body Parameters

Field	Type	Required	Description
prompt	string	Yes	The input text completion prompt for the model.
systemPrompt	string	No	Optional developer directives or persona limits for the model.
modelId	string	No	Target a specific model explicitly (e.g. `gemini-2.0-flash`).
temperature	number	No	Creative randomness setting (from `0.0` to `1.0`).
jsonMode	boolean	No	Enforce structured output; model response is guaranteed to be parsable JSON.

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

POST /api/v1/conversations

Field	Type	Required	Description
message	string	Yes	The starting message.
modelId	string	No	Target model selector override.
attachments	array	No	List of base64 encoded image objects (for vision support). See details below.

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

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

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

Retrieve Thread History

GET /api/v1/conversations/:id

Archive Conversation

DELETE /api/v1/conversations/:id

Image Generation

Coming Soon Stable Diffusion / Flux Core API

This service will allow generating realistic visual assets from a text prompt. Output formats will include high-definition PNG/JPG assets, custom resolutions, and styles.

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

Video Generation

Coming Soon Text-to-Video / Image-to-Video Engine

Generate short-form video clips or animate existing image attachments using Sora/Runway styled pipelines.

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

Transcription & Audio

Coming Soon Whisper Core Transcription API

Translate, transcribe, and timestamp audio file uploads (mp3, wav, m4a) directly into text scripts.

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