Documentation

Add AI chat to your app in minutes

Quick Start

Get AI chat running on your website in 3 steps:

1

Sign in with Google

Click "Get Started" on the homepage to sign in.

2

Register your app

Add your app in the dashboard. You'll get an API key like:

spark_ai-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
3

Add the widget

Paste this before </body>:

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

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

Registration

Create your SparkBrain 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:

HTML
<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

AttributeDefaultDescription
data-primary-color#818cf8Theme color (hex)
data-titlePage titleHeader title
data-subtitleAI AssistantHeader subtitle
data-positionbottom-rightbottom-right or bottom-left
data-greetingTime-basedInitial greeting message
data-user-email-User email for context
data-user-hash-HMAC-SHA256 of the user email, signed server-side with your identity secret (required when identity verification is enabled)
data-user-name-User display name
data-api-key-API key - required for local dev (localhost), not needed in production
data-debugoffLog widget diagnostics to the browser console while troubleshooting. Off by default, and the diagnostics never include the user's email or any other identifier

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_BRAIN_IDENTITY_SECRET)
  .update(user.email)
  .digest('hex');
<script
  src="https://sparkbrain.app/chat.js"
  data-user-email="jane@myapp.com"
  data-user-hash="<userHash from your server>"
></script>
<!-- Or after login: SparkWidget.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:

POST https://sparkbrain.app/api/chat

Authentication (via Headers)

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

Headers are the only way to authenticate this endpoint. Credentials in the request body are ignored and the call returns 403.

Request Body

{
  "messages": ["Hello!", "How are you?"],  // Simple string array
  "model": "...",                      // Optional, top plan only (see below)
  "userEmail": "user@example.com",     // 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'])

Choosing the model

Your plan picks the model, so model is ignored on every plan except the top one, which may override it. The values that plan accepts are listed in your dashboard. Requests that read your database always use the stronger model regardless of plan, because the weaker one cannot reason over tables.

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

POST https://sparkbrain.app/api/voice/tts

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

POST https://sparkbrain.app/api/voice/stt

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

Request (multipart/form-data)

FieldTypeDescription
audioFileAudio file (max 25 MB). WAV, MP3, OGG, WebM supported.
languagestringOptional language hint for Whisper.
denoisestringSet to "true" to apply RNNoise before transcription.

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 "audio=@recording.wav" \
  -F "denoise=true"

Voice Conversion

POST https://sparkbrain.app/api/voice/convert

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)

FieldTypeDescription
audioFileAudio file (max 25 MB).
formatstringOutput format: "mp3", "webm", or "wav".
voicestringOptional. Force a specific voice (skips auto-detect).

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

POST https://sparkbrain.app/api/voice/translate

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

Request (multipart/form-data)

FieldTypeDescription
audioFileAudio file (max 25 MB). WAV, MP3, OGG, WebM supported.
targetLangstringTarget language code (ISO 639-1, default "en").
formatstringOutput format: "mp3", "webm", or "wav".

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.

Avatar API

Give your app a presenter: a character who can be shown as a looping clip, or rendered actually saying a line with real lip-sync. Pick one of the ready-made presenters on the Avatar tab of your dashboard - or be the presenter yourself, by uploading a headshot and recording a few seconds of speech - then use it from anywhere with the same X-Api-Key header as the rest of the API.

Your Presenter

GET https://sparkbrain.app/api/avatar

Returns the character as your apps should see it, with nothing about how it was made.

Response

{
  "character": {
    "enabled": true,                 // false until a character is rendered and switched on
    "name": "Ada",
    "style": "realistic",            // "realistic", "toon" or "illustrated"
    "voice": "en-GB-SoniaNeural",
    "poster": "https://.../still.jpg",   // single frame, for a placeholder
    "idleClip": "https://.../idle.mp4",  // seamless loop, mouth closed
    "talkClip": "https://.../talk.mp4",  // seamless loop, mouth moving
    "sourceClip": "https://.../src.mp4",
    "maxSpeechChars": 420            // longest line one render can speak
  },
  "rendering": "available",          // "unconfigured" if this deployment cannot render
  "storage": "durable"               // "ephemeral" means the clip URLs above expire within the hour
}

Always check enabled. An app with no presenter returns enabled: false rather than an error, so your integration can simply fall back to whatever it showed before.

Make Them Speak

POST https://sparkbrain.app/api/avatar/speak

Send a line of text and get back a clip of your presenter saying it, mouth matched to the words. The voice is synthesised here, so you never send audio or pick a voice provider.

Request Body (JSON)

{
  "text": "Welcome to the tour."   // Required (max 420 chars)
}

Response

A render takes minutes, so the call returns a job to poll:

{ "jobId": "abc123~speech/9f2c...", "status": "pending" }

A line this presenter has already said comes back finished instead, with no job and no second charge:

{ "status": "done", "url": "https://.../said.mp4", "cached": true }

Polling

GET https://sparkbrain.app/api/avatar/speak?id=JOB_ID
{ "status": "pending" }
{ "status": "done", "url": "https://.../said.mp4", "ephemeral": false }
{ "status": "failed", "error": "Render failed" }

Example

JOB=$(curl -s -X POST https://sparkbrain.app/api/avatar/speak \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: spark_ai-your-key" \
  -d '{"text":"Welcome to the tour."}' | jq -r .jobId)

curl -s "https://sparkbrain.app/api/avatar/speak?id=$JOB" \
  -H "X-Api-Key: spark_ai-your-key"

Download what you get. When ephemeral is true the URL is temporary - save the file rather than linking to it. Identical text reuses the stored render, so writing one script and rerunning it costs one render, not one per run.

Errors

400  text missing, or longer than maxSpeechChars
409  this app has no rendered character yet
503  avatar rendering is not configured on this deployment

Bring Your Own Key

Use your own AI API key instead of SparkBrain'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 SparkBrain 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
  • SparkBrain 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 SparkBrain's shared quota

API Configuration

cURL
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

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 SparkBrain" footer.

TierBadge visibleOverride
FreeYes-
Paid (Cortex+)No-
AnyNohide-footer="true" on script tag
<!-- Hide the footer badge (any tier) -->
<script src="https://sparkbrain.app/chat.js" hide-footer="true"></script>

Plans & Limits

PlanPriceAppsDaily msgsMonthly msgsHighlights
SparkFree11001,000Widget + TTS, 14 languages
Cortex$29/mo12005,000REST API, STT, phone AI, magic setup
Orbit$79/mo350020,000Database answers, voice convert + translate, live chat
Supernova$199/moUnlimited3,00050,000Premium model, premium voices, full moderation

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