Visual Agents as a Service
The engine behind the ReelWand app, as an API: agents, sessions with memory, metered runs, streamed events.
- visual agents
- 50
- frontier models
- 8
- stream events
- 7
- video credits
- 4×
One surface, every frontier model
Agents route each run to the right renderer across eight image and video models. Without the prompt ever changing.
The concept model
Agent (slug) → Session (ses_*) → Run (run_*) → Message (msg_*). One active run per session, enforced server-side (409). Every run holds credits up front and settles on completion. Failed or cancelled runs refund automatically. Messages carry a per-session sequence and are either external (the conversation) or internal (work steps).
Start a run (SSE)
POST /api/generate
Content-Type: application/json
{
"agentSlug": "director-cut-studio",
"prompt": "a lone astronaut walks through neon rain",
"aspect": "16:9",
"sessionId": "ses_…" // omit to start a new session
}
→ 401 sign-in required · 403 model gate · 429 quota · 409 active run
→ 200 text/event-streamOn the Workers runtime the same protocol is available over a persistent WebSocket at /api/ws. Send {"type":"generate", …} frames, receive the events below as JSON frames.
Event protocol
| Event | Meaning |
|---|---|
| stream_started | Run accepted. Carries run_id, session_id and the credit cost |
| stream_progress | A work step (memory, knowledge retrieval, style assembly, rendering) with params; done:true when it completes |
| warning | Non-fatal notices, e.g. provider fallback to demo rendering |
| message_completed | The finished media message (msg_*) with its payload |
| stream_error | The run failed; the credit hold is refunded |
| stream_ended | Terminal event with run status and updated usage |
| ping | Keep-alive every 15 seconds during long renders |
More endpoints
GET /api/sessions. Session list;?id=ses_*one session with messagesPOST /api/agents. Create a private custom agent (its instructions never come back down)/api/knowledge. Notes retrieved into every render (your RAG layer)
Publish everywhere you create
Finished renders flow straight into 20 connected apps: cloud storage, socials and design tools.
Questions, answered
The details developers check before wiring the run API into a product.
What happens to my credits when a run fails?
Every run holds credits up front and settles on completion. Failed or cancelled runs refund the hold automatically. The stream_ended event carries your updated usage so clients never have to reconcile.
Should I stream over SSE or WebSocket?
SSE (POST /api/generate) is the simplest path: one request, one event stream per run. On the Workers runtime the same protocol is available over a persistent WebSocket at /api/ws. Pick it when your client already holds a socket or needs many runs on one connection. The events are identical.
Why am I getting a 409?
One active run per session, enforced server-side. Wait for stream_ended on the current run. Or start the new run in a fresh session by omitting sessionId.
When do API keys arrive?
Authentication is currently cookie-session. The consumer app is the reference client. API keys for third-party clients are the natural next step of this surface.
How are credits priced?
Images meter at 1 credit and video renders at 4. The exact cost of each accepted run arrives on its stream_started event, so pricing is visible before the render finishes.
The engine is already running
Everything on this page powers the consumer app today. Point your client at the same surface.
Sessions with memory
Every run iterates on the last render. Continuity is server-side.
Metered runs
Credits hold up front and settle on completion; failures refund.
SSE + WebSocket
One event protocol, two transports. Pick per client.