Send Context & Trigger Reactions

Use two complementary endpoints to steer ai_licia in real time:

POST /v1/events — stream contextual facts so she understands the situation.
POST /v1/events/generations — demand an immediate response (rate-limited).

Both share the same envelope shape; choose the one that matches your use case.

When to send events

Situation	Suggested Endpoint	Notes & Sample Ideas
Production cues or stream activity	`POST /v1/events`	Upcoming guests, sponsor reads, raid announcements, “BRB in 2 min”.
Game moments & quest progress	`POST /v1/events` or `POST /v1/events/generations`	Player deaths, scoring plays, engine failures, quest acceptance/completion, rare drops. Force a reaction when you want an immediate hype/condolence.
Setup & environment status	`POST /v1/events`	Lighting scenes, camera changes, mic mute/unmute, background music titles, smart-home statuses.
Creator-specific workflows	`POST /v1/events`	Cooking steps (“adding spices”, “sautéing onions”), art commissions (“inking outline complete”), IRL or maker updates.
Chat trigger that needs an instant line	`POST /v1/events/generations`	Emergency shouts, donation callouts, high-value channel point rewards.
Channel point reward that forces a quip	`POST /v1/events/generations`	“Roast me” redemptions, “suggest a song”, “pick the next ingredient” challenges.
Telemetry, HUD, and stat updates	`POST /v1/events`	Race lap times, split differentials, health/ammo, map zones, sensor readouts. Keeps ai_licia aligned with on-screen data without forcing an instant reply.

/v1/events updates ai_licia’s internal context and she decides whether to speak.
/v1/events/generations forces a response right away. Use it sparingly to avoid interrupting ongoing flows.

Scenario ideas for `/v1/events`

You can send rich variety of context snippets; below are starting points you can adapt per stream type:

Game events: "PLAYER_DOWN: squad wiped on floor 32, request motivational speech", "Quest accepted: Rescue the lighthouse keeper", "Engine failure on left turbine, emergency landing in progress".
Production cues / stream activity: "Starting Q&A segment, remind viewers to submit questions", "Sponsor block in 5 minutes, mention Hydra Chairs", "Switching to Just Chatting for 15 minutes".
Setup / environment: "Studio lights set to 'Night Mode'", "Background track: Lofi Chill Mix Vol 2", "Kitchen cam online, oven preheated to 375F".
Cooking / creative streams: "Recipe: Carbonara, currently boiling pasta", "Art commission for @viewer42, blocking out colors", "Maker stream: resin curing, 10 minutes remaining".
Telemetry / HUD data: "Lap 5/12 completed in 1:37.521, tire wear 45%", "Health 23%, shield broken, ammo 12/90", "Flight sim altitude 18,000ft, IAS 220 knots, crosswind 12 knots".

Blend multiple facts (within the 1,000-character limit) to give ai_licia plenty of hooks.

POST /v1/events (context ingestion)

Feed ai_licia structured text so she can weave it into future replies.

Typical payloads

Live game telemetry: "Altitude 18 ft, heading 304, speed 5 knots"
Production notes: "New sponsor goal unlocked, remind chat about the giveaway"
IRL trackers: "Heart rate 120 bpm, say I'm sprinting"

Request

Method/Path: POST /v1/events
Headers: Authorization: Bearer <API_KEY>, Content-Type: application/json
Body:
- eventType (string): categorize the event (e.g. GAME_EVENT, IRL_EVENT)
- data.channelName (string): channel tied to your API key
- data.content (string, max 1,000 chars): the context snippet
- data.ttl (optional integer): auto-expire after X seconds

Responses

200 OK — ingested
401 Unauthorized — missing/invalid key
422 Unprocessable Entity — content too long

curl -X POST https://api.getailicia.com/v1/events \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "GAME_EVENT",
    "data": {
      "channelName": "mychannel",
      "content": "Squad reached Zone 3 with 2 medkits left; weather turning to storm."
    }
  }'
'

POST /v1/events/generations (force a reply)

Request a specific reaction when you need ai_licia to speak now.

Great for

Channel point rewards that demand a shout-out.
Custom alerts (e.g. "Tell chat we just hit 500 subs!").
Emergency call-outs ("Warn viewers we're about to wipe").

Request

Method/Path: POST /v1/events/generations
Headers: Authorization: Bearer <API_KEY>, Content-Type: application/json
Body:
- eventType (string): use any label, e.g. CHAT_TRIGGER
- data.channelName (string): channel tied to your API key
- data.content (string, max 300 chars): the prompt for ai_licia
- data.options (object, optional): execution and delivery options
  - mode (STANDARD or FAST, default STANDARD)
  - tts (boolean, default true, still governed by existing TTS rules)
  - ttl (optional positive integer, seconds): discard the request if processing has not started before it becomes stale

Omitting data.options uses STANDARD model execution with TTS enabled. You can control TTS independently in either mode.

Standard and fast modes

STANDARD is the default. Use it for normal reactions, summaries, or requests that need conversation history, memory, knowledge-base content, goals, mission, vision, web search, or commands.

FAST selects a dedicated latency-optimized path for brief, time-sensitive reactions. It keeps the active character and persona, configured language, compact streamer identity and description, current stream category, and current stream title. It deliberately excludes conversation history, memory, knowledge-base content, goals, mission, vision, web search, and commands.

Fast mode does not rewrite, shorten, or otherwise change the accepted data.content. Send the complete instruction and factual grounding the message needs. If a particular sentence style is useful, include it as a hint in the content itself.

Fast mode uses one model attempt with no fallback so stale messages are not delayed by recovery work. This trades some quality and resilience for lower latency. It does not guarantee a fixed end-to-end response or audio delivery time. TTS remains independently controlled by data.options.tts.

Rate limits are independent by mode for each API key: STANDARD allows one accepted request roughly every 25 seconds, while FAST allows one accepted request per second. A request in one mode does not consume the other mode’s window. These limits control API admission, not guaranteed speech cadence. Overlapping generations may still be serialized by downstream delivery.