API Documentation

Everything you need to build with FusionAI. One API for multiple models with clear billing, routing, and production-grade controls.

Overview

Base URL for all requests:

https://<base_url>

Versioning

FusionAI uses date-stable API versions. Breaking changes are announced 90 days in advance and released under a new version. The current version is v1.

Authentication

All API requests require a project API key in the Authorization header.

Authorization: Bearer fusionai_live_xxx

Test keys

Use test keys for development and staging. Test requests are never billed and responses include a test flag in the usage object.

Authorization: Bearer fusionai_test_xxx

Quick start

curl https://<base_url>/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fusionai_live_xxx" \
  -d '{
    "model": "claude-3-opus",
    "messages": [
      { "role": "user", "content": "Summarize this invoice." }
    ],
    "temperature": 0.3
  }'

SDKs

Official SDKs are available for JavaScript/TypeScript, Python, and Go.

# JavaScript / TypeScript
npm install @fusionai/sdk

# Python
pip install fusionai

# Go
go get github.com/fusionai/sdk-go

Core endpoints

POST /chat/completions — chat and tool use
POST /embeddings — vector embeddings
POST /images — image generation
GET /models — list available models
GET /usage — usage and credit consumption

Available models

Provider	Model ID	Best for
Anthropic	claude-3-opus	Long-context reasoning
Anthropic	claude-3-sonnet	Balanced performance
OpenAI	gpt-4	Coding and tool use
OpenAI	gpt-3.5-turbo	Low-latency chat
Google	gemini-pro	Multimodal workflows

Chat completions

Create a chat completion by sending a POST request to /chat/completions.

Request parameters

model (string) — model identifier, e.g. claude-3-opus
messages (array) — ordered chat messages with role and content
temperature (number) — randomness control, default 0.7
max_tokens (number) — cap response tokens

POST https://<base_url>/chat/completions
Content-Type: application/json
Authorization: Bearer fusionai_live_xxx

{
  "model": "claude-3-opus",
  "messages": [
    {
      "role": "user",
      "content": "Explain quantum computing in simple terms"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 500
}

Tool calling

Define tools to let models call functions during a completion.

{
  "model": "gpt-4",
  "messages": [{ "role": "user", "content": "Find my last invoice." }],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_invoices",
      "description": "Fetch invoices for a customer",
      "parameters": { "type": "object", "properties": { "customerId": { "type": "string" } } }
    }
  }]
}

Streaming responses

Set stream to true to receive incremental tokens.

POST https://<base_url>/chat/completions
Content-Type: application/json
Authorization: Bearer fusionai_live_xxx

{
  "model": "gpt-4",
  "stream": true,
  "messages": [{ "role": "user", "content": "Draft a product brief." }]
}

Embeddings

POST https://<base_url>/embeddings
Content-Type: application/json
Authorization: Bearer fusionai_live_xxx

{
  "model": "text-embedding-3-large",
  "input": ["Search this knowledge base", "Summarize this document"]
}

{
  "object": "list",
  "data": [{ "index": 0, "embedding": [0.0123, 0.9981] }],
  "usage": { "total_tokens": 42, "credits_used": 0.01 }
}

Image generation

POST https://<base_url>/images
Content-Type: application/json
Authorization: Bearer fusionai_live_xxx

{
  "model": "image-gen-2",
  "prompt": "A futuristic skyline at sunset",
  "size": "1024x1024"
}

{
  "created": 1712345678,
  "data": [{ "url": "https://cdn.fusionai.cloud/images/abc.png" }],
  "usage": { "credits_used": 10 }
}

Model routing

Control quality, latency, or spend with routing and fallbacks.

{
  "model": "claude-3-opus",
  "routing": {
    "fallbacks": ["gpt-4", "gemini-pro"],
    "budget": "balanced"
  }
}

Reliability

Idempotency: Use an Idempotency-Key header to safely retry without double-charging.

Pagination: List endpoints use cursor-based pagination with limit and after.

Retries: Retry on 429 and 5xx errors with exponential backoff (max 3 retries).

Timeouts: Use a 30s client timeout for non-streaming and 120s for streaming.

Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7

GET https://<base_url>/usage?limit=100&after=usage_abc123

Usage & billing

Track credit consumption and export usage for finance and forecasting.

GET https://<base_url>/usage?from=2025-01-01&to=2025-01-31

{
  "period": { "from": "2025-01-01", "to": "2025-01-31" },
  "credits_used": 12840,
  "top_models": [{ "model": "gpt-4", "credits": 6021 }]
}

Webhooks

Receive notifications for spend thresholds and billing events.

POST https://<base_url>/webhooks
{
  "url": "https://example.com/webhooks/fusionai",
  "events": ["credit.threshold", "invoice.paid"]
}

Webhook signing: Verify signatures using the FusionAI-Signature header and your webhook secret.

Error codes

The API uses standard HTTP status codes. Errors are returned in JSON format.

{
  "error": {
    "message": "Insufficient credits",
    "type": "insufficient_credits",
    "code": 402
  }
}

400 — invalid_request
401 — unauthorized
402 — insufficient_credits
429 — rate_limit_exceeded
500 — internal_error

Rate limits

Starter Plan: 100 requests per minute
Professional Plan: 600 requests per minute
Business Plan: 2,500 requests per minute
Enterprise: Custom limits

Support

Support: support@fusionai.cloud. Billing: billing@fusionai.cloud. Sales: sales@fusionai.cloud.