One API for every AI provider
ModelRiver provides a single, unified API endpoint that routes your requests to any configured AI provider: OpenAI, Anthropic, Mistral, Google, xAI, and more. Instead of maintaining separate integrations for each provider, you configure workflows in the console and call one endpoint. ModelRiver handles the rest: provider routing, automatic failover, token tracking, and structured output enforcement.
How it works
- Create a workflow in the ModelRiver console: choose your provider, model, fallbacks, and output schema
- Send a request to the unified endpoint with your workflow name
- Receive the response in standard OpenAI format, with metadata about which provider was used, tokens consumed, and more
curl -X POST https://api.modelriver.com/v1/ai \ -H "Authorization: Bearer mr_live_your_key" \ -H "Content-Type: application/json" \ -d '{ "workflow": "marketing-summary", "messages": [ {"role": "user", "content": "Summarise this week's launch."} ] }'Core concepts
Workflows as model aliases
The workflow field in your API request maps to a named configuration in the ModelRiver console. Each workflow specifies:
- Primary provider and model (e.g.,
openai/gpt-4o) - Fallback providers for automatic failover
- System instructions prepended to every request
- Structured output schemas for guaranteed JSON shape
- Cache fields that echo request metadata in responses
Change providers, models, or prompts in the console: no code changes required.
Two API flavours
ModelRiver offers two ways to send AI requests:
| Feature | Native API | OpenAI-compatible API |
|---|---|---|
| Endpoint | POST /v1/ai | POST /api/v1/chat/completions |
| Auth | Bearer mr_live_... | Bearer mr_live_... |
| Model field | workflow name | model = workflow name |
| Response | Raw or wrapped format | Standard OpenAI format |
| Best for | Full feature access | Drop-in SDK replacement |
API sections
Endpoints & requests
Base configuration, synchronous and asynchronous request patterns, optional fields, and the full response payload specification.
OpenAI SDK compatibility
Use ModelRiver as a drop-in replacement for the OpenAI API. Connect with any OpenAI-compatible SDK: Python, Node.js, LangChain, LlamaIndex, Vercel AI, and more.
Streaming
Real-time Server-Sent Events (SSE) for token-by-token delivery. Includes heartbeat support, timeout handling, and examples in Python and Node.js.
Function calling
OpenAI-compatible tool use with tools and tool_choice. Pass function definitions, receive structured tool_calls, and handle multi-turn tool conversations.
Request types
Configure workflows for chat completions, text completions, image generation, embeddings, audio processing, and vision analysis.
Response formats
Choose between raw format (OpenAI-compatible) for production and wrapped format (with metadata) for debugging and analytics.
Error handling
Standard error envelope, HTTP status codes, common error codes, and best practices for production error handling and retry logic.
Authentication
API key management, header configuration, key rotation, and security best practices for production deployments.
Migration guide
Step-by-step guides for migrating from direct OpenAI, Anthropic, or other provider APIs to ModelRiver.
Quick reference
| I want to... | Go to |
|---|---|
| Send my first request | Endpoints |
| Use the OpenAI Python SDK | OpenAI compatibility |
| Stream tokens in real-time | Streaming |
| Add function calling | Function calling |
| Generate images or embeddings | Request types |
| Choose raw vs wrapped response | Response formats |
| Handle errors gracefully | Error handling |
| Rotate or secure API keys | Authentication |
| Migrate from OpenAI | Migration guide |
Next steps
- Webhooks & event-driven workflows: Receive async results via webhooks
- Workflows: Configure providers, fallbacks, and structured outputs
- Client SDK: Frontend libraries for React, Vue, Angular, and more
- Observability: Monitor and debug every request