API Keys — FAE

Your Workspace Keys

Each workspace has a unique API key. Use it in the x-api-key request header. Regenerating a key immediately invalidates the previous one.

Keep your API key secret. Never expose it in client-side JavaScript. Use it only from your own server or backend. If compromised, regenerate it immediately.

Overview

Base URL

https://faeframeworks.com/api

Response Format

application/json

Auth Header (API key)

x-api-key: <your-key>

API Status

checking…

JSON endpoints use ISO 8601 timestamps and MongoDB ObjectIds. Voice generation endpoints return binary audio/wav so they can be saved or streamed directly.

Authentication

API Key Auth — for external integrations

Pass your workspace API key in the x-api-key header on every request. Keys are generated per workspace from the panel above.

            
# Works on any workspace-scoped endpoint (characters, nfts, apps, stories, bots, media...)
curl https://faeframeworks.com/api/characters?workspace=WORKSPACE_ID \
  -H "x-api-key: YOUR_API_KEY"
          

Dual Auth — workspace-scoped routes

All workspace-scoped CRUD routes (characters, apps, stories, NFTs, bots, media, scenes) accept either method. Use API key from external servers, automation scripts, or embedded tools. Use session cookies when calling from the FAE frontend.

Endpoints labeled accept both an x-api-key header and a session cookie. Endpoints labeled are public-embed routes. Endpoints labeled require a logged-in user (TTS, tokens).

Error Responses

All errors return a JSON object with an error field describing the problem.

Code	Meaning	Common Cause
200 OK	Success	Request completed normally
201 Created	Resource created	POST returned new resource
400 Bad Request	Validation failed	Missing or invalid fields
401 Unauthorized	Not logged in	Session expired or missing
403 Forbidden	Invalid API key or no access	Wrong key, wrong workspace, or insufficient permissions
404 Not Found	Resource missing	Bad ID or deleted resource
409 Conflict	Result still processing	Generated audio is still being stored
429 Rate Limited	Too many requests	Wait for the `Retry-After` interval
500 Server Error	Internal error	Unexpected server-side failure
503 Unavailable	Service offline	Stripe not configured, no AI agents online

NFTs

Fetch public NFTs for a workspace. No user session required — just your workspace ID and API key.

GET /api/public/nfts?workspace={workspaceId} List public NFTs

Returns all NFTs in the workspace where public: true. Pass your API key in the x-api-key header.

Query Parameters

Name	Type	Required	Description
workspace	string	required	Your workspace ID (24-char hex)

Headers

Name	Type	Required	Description
x-api-key	string	required	Your workspace API key

JavaScript

cURL

                
const res = await fetch('/api/public/nfts?workspace=' + WORKSPACE_ID, {
  headers: { 'x-api-key': YOUR_API_KEY }
});
const nfts = await res.json();
// nfts ? Array of NFT objects
              

Payments Embed

Embed a FAE-powered Stripe checkout on any site. Create payment products in your workspace, then use these endpoints to surface them publicly and initiate checkout sessions — no Stripe keys on the client side.

Requires a connected Stripe account. Set up Stripe Connect from your workspace settings before accepting payments.

GET /api/payments/embed/product/{productId} Get product info

Returns public product details for embedding in a checkout widget. Pass your API key as x-api-key header or ?key= query param.

Path Parameters

Name	Type	Required	Description
productId	string	required	The product's ObjectId

JavaScript

cURL

                
const res = await fetch(`/api/payments/embed/product/${PRODUCT_ID}`, {
  headers: { 'x-api-key': YOUR_API_KEY }
});
const product = await res.json();
// { id, name, description, amount, currency, images }
              

POST /api/payments/embed/checkout Create Stripe checkout

Creates a Stripe Checkout session for a product. Returns a url to redirect the customer to. Pass API key in x-api-key header.

Request Body (JSON)

Name	Type	Required	Description
productId	string	required	ID of an active payment product
successUrl	string	required	Redirect URL after successful payment (https)
cancelUrl	string	required	Redirect URL if customer cancels (https)
customerEmail	string	optional	Pre-fill customer email in checkout
ref	string	optional	Custom reference string saved with the order

JavaScript

cURL

                
const res = await fetch('/api/payments/embed/checkout', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': YOUR_API_KEY
  },
  body: JSON.stringify({
    productId:  'PRODUCT_ID',
    successUrl: 'https://yoursite.com/success',
    cancelUrl:  'https://yoursite.com/cancel',
    ref:        'order_42'   // optional reference
  })
});
const { url } = await res.json();
window.location.href = url;  // redirect to Stripe Checkout
              

NFTs

Full CRUD for NFTs (masters, editions, collections). Accepts API key or session auth.

GET/api/nfts?workspace={workspaceId}List NFTs

Query Parameters

Name	Type	Required	Description
workspace	string	optional	Filter by workspace ID
collection	string	optional	Filter by collection ID

POST/api/nftsCreate NFT

Request Body (JSON)

Name	Type	Required	Description
workspace	string	required	Workspace ID
name	string	required	NFT name
nftKind	string	optional	`master`, `edition`, or `collection`
public	boolean	optional	Visible in public API (default: false)
mintCount	number	optional	For edition kind — bulk mint count

PUT/api/nfts/{id}Update NFT

Update any fields on an existing NFT. Send only the fields to change.

DELETE/api/nfts/{id}Delete NFT

Permanently deletes an NFT record. Returns {"success":true}.

Characters API KEY

Every lookup is constrained to the API key's workspace. The workspace is inferred from x-api-key, private memory is omitted from list results, and supplied workspace IDs cannot be used to cross tenant boundaries. Logged-in site callers may continue using the compatible /api/characters routes with a workspace ID.

AI Character profiles — traits, prompts, avatar, Ollama model assignment, memory.

GET/v1/characters?limit=100&skip=0List characters

Returns all characters for the workspace. Results are cached server-side (60s) and refreshed in the background — first call may be slower.

POST/v1/charactersCreate character

Key Body Fields

Name	Type	Required	Description
name	string	required	Character name
traits	string[]	optional	Personality trait list
background	string	optional	Character backstory
ollamaModel	string	optional	Default Ollama model for AI responses

POST/v1/characters/{id}/responsesGet AI response

Uses the current authenticated Ollama provider network. Chat credits are reserved before dispatch, settled using actual response tokens, and refunded on provider failure or timeout. The response includes token usage, usage.credits_charged, and X-Credits-Charged.

Requires at least one connected desktop provider with Ollama ready. Requests are limited to 8,000 input characters and 4,096 requested response tokens.

Request Body

Name	Type	Required	Description
text	string	required	User message
model	string	optional	Override Ollama model
max_tokens	integer	optional	Maximum response tokens, 1-4096; default 512

PATCH/v1/characters/{id}Update character

Updates supported fields only; workspace and internal metadata cannot be overwritten.

DELETE/v1/characters/{id}Delete character

Deletes only a character belonging to the API key's workspace and invalidates that workspace's cache.

Discord Character Bots SESSION OR API KEY

The easiest setup is in Workspace → Characters → select a character → Launch on Discord. Paste a Discord bot token once, click Launch, then click Add to Discord. Tokens are AES-256-GCM encrypted at rest, are never returned by the API, and can be replaced or disconnected at any time.

Each connected bot registers a global /chat message:… command and reconnects automatically after a normal server or Docker restart. It uses only Discord's standard Guilds intent, so the privileged Message Content intent is not needed. Replies use the Character API persona and normal metered chat credits.

POST/api/discord-character-botsConnect and launch

Validates the token with Discord, registers /chat, encrypts the token, and starts the Gateway connection. Repeating this request for the same character replaces its configuration and token.

Request Body

Name	Type	Required	Description
workspace	string	session only	Workspace ID; inferred and constrained when using `x-api-key`
characterId	string	required	A character owned by the authenticated workspace
token	string	required	Discord bot token; write-only and encrypted immediately
maxTokens	integer	optional	1–4096; default 512
allowedGuildIds	string[]	optional	Optional Discord server allowlist; empty allows every server that installs the bot

GET/api/discord-character-bots?workspace={workspaceId}&characterId={id}List connections and status

Returns identity, status, generated invite URL, response count, restrictions, and runtime state. The token and its fingerprint are always omitted.

PATCH/api/discord-character-bots/{id}Update limits or rotate token

Accepts maxTokens, allowedGuildIds, and an optional replacement token. A replacement token must belong to the same Discord application.

POST/api/discord-character-bots/{id}/startStart or reconnect

Starts the encrypted saved connection. Enabled bots also start automatically when the FAE backend starts.

POST/api/discord-character-bots/{id}/stopStop

Stops reconnects without deleting the saved encrypted configuration.

DELETE/api/discord-character-bots/{id}Disconnect and forget token

Stops the process and deletes FAE's encrypted credential. It does not delete the application in Discord.

Apps

Create and manage hosted web apps. Files are stored on GCS and served via Traefik.

GET/api/apps?workspace={workspaceId}List apps

Returns all apps in the workspace.

GET/api/apps/templatesList templates

Returns all available app starter templates.

POST/api/appsCreate app

Request Body

Name	Type	Required	Description
name	string	required	App name (auto-generates slug)
workspace	string	required	Workspace ID
templateId	string	optional	Starter template ID
githubRepo	string	optional	GitHub repo URL to link
domain	string	optional	Custom domain (default: slug.faeframeworks.com)

GET/api/apps/{id}/filesList app files (GCS)

Returns list of file paths in Google Cloud Storage for this app.

POST/api/apps/{id}/uploadUpload app file

Multipart form upload. Sends a file to GCS under the app's prefix.

Form Fields

Name	Type	Required	Description
file	File	required	The file binary
filename	string	optional	Override destination filename

Stories

Book Studio stories — create, read, update, and delete story documents.

GET/api/stories?workspace={workspaceId}List stories

Returns all stories in the workspace.

GET/api/stories/{id}Get story

Returns a single story by ID.

POST/api/storiesCreate story

Creates a new story. Pass all story fields in the request body.

PUT/api/stories/{id}Update story

Updates the story. Auto-sets updatedAt.

DELETE/api/stories/{id}Delete story

Permanently deletes a story.

Bots

Automation bots with node/edge pipelines, trigger configs, and run logs.

GET/api/bots?workspace={workspaceId}List bots

Returns bots for the workspace (nodes/edges/logs are excluded from list response).

GET/api/bots/{id}Get bot

Returns full bot including pipeline nodes and edges.

POST/api/botsCreate bot

Creates a new bot. Pass name, workspace, and pipeline config in body.

POST/api/bots/{id}/runRun bot

Starts the bot pipeline. Returns immediately with {"status":"running"}; pipeline runs async.

POST/api/bots/{id}/stopStop bot

Sets bot status to idle.

GET/api/bots/{id}/logsGet run logs

Returns {"logs":[...],"status":"idle|running|error"} for the bot.

DELETE/api/bots/{id}/logsClear logs

Clears all run log entries for the bot.

DELETE/api/bots/{id}Delete bot

Permanently deletes the bot and all its data.

Media Files

Workspace file records for images, videos, audio, documents, and 3D models. Files are stored in Google Cloud Storage; these endpoints manage the metadata records.

Replace {type} with one of: images, videos, audios, documents, models.

GET/api/{type}?workspace={workspaceId}List files

Returns all files of the given type in the workspace, sorted newest first.

POST/api/{type}Register file

Creates a file record after you've uploaded the binary to GCS directly. The caller must be a workspace editor.

Request Body

Name	Type	Required	Description
workspace	string	required	Workspace ID
url	string	required	GCS public URL
name	string	optional	Display name
size	number	optional	File size in bytes
mimeType	string	optional	MIME type

PUT/api/{type}/{id}Update file

Update metadata fields for a file record (e.g. rename). Caller must be a workspace editor.

DELETE/api/{type}/{id}Delete file

Deletes the DB record and removes the file from GCS. Returns {"success":true,"freed":<bytes>}.

GET/api/models/{id}/contentProxy-stream GLB

Streams the GLB binary from GCS through the FAE server (bypasses browser CORS restrictions for the 3D viewer).

Generative API API KEY

Production REST access to the FAE provider network for chat completions, Kokoro speech, Fooocus image generation, and Chatterbox voice cloning. Requests are isolated to the workspace belonging to your API key.

Call these routes from your server and send x-api-key. Use Idempotency-Key when creating images so a network retry cannot create the same job twice. Complete schema: OpenAPI 3.1 JSON.

Credit pricing

Purchased credits are currently $0.05 each. Generation requests reserve credits before dispatch, settle the final amount on success, and automatically refund failed requests. Current defaults:

Service	Credits	Approx. purchased-credit cost
Chat	0.10 / 1K tokens; 0.05 minimum	$0.005 / 1K tokens
Kokoro speech	0.50 / 1K characters; 0.10 minimum	$0.025 / 1K characters
Chatterbox cloning	0.80 / 1K characters; 0.20 minimum	$0.04 / 1K characters
Fooocus image	0.15 / 0.35 / 0.65 per output MP	$0.0075 / $0.0175 / $0.0325 for Lightning / Speed / Quality
Image input	+0.10 per input MP	+$0.005 per input MP

The website AI workspace and code-editor assistant use these same rates and the active workspace balance. REST clients receive 402 insufficient_credits when a reservation cannot be funded. Audio responses include X-Credits-Charged; chat and image JSON include their settled charge.

GET/v1/pricingPUBLICCurrent credit rates

Returns the live configurable rates used by the server and the purchased-credit USD value.

GET/v1/creditsAPI KEYWorkspace credit balance

Returns total, monthly, and permanent purchased credits for the API key's workspace. Generation routes return 402 insufficient_credits when funds are unavailable.

GET/v1/credits/usage?limit=20&skip=0API KEYCharge and refund history

Lists reserved, settled, and refunded API usage with service, resource ID, charged credits, and calculation metadata.

Chat quick start

curl https://www.faeframeworks.com/v1/chat/completions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"fae-text","messages":[{"role":"user","content":"Explain edge AI in one paragraph."}]}'

Image quick start

curl https://www.faeframeworks.com/v1/images/generations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: project-42-hero-v1" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A bioluminescent forest city at night","size":"1344x768","n":2,"performance":"Quality","wait":true}'

GET/v1/modelsPUBLICCapabilities and ready nodes

Lists chat, image, speech, and voice-cloning capabilities with their current ready-node counts.

POST/v1/chat/completionsAPI KEYOpenAI-style chat completion

Accepts 1–50 system, user, and assistant messages, up to 32,000 total characters. Responses use the familiar chat.completion, choices, and usage structure. Streaming is not currently supported.

Name	Type	Required	Description
messages	array	required	Conversation messages with `role` and `content`
model	string	optional	`fae-text` selects the provider's available Ollama model; a specific Ollama model name may also be requested
max_tokens	integer	optional	1–4096; default 512

GET/v1/audio/voicesPUBLICKokoro voices and availability

Lists the built-in Kokoro voice IDs, labels, current availability, and ready-node count.

POST/v1/audio/speechAPI KEYGenerate Kokoro speech

OpenAI-style text-to-speech endpoint returning audio/wav bytes. The generation ID is returned in X-Generation-Id.

curl https://www.faeframeworks.com/v1/audio/speech \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"kokoro","input":"Welcome to the FAE network.","voice":"af_heart","speed":1}' \
  --output speech.wav

Name	Type	Required	Description
input	string	required	Text to synthesize, up to 2,000 characters
voice	string	optional	A voice ID from `/v1/audio/voices`; default `af_heart`
speed	number	optional	0.5 to 2.0; default 1.0
response_format	string	optional	Currently `wav`

GET/v1/images/statusPUBLICFooocus availability

Returns whether any Fooocus provider is ready and the number of ready nodes.

POST/v1/images/generationsAPI KEYCreate an image generation

Returns 202 with a persistent job by default. Set wait:true to wait up to wait_timeout seconds for a completed 200 response. Jobs remain queued safely when no provider is ready.

Name	Type	Required	Description
prompt	string	required	Generation prompt, up to 4,000 characters
negative_prompt	string	optional	Elements to avoid
size	string	optional	For example `1024x1024` or `1344x768`; dimensions must be multiples of 64
n	integer	optional	1–4 images
performance	string	optional	`Lightning`, `Speed`, or `Quality`
styles	array	optional	Up to five Fooocus style names
loras	array	optional	Up to five `{name, weight}` objects
seed	integer	optional	`-1` for random
output_format	string	optional	`webp`, `png`, or `jpeg`
response_format	string	optional	`url` (one-hour signed URL plus authenticated proxy) or `b64_json`
input_image	data URL	optional	PNG/JPEG/WebP up to 10 MB for image-to-image generation

GET/v1/images/generations?limit=20&skip=0API KEYList image jobs

Lists only the image jobs created by this workspace API key. Base64 image bodies are omitted from list responses; fetch the individual generation to retrieve them.

GET/v1/images/generations/{generation_id}API KEYPoll status and results

Returns queued, processing, completed, or failed, plus result data when ready.

GET/v1/images/generations/{generation_id}/content/{index}API KEYAuthenticated image download

Streams image bytes through a tenant-checked proxy. Continue sending x-api-key.

DELETE/v1/images/generations/{generation_id}API KEYDelete job and stored images

Removes the workspace-owned job and its generated GCS objects. A currently processing job returns 409 and can be deleted after completion.

Default limits are 30 chat completions, 20 speech generations, and 10 image generations per workspace per minute. Read X-RateLimit-Remaining, preserve X-Request-Id in support logs, and honor Retry-After after a 429.

Text-to-Speech

Kokoro TTS via the AI relay. Requires a connected FAE desktop app with Kokoro loaded.

GET/api/tts/statusPUBLICTTS availability

Returns TTS availability and available voices. No auth required.

                // Response when ready
{ "available": true, "state": "ready", "voices": [
  { "id": "af_heart", "label": "Heart (US Female)" },
  { "id": "af_bella", "label": "Bella (US Female)" },
  // ... 6 more voices
]}
              

POST/api/ttsGenerate speech

Returns audio/wav binary. Routed through AI relay to Electron. Persists a TTSJob record.

Request Body

Name	Type	Required	Description
text	string	required	Text to synthesize (max 2000 chars)
voice	string	optional	Voice ID (default: `af_heart`)
speed	number	optional	Speed multiplier 0.5–2.0 (default: 1.0)
workspaceId	string	required	Workspace charged for the generation

Chatterbox Voice API API KEY

Reusable voice cloning powered by Chatterbox nodes on the FAE provider network. Upload a reference clip once, then generate WAV speech with its voice_id.

Keep workspace API keys on your server and send them in x-api-key (xi-api-key is also accepted). Saved voices and generations are isolated to the key's workspace. Machine-readable schema: OpenAPI 3.1 JSON.

Quick start

            
# 1. Save a reusable voice
curl -X POST https://www.faeframeworks.com/v1/voices \
  -H "x-api-key: YOUR_API_KEY" \
  -F "name=Narrator" \
  -F "audio=@reference.wav"

# 2. Generate speech using voice_id from step 1
curl -X POST https://www.faeframeworks.com/v1/text-to-speech/VOICE_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Welcome to the FAE network."}' \
  --output speech.wav
          

GET/v1/statusPUBLICNetwork availability

Returns available, state (offline, loading, or ready), and ready_nodes.

POST/v1/voicesAPI KEYCreate a saved voice

Send multipart/form-data. WAV, MP3, OGG, FLAC, and M4A clips up to 10 MB are accepted. The response includes a reusable voice_id.

Name	Type	Required	Description
name	string	required	Display name, up to 100 characters
audio	file	required	Reference clip; `files` is accepted as an alias
description	string	optional	Voice description
labels	JSON	optional	String key/value metadata
exaggeration	number	optional	Default expressiveness, 0–1
cfg_weight	number	optional	Default reference adherence, 0–1
turbo	boolean	optional	Use the faster Turbo model by default

GET/v1/voicesAPI KEYList saved voices

Returns {"voices": [...], "has_more": false} for the key's workspace.

GET/v1/voices/{voice_id}API KEYGet voice details

Returns voice metadata and default generation settings.

DELETE/v1/voices/{voice_id}API KEYDelete a voice

Deletes the saved reference clip. Existing generation history remains available.

POST/v1/text-to-speech/{voice_id}API KEYGenerate cloned speech

Send JSON and receive raw audio/wav. The X-Generation-Id header identifies the persisted result. Text is limited to 2,000 characters.

{
  "text": "Your script goes here.",
  "output_format": "wav",
  "voice_settings": {
    "exaggeration": 0.5,
    "cfg_weight": 0.5,
    "turbo": true
  }
}

Default rate limit: 20 generations per workspace per minute. Read X-RateLimit-Remaining and honor Retry-After after a 429.

GET/v1/generations?limit=20&skip=0API KEYGeneration history

Lists this workspace's generations, newest first. Maximum page size is 100.

GET/v1/generations/{generation_id}API KEYGeneration metadata

Returns status, voice ID, timestamps, text, and stored audio URL.

GET/v1/generations/{generation_id}/audioAPI KEYDownload generated WAV

Streams the stored WAV. A 409 means storage is still completing; retry shortly.

Node.js example

import { writeFile } from 'node:fs/promises';
const response = await fetch('https://www.faeframeworks.com/v1/text-to-speech/VOICE_ID', {
  method: 'POST',
  headers: { 'x-api-key': process.env.FAE_API_KEY, 'content-type': 'application/json' },
  body: JSON.stringify({ text: 'Hello from FAE.', voice_settings: { turbo: true } })
});
if (!response.ok) throw new Error(await response.text());
await writeFile('speech.wav', Buffer.from(await response.arrayBuffer()));

Scenes

3D scene definitions for the Scene Builder.

GET/api/scenes?workspace={workspaceId}List scenes

Returns all scenes for the workspace.

POST/api/scenesCreate scene

Creates a new scene. Pass scene definition fields in the body.

PUT/api/scenes/{id}Update scene

Updates an existing scene record.

DELETE/api/scenes/{id}Delete scene

Permanently deletes the scene.

Tokens

Token tracking and on-chain price data via Moralis.

GET/api/tokensList tokens

Returns all token entries.

POST/api/tokensCreate token

Registers a new token record.

GET/api/tokens/getTokenPrice?tokenAddress={addr}&chain={chain}Get price (Moralis)

Query Parameters

Name	Type	Required	Description
tokenAddress	string	required	On-chain token contract address
chain	string	required	e.g. `solana`

API Tester

Run live requests against the FAE API and inspect responses in real time.

Workspace

Select an endpoint

Public

Workspace — Content

Workspace ? Files

Payments Embed

New AI Bot

Story Bot

New Community

Chat Group

New Token

NFT Collection

Book Studio

Asset Studio

Code Editor