Documentation

Quick Start

Get AI chat running on your website in 3 steps:

spark_ai-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

<script src="https://sparkbrain.app/chat.js"></script>

The widget uses domain-based auth - no API key needed in the client!

Registration

Create your SparkAI account in seconds:

1. Click "Get Started" or "Sign In" on the homepage
2. Authenticate with your Google account
3. Add your app (name + domain) in the dashboard
4. Copy your API key (shown once!)

Localhost is automatically allowed for development. Your API key is for server-side use only.

Widget Installation

Add the chat widget to any website with a single script tag:

<script src="https://sparkbrain.app/chat.js"></script>

The widget will appear as a floating button in the bottom-right corner.

Widget Configuration

Customize the widget with data attributes:

<script
  src="https://sparkbrain.app/chat.js"
  data-primary-color="#8b5cf6"
  data-title="My App"
  data-subtitle="AI Assistant"
  data-position="bottom-right"
  data-greeting="Hi! How can I help?"
></script>

Options

Local Development

On localhost, the widget cannot verify your domain via Origin header. Add your API key so it can load your app's config:

<script
  src="https://sparkbrain.app/chat.js"
  data-domain="myapp.com"
  data-api-key="spark_ai-..."
></script>
<!-- Remove data-api-key in production - not needed when deployed -->

Your API key is available in the dashboard under the API tab.

Identity Verification

When "Require identity verification" is enabled in the dashboard Data tab, sign the user's email on your server with your identity secret and pass the result to the widget. Requests without a valid hash are treated as anonymous.

// Server-side (Node.js / Next.js API route)
import crypto from 'node:crypto';

const userHash = crypto
  .createHmac('sha256', process.env.SPARK_AI_IDENTITY_SECRET)
  .update(user.email)
  .digest('hex');

<script
  src="https://sparkbrain.app/chat.js"
  data-user-email="[email protected]"
  data-user-hash="<userHash from your server>"
></script>
<!-- Or after login: SparkAI.setUser(email, name, userHash) -->

Never expose the identity secret in client-side code - compute the hash on your server only.

Framework Integration

React

import { useEffect } from 'react';

export function ChatWidget({ user }) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://sparkbrain.app/chat.js';
    script.async = true;
    if (user?.email) script.dataset.userEmail = user.email;
    document.body.appendChild(script);
    return () => script.remove();
  }, []);
  return null;
}

Next.js

'use client';
import Script from 'next/script';

export function ChatWidget({ user }) {
  return (
    <Script
      src="https://sparkbrain.app/chat.js"
      strategy="lazyOnload"
      data-user-email={user?.email}
    />
  );
}

REST API

For server-side integration, use the chat endpoint with your API credentials:

Authentication (via Headers)

X-App-ID: your-app-domain.com
X-Api-Key: spark_ai-your-api-key-here

Or pass credentials in the request body (headers take precedence).

Request Body

{
  "messages": ["Hello!", "How are you?"],  // Simple string array
  "appId": "your-app-domain.com",  // Required if not in headers
  "appSecret": "spark_ai-...",     // Required if not in headers
  "model": "llama-3.3-70b-versatile",  // Optional (this is default)
  "userEmail": "[email protected]",     // Optional (for user-level rate limiting)
  "sessionId": "unique-session-id",    // Optional (for conversation history)
  "max_tokens": 300,                   // Optional
  "temperature": 0.7                   // Optional
}

Security: Messages are automatically assigned role: "user" server-side. Clients cannot inject system messages.

Note: userEmail is optional. If omitted, rate limiting applies per-app instead of per-user.

Response

{
  "success": true,
  "response": "Hi! How can I help you today?"
}

Note: Usage and rate limit data are not included in responses to minimize bandwidth. Check your dashboard for detailed analytics and usage tracking.

The widget doesn't need API credentials - it authenticates via your registered domain automatically.

API Examples

cURL (Headers)

curl -X POST https://sparkbrain.app/api/chat \
  -H "Content-Type: application/json" \
  -H "X-App-ID: bottled.email" \
  -H "X-Api-Key: spark_ai-your-api-key-here" \
  -d '{"messages":["Hello!"]}'

JavaScript (Server-side)

const response = await fetch('https://sparkbrain.app/api/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-App-ID': 'bottled.email',
    'X-Api-Key': 'spark_ai-your-api-key-here'
  },
  body: JSON.stringify({
    messages: ['Hello!', 'How can you help me?']
  })
});
const data = await response.json();
console.log(data.response);

Python

import requests

response = requests.post(
    'https://sparkbrain.app/api/chat',
    headers={
        'Content-Type': 'application/json',
        'X-App-ID': 'bottled.email',
        'X-Api-Key': 'spark_ai-your-api-key-here'
    },
    json={
        'messages': ['Hello!', 'What can you do?']
    }
)
data = response.json()
print(data['response'])

Alternative: Credentials in Body

curl -X POST https://sparkbrain.app/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "bottled.email",
    "appSecret": "spark_ai-your-api-key-here",
    "messages": ["Hello!"]
  }'

Voice API

Standalone voice endpoints for game engines, video tools, and pay-as-you-go integrations. Authenticate with your API key via the X-Api-Key header.

Text-to-Speech

Convert text to audio. Returns binary audio data. Free on all tiers (14 languages, 28 voices). Premium voices (ElevenLabs) available on Supernova.

Request Body (JSON)

{
  "text": "Hello world",       // Required (max 5000 chars)
  "lang": "en",                // Optional (ISO 639-1, default "en")
  "gender": "female",          // Optional ("male" or "female")
  "voice": "en-US-AvaMultilingualNeural",  // Optional (override)
  "format": "mp3",             // Optional ("mp3", "webm", "wav")
  "provider": "edge"           // Optional ("edge", "elevenlabs")
}

Response

Binary audio with headers:

Content-Type: audio/mpeg
X-Voice-Used: en-US-AvaMultilingualNeural
Cache-Control: no-store

Formats: mp3 (default, universal), webm (smallest, Opus codec), wav (lossless).

Example

curl -X POST https://sparkbrain.app/api/voice/tts \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: spark_ai-your-key" \
  -d '{"text":"Hello world","format":"mp3"}' \
  --output speech.mp3

Speech-to-Text

Transcribe audio to text using Whisper. Requires Cortex plan or higher.

Request (multipart/form-data)

Response (JSON)

{
  "success": true,
  "text": "Hello world",
  "language": "en"
}

Example

curl -X POST https://sparkbrain.app/api/voice/stt \
  -H "X-Api-Key: spark_ai-your-key" \
  -F "[email protected]" \
  -F "denoise=true"

Voice Conversion

Transcribe audio, detect the speaker's gender and language, then re-synthesize with a matching voice. Requires Orbit plan or higher.

Request (multipart/form-data)

Response

Binary audio with headers:

Content-Type: audio/mpeg
X-Transcript: Hello%20world
X-Voice-Used: en-US-AndrewMultilingualNeural
Cache-Control: no-store

Pipeline: Input audio is denoised (RNNoise), transcribed (Whisper), pitch-analyzed for gender, then re-synthesized with the closest matching voice from 28 Microsoft Neural voices across 14 languages.

Voice Translation

Translate spoken audio into another language and re-synthesize it as speech. Requires Orbit plan or higher.

Request (multipart/form-data)

Response

Binary audio with headers:

Content-Type: audio/mpeg
X-Transcript: Hello%20world
X-Source-Language: es
X-Voice-Used: en-US-AvaMultilingualNeural
Cache-Control: no-store

Pipeline: Source audio is transcribed (auto-detect language), translated via AI chat, then synthesized in the target language with a gender-matched voice.

Bring Your Own Key

Use your own AI API key instead of SparkAI's shared quota. Your key is encrypted at rest (AES-256-GCM) and never exposed in client code. Available on all tiers.

Setup

1. Get your AI provider API key (e.g. from your provider's console)
2. Open your app settings in the SparkAI dashboard
3. Paste the key into the API Key field and save

How it works

• All chat and voice requests use your own account for token consumption
• SparkAI still handles auth, rate limiting, moderation, and delivery
• Platform request limits still apply (per your plan tier)
• Remove the key anytime to switch back to SparkAI's shared quota

API Configuration

curl -X PUT "https://sparkbrain.app/api/dashboard/apps?id=YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=..." \
  -d '{"action":"update","byokApiKey":"gsk_your_key_here"}'

Security: Your key is encrypted before storage and decrypted only at request time. It never appears in client code, logs, or API responses.

Playground

Try the chat widget right here! Click the button in the bottom-right corner.

Customize Live Preview

Icon

Color

Title

Subtitle

Position

Shareable Conversations

Let your users share AI conversations via a public link. Each shared conversation renders as a clean read-only page with OG meta tags for social previews.

Generate a share link

POST /api/widget/share
Content-Type: application/json

{
  "sessionId": "ses_abc123",
  "domain": "yoursite.com"
}

// Response
{
  "success": true,
  "shareToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}

The share link is: https://sparkbrain.app/share/{shareToken}

Share tokens are idempotent - the same conversation always returns the same token. The share button is built into the widget automatically.

Fetch a shared conversation (public)

GET /api/share/{token}

// Response
{
  "success": true,
  "conversation": {
    "appName": "My App",
    "domain": "myapp.com",
    "messageCount": 6,
    "messages": [
      { "role": "user", "content": "How do I reset my password?" },
      { "role": "assistant", "content": "Go to Settings > Security..." }
    ]
  }
}

Conversation Summaries

Generate a 1-2 sentence AI summary of any conversation, optimized for social sharing.

POST /api/widget/summary
Content-Type: application/json

{
  "sessionId": "ses_abc123",
  "domain": "yoursite.com"
}

// Response
{
  "success": true,
  "summary": "A walkthrough of password reset and 2FA setup for enterprise accounts."
}

Rate-limited to 1 summary per session per minute to prevent abuse.

Widget Branding

The widget init response includes a branding object that controls the "Powered by SparkAI" footer.

<!-- Hide the footer badge (any tier) -->
<script src="https://sparkbrain.app/chat.js" hide-footer="true"></script>

Plans & Limits

Limits reset daily at midnight UTC. Per-user limits also apply (50-500 msgs/day depending on plan). View full pricing.