Documentation
Add AI chat to your app in minutes
Quick Start
Get AI chat running on your website in 3 steps:
Sign in with Google
Click "Get Started" on the homepage to sign in.
Register your app
Add your app in the dashboard. You'll get an API key like:
spark_ai-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
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:
- Click "Get Started" or "Sign In" on the homepage
- Authenticate with your Google account
- Add your app (name + domain) in the dashboard
- 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
| Attribute | Default | Description |
|---|---|---|
data-primary-color | #818cf8 | Theme color (hex) |
data-title | Page title | Header title |
data-subtitle | AI Assistant | Header subtitle |
data-position | bottom-right | bottom-right or bottom-left |
data-greeting | Time-based | Initial 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-debug | off | Log 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:
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
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
https://sparkbrain.app/api/voice/stt
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 "audio=@recording.wav" \
-F "denoise=true"
Voice Conversion
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)
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
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)
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
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
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
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
- Get your AI provider API key (e.g. from your provider's console)
- Open your app settings in the SparkBrain dashboard
- 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 -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
Plans & Limits
| Plan | Price | Apps | Daily msgs | Monthly msgs | Highlights |
|---|---|---|---|---|---|
| Spark | Free | 1 | 100 | 1,000 | Widget + TTS, 14 languages |
| Cortex | $29/mo | 1 | 200 | 5,000 | REST API, STT, phone AI, magic setup |
| Orbit | $79/mo | 3 | 500 | 20,000 | Database answers, voice convert + translate, live chat |
| Supernova | $199/mo | Unlimited | 3,000 | 50,000 | Premium 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.