Supabase Edge Functions: WZRD Backend API Reference

WZRD Studio’s backend is built entirely on Supabase Edge Functions — Deno-based serverless functions deployed at the edge and called directly from the Electron desktop app. Each function handles a focused responsibility: authentication, billing, AI model proxying, asset management, or social publishing. All functions share a common authentication pattern and CORS configuration, and they are addressable at {VITE_SUPABASE_URL}/functions/v1/{function-name}.

Base URL: https://ixkkrousepsiorwlaycp.supabase.co/functions/v1/In the app, this value comes from the VITE_SUPABASE_URL environment variable.

All requests require Authorization: Bearer <supabase-jwt> unless noted otherwise. Functions return Content-Type: application/json for standard responses and text/event-stream for SSE endpoints.

Authentication

POST /functions/v1/wallet-auth — Wallet Signature → Supabase JWT

The only public edge function (no JWT required). Verifies an EIP-191 wallet signature using viem, then upserts the user in Supabase Auth and returns a full session.This is the primary sign-in path for WZRD Studio — users sign a timestamped message with their Web3 wallet, and the function bridges that proof into a standard Supabase session.Request body:

walletAddress

string

required

The 0x-prefixed EVM wallet address (case-insensitive; stored as lowercase).

message

string

required

The raw message that was signed. Must contain walletAddress and timestamp as substrings to prevent replay attacks.

signature

string

required

EIP-191 hex signature produced by the wallet.

timestamp

integer

required

Unix timestamp (milliseconds) when the message was signed. Must be within 10 minutes of server time (2-minute future tolerance for clock skew).

Successful response:

{
  "session": { "access_token": "...", "refresh_token": "...", "expires_in": 3600 },
  "user": { "id": "uuid", "email": "0xabc...@wallet.local" },
  "bootstrap": { ... }
}

Bootstrap side-effects:

Creates a user profile row if one doesn’t exist
Ensures a wallet_users link record exists
Provisions a credit account with a one-time 100-credit welcome grant via ensure_credit_account

The bootstrap step is idempotent but must not fail. If it does, the function returns HTTP 500 — a half-initialized user session is not returned to the client.

GET /functions/v1/get-thirdweb-config — Thirdweb Client Config

Returns the Thirdweb clientId and any additional configuration needed for the Thirdweb Connect SDK. Called by the app during initialization before the auth flow begins.Response:

{
  "clientId": "..."
}

GET /functions/v1/realtime-client-secret — OpenAI Realtime API Key

Issues an ephemeral, short-lived OpenAI Realtime API key for use in the AI Director voice interface. The key is scoped to real-time sessions and expires automatically.Response:

{
  "client_secret": "...",
  "expires_at": 1700000000
}

Never expose this key to users or log it. The response contains a sensitive credential that grants real-time API access.

Billing

GET /functions/v1/billing-catalog — Plans and Credit Packs

Returns the full billing catalog: subscription plans, credit packs, the current user’s active subscription, and their credit wallet balance. Falls back to hardcoded defaults if the database tables are unavailable.Plans (fallback defaults):

`plan_code`	Name	Monthly	Yearly	Credits/mo
`free`	Free	$0	—	0 (one-time 100 welcome)
`pro`	Pro	$49	$468	2,000
`business`	Business	$149	$1,428	10,000

Credit Packs (fallback defaults):

`pack_code`	Credits	Price
`pack_500`	500	$9.99
`pack_2000`	2,000	$29.99
`pack_5000`	5,000	$59.99

Response:

{
  "success": true,
  "billing_mode": "live",
  "checkout_available": true,
  "plans": [ ... ],
  "credit_packs": [ ... ],
  "subscription": {
    "plan_code": "pro",
    "status": "active",
    "cancel_at_period_end": false,
    "current_period_start": "2024-01-01T00:00:00Z",
    "current_period_end": "2024-02-01T00:00:00Z"
  },
  "wallet": { ... },
  "plan": { ... }
}

POST /functions/v1/billing-checkout — Create Stripe Checkout Session

Creates a Stripe Checkout session for either a credit pack purchase (one-time payment) or a subscription upgrade.Request body:

checkout_mode

string

required

Either "pack" (one-time credit purchase) or "subscription".

pack_code

string

Required when checkout_mode is "pack". Must match an active billing_credit_packs row (e.g., "pack_500").

plan_code

string

Required when checkout_mode is "subscription". Must match an active billing_plans row (e.g., "pro").

interval

string

For subscriptions: "month" (default) or "year".

success_url

string

Redirect URL after successful payment. Defaults to {origin}/settings/billing?checkout=success.

cancel_url

string

Redirect URL if the user cancels. Defaults to {origin}/settings/billing?checkout=cancel.

Response:

{
  "success": true,
  "billing_mode": "live",
  "checkout_mode": "pack",
  "session_id": "cs_...",
  "checkout_url": "https://checkout.stripe.com/pay/cs_...",
  "status": "created"
}

A billing_checkout_sessions row is inserted for audit purposes.

POST /functions/v1/billing-portal — Customer Billing Portal

Creates a Stripe Customer Portal session so the user can manage their subscription, update payment methods, and view invoices.Response:

{
  "url": "https://billing.stripe.com/session/..."
}

POST /functions/v1/admin-add-credits — Admin Credit Adjustment

Adds or removes credits from a user’s wallet. Restricted to users with an admin role. Used for manual top-ups, refunds, and promotions.Request body:

user_id

string

required

Target user UUID.

amount

number

required

Credits to add (positive) or deduct (negative).

reason

string

Human-readable reason for the adjustment (stored in the credit ledger).

AI Generation (Proxy)

POST /functions/v1/fal — fal.ai Model Proxy (Queue Mode)

Submits a generation job to fal.ai in queue mode and returns immediately with a requestId and initial status. Use this for fire-and-forget submissions where the client polls for results separately.Request body:

modelId

string

required

fal.ai model ID (e.g., fal-ai/flux/schnell). The function prepends the fal.run/v1/ prefix automatically.

input

object

required

Model-specific input payload. All fields are forwarded verbatim to fal.ai with mode: "queue" added.

Response:

{
  "requestId": "fal-request-id",
  "status": "IN_QUEUE",
  "result": null
}

For streaming results with automatic polling, use /functions/v1/fal-stream instead. The fal function is a thin proxy for advanced use cases.

POST /functions/v1/fal-stream — fal.ai SSE Streaming Proxy

The primary AI generation proxy used by the Unified Generation Service. Submits the job to fal.ai, polls for status, and streams progress as SSE events. Handles automatic model fallback if the primary model fails.Request body:

modelId

string

required

fal.ai model ID. The function resolves aliases and applies model-specific input normalization.

inputs

object

required

Model inputs. Fields are normalized via mergeFalModelInputs before submission.

media_type

string

Hint for credit billing and fallback resolution: "image", "video", "audio", "json", or "utility". Inferred from modelId when omitted.

request_id

string

Client-supplied idempotency key for credit deduplication.

SSE Event Types:

Event `type`	Description
`meta`	Resolved model, fallback status, media type
`progress`	fal.ai queue status (`IN_QUEUE` → `IN_PROGRESS`), progress percent (5–95), logs
`done`	Final result object, resolved model ID
`fallback`	Primary model failed; retrying with fallback model
`error`	Terminal error with reason

Credit billing: Credits are reserved before submission. Actual cost committed on done; hold released on error.

POST /functions/v1/fal-proxy — fal.ai Request Proxy

Low-level passthrough proxy for fal.ai requests. Forwards the request body directly to fal.ai without modification. Used for specialized integrations that need raw fal.ai API access.

POST /functions/v1/gemini-image-generation — Gemini Image Generation

Generates images using Google Gemini’s image generation capabilities. Accepts a text prompt and optional generation parameters.Request body: { prompt, model?, parameters? }

POST /functions/v1/gemini-video-generation — Gemini Video Generation

Generates videos using Google Gemini’s video generation capabilities.Request body: { prompt, model?, parameters? }

POST /functions/v1/gemini-text-generation — Gemini Text Generation (SSE)

Generates text using Google Gemini or OpenAI GPT models. Streams the response as SSE with OpenAI-compatible data: chunks. Used by the Unified Generation Service for the gemini-text route.Request body: { prompt, model?, stream? }

POST /functions/v1/gemini-image-analysis — Gemini Image Analysis

Analyzes an image using Gemini’s multimodal capabilities. Returns structured descriptions, tags, and scene information.Request body: { image_url, prompt? }

POST /functions/v1/elevenlabs-tts — ElevenLabs Text-to-Speech

Converts text to speech using ElevenLabs. Returns raw audio bytes (audio/mpeg).Request body:

text

string

required

The text to synthesize.

voiceId

string

ElevenLabs voice ID. Defaults to JBFqnCBsd6RMkjVDRZzb.

modelId

string

ElevenLabs TTS model ID.

Response: Binary audio stream (Content-Type: audio/mpeg).

POST /functions/v1/elevenlabs-sfx — ElevenLabs Sound Effects

Generates a sound effect from a text description.Request body:

prompt

string

required

Description of the sound to generate.

duration

number

Desired duration in seconds (default: 5).

Response: Binary audio stream.

POST /functions/v1/elevenlabs-music — ElevenLabs Music Generation

Generates a music track from a text prompt.Request body:

prompt

string

required

Description of the music to generate.

duration

number

Duration in seconds (default: 30).

Response: Binary audio stream.

GET /functions/v1/elevenlabs-voices — ElevenLabs Voice List

Returns the list of available ElevenLabs voices for use in TTS.Response: { voices: [{ voice_id, name, preview_url, ... }] }

POST /functions/v1/groq-chat — Groq Chat Completion

Calls Groq’s /openai/v1/chat/completions endpoint. Used for fast text generation in project setup (storyline, shot ideas, scene breakdowns).Request body:

prompt

string

required

User prompt text.

model

string

Groq model ID (default: llama-3.3-70b-versatile).

temperature

number

Sampling temperature (default: 0.7).

maxTokens

integer

Maximum tokens to generate (default: 1024).

systemPrompt

string

System prompt to prepend.

Response: OpenAI-compatible completion object.

POST /functions/v1/groq-stream — Groq Chat Completion (SSE)

Streaming variant of groq-chat. Emits OpenAI-compatible data: SSE chunks.Request body: Same as groq-chat with stream: true implied.

Assets & Projects

POST /functions/v1/asset-upload — Upload Media to Project

Uploads a media file to the project’s Supabase Storage bucket and creates an asset record. Supports images, videos, and audio.Request body:

project_id (required) — target project UUID
file — base64-encoded file data or a URL to fetch and re-upload
asset_type — "image" | "video" | "audio"
metadata — optional custom key-value metadata

Response: { asset_id, public_url, storage_path }

POST /functions/v1/asset-processor — Process / Transcode Assets

Triggers server-side processing or transcoding for an uploaded asset. Operations include thumbnail generation, video frame extraction, and format conversion.Request body: { asset_id, operations: string[] }

POST /functions/v1/create-project — Create a New Project

Creates a new project row with default scenes and metadata. Returns the full project object.Request body:

title (required) — project title
description — optional project description
template_id — optional starting template

Response: { project: { id, title, ... } }

POST /functions/v1/upload — Generic File Upload

Generic file upload endpoint. Accepts multipart or base64 payloads and stores the file in the specified bucket. Returns a public_url.

POST /functions/v1/download — Retrieve Asset

Generates a signed download URL for a private storage asset, or proxies the asset bytes directly.Request body: { bucket, path, expires_in? }Response: { url } or binary stream.

POST /functions/v1/invite-collaborator

Sends a collaboration invite to another user by email or user ID, granting them access to a specific project.Request body:

project_id (required)
invitee_email or invitee_user_id
role — "viewer" | "editor" | "admin"

POST /functions/v1/create-share-link

GET /functions/v1/access-share-link

POST /functions/v1/revoke-share

The Postz integration lets users publish project exports to social media platforms directly from WZRD Studio.

POST /functions/v1/postz-channels

Returns the list of social media channels connected to the user’s account, and the platforms available for OAuth connection.Response:

{
  "channels": [
    {
      "id": "channel-uuid",
      "provider": "instagram",
      "display_name": "@myaccount",
      "status": "connected"
    }
  ],
  "available_platforms": ["instagram", "tiktok", "youtube", "twitter"]
}

POST /functions/v1/postz-oauth

Initiates the OAuth flow for a new social media connection. Returns an authorization URL that the desktop app opens in the system browser. After the user authorizes, the platform redirects to wzrd://postz/connected — see the Deep Links reference for how this callback is handled.Request body:

provider (required) — platform to connect (e.g., "instagram")
redirect_uri — typically the deep link wzrd://postz/connected

Response: { auth_url, state_id }

POST /functions/v1/postz-posts

Publishes a post to one or more connected channels.Request body:

channel_ids (required) — array of channel UUIDs to post to
asset_url (required) — URL of the video or image to publish
caption — post caption text
scheduled_at — ISO 8601 timestamp to schedule the post (publishes immediately if omitted)

Response: { post_id, status: "published" | "scheduled" }

Agent Integration

API Reference

Desktop Shell

Supabase Edge Functions: WZRD Backend API Reference

Authentication

Billing

AI Generation (Proxy)

Assets & Projects

Build docs developers (and LLMs) love

Agent Integration

API Reference

Desktop Shell

Documentation Index

​Authentication

​Billing

​AI Generation (Proxy)

​Assets & Projects

​Collaboration & Sharing

​Social (Postz)

Build docs developers (and LLMs) love

Authentication

Billing

AI Generation (Proxy)

Assets & Projects

Collaboration & Sharing

Social (Postz)