Should I use sync, async or streaming, and do I need webhooks?
Use sync when your server can wait for the answer, streaming when users should see the answer as it's written, and async when the work is long or your browser should receive the result directly. Webhooks are optional: you only need them when your own backend must act on the result.
Which one fits my app?#
| You want to… | Use |
|---|---|
| Get a full answer in one response, from your server | Sync: POST /v1/ai |
| Show text as it's written, from your server | Sync with stream: true (Server-Sent Events) |
| Return immediately and deliver the result to the browser | Async: POST /v1/ai/async |
| Stream to the browser without proxying through your server | Async with stream: true |
| Let your backend process the result before the user sees it | Async with a backend pipeline (webhooks) |
How does the browser get an async result without webhooks?#
An async request returns right away with a channel_id and a one-time ws_token. Pass the token to the browser, which connects over WebSocket and receives the answer, streamed or complete. The client SDK handles the connection, reconnects and page refreshes for you. Your API key stays on your server.
When do I need webhooks?#
When your backend has to do something with the result: save it to a database, call another service, or check it before the user sees it. With a backend pipeline, ModelRiver sends the AI result to your webhook, your backend processes it and calls back, and the final result is pushed to the browser. Your backend has 10 minutes to call back.
Any timeouts I should know about?#
- Streams send a heartbeat every 15 seconds and time out after 5 minutes.
- Webhook endpoints must answer with a 2xx status within 30 seconds.