Documentation

Request types for every AI operation

ModelRiver workflows support three request types: chat, completion and embedding. Each has its own message format and provider support.

Workflows support different request types to handle different AI operations. The request_type field determines the expected message format and API endpoint usage. The examples use model to select a saved workflow; native requests can also use workflow. If the payload also needs a provider model field, send the workflow name as workflow.

Available request types

Chat (default)

Standard chat completions for conversational AI.

Use cases: Conversational assistants, Q&A systems, multi-turn dialogues, chatbots

JSON
1{
2 "model": "my_chat_workflow",
3 "messages": [
4 {"role": "system", "content": "You are a helpful assistant."},
5 {"role": "user", "content": "Hello, how are you?"}
6 ],
7 "temperature": 0.7,
8 "max_tokens": 1000
9}

Supported providers:

  • OpenAI
  • Anthropic
  • Google (Gemini)
  • xAI (Grok)
  • Mistral
  • Cohere, DeepSeek, Qwen, Groq, Kimi, MiniMax (catalog models via console)
  • Azure OpenAI: OpenAI-compatible chat. The workflow model must match your Azure deployment name. Requires the resource base URL and API key in the console.
  • Amazon Bedrock: Converse API (Nova, Claude on Bedrock, etc.). Requires the regional runtime base URL and a Bedrock API key. Streaming is not supported yet.
  • Custom: any OpenAI-compatible endpoint you add in the console.

The current model list for each provider is on the providers page.

Images in chat messages

To ask a model about an image, send it inside a chat message as an image_url content part. There is no separate vision request type.

JSON
1{
2 "model": "my_chat_workflow",
3 "messages": [
4 {
5 "role": "user",
6 "content": [
7 {"type": "text", "text": "What's in this image?"},
8 {
9 "type": "image_url",
10 "image_url": {"url": "data:image/jpeg;base64,..."}
11 }
12 ]
13 }
14 ]
15}

The url can be a base64 data URL or an https:// link. The workflow's model must accept images (models marked Vision on the providers page).

ProviderImage parts
OpenAI, Azure OpenAI, xAI, Mistral, DeepSeek, Qwen, Groq, Kimi, MiniMax, Cohere, CustomPassed through unchanged
AnthropicConverted to image blocks. Data URLs and https:// links
Google Gemini, Amazon BedrockConverted to the provider's image format. Data URLs only: an https:// link returns a 400 error, so download the image and send its data

Completion

Text completions for autocomplete and single-shot text generation.

Use cases: Code completion, text autocomplete, prompt-based text generation

JSON
1{
2 "model": "my_completion_workflow",
3 "prompt": "Once upon a time in a galaxy far far away",
4 "max_tokens": 500,
5 "temperature": 0.8
6}

Supported providers:

  • All chat providers. ModelRiver sends the prompt to the model as a single user message and returns the reply in completion format.
  • OpenAI's legacy completion models (gpt-3.5-turbo-instruct, davinci-002, babbage-002) use OpenAI's native completions endpoint instead.

Embedding

Generate vector embeddings for text: essential for semantic search, RAG, and clustering.

Use cases: Semantic search, text similarity, clustering, recommendation systems, RAG (Retrieval Augmented Generation)

Single text:

JSON
1{
2 "model": "my_embedding_workflow",
3 "input": "The quick brown fox jumps over the lazy dog",
4 "encoding_format": "float"
5}

Batch (multiple texts):

JSON
1{
2 "model": "my_embedding_workflow",
3 "input": [
4 "First text to embed",
5 "Second text to embed",
6 "Third text to embed"
7 ]
8}

Supported providers:

  • OpenAI (text-embedding-3-large, text-embedding-3-small)
  • Google (gemini-embedding-2)
  • Cohere (embed-v4.0)
  • Mistral (mistral-embed, codestral-embed)

Response:

JSON
1{
2 "data": {
3 "object": "list",
4 "data": [
5 {
6 "object": "embedding",
7 "embedding": [0.123, -0.456, 0.789],
8 "index": 0
9 }
10 ],
11 "model": "text-embedding-3-large",
12 "usage": {
13 "prompt_tokens": 8,
14 "total_tokens": 8
15 }
16 }
17}

Image generation, audio and vision

These types are not supported yet, and the console shows them as Coming soon.

Requests to a workflow with one of these types fail with unsupported_request_type. To analyse an image today, use a chat workflow and send the image in the message.

Creating workflows with request types

Via the console

  1. Open Workflows in your project
  2. Click Create Workflow
  3. Select the Request Type from the dropdown
  4. Choose a provider and model that supports your selected type
  5. Save the workflow

Validation

Before a request reaches a provider, ModelRiver checks that:

  1. The workflow's request_type is supported
  2. stream: true is only used with chat workflows; completion and embedding requests can't stream
  3. The request body has the field that type needs: messages for chat, prompt for completion, input for embedding

Example error from POST /v1/ai for a workflow whose type isn't supported (HTTP 400):

JSON
1{
2 "error": "unsupported_request_type",
3 "message": "Request type 'image' is not supported yet. Supported types: chat, completion, embedding.",
4 "details": {}
5}

Default behaviour

If no request_type is specified when creating a workflow, it defaults to "chat". Existing workflows without a request_type automatically use "chat" for backward compatibility.

Quick reference

TypeKey fieldProviders
chatmessagesAll providers
completionpromptAll chat providers
embeddinginputOpenAI, Google, Cohere, Mistral

Best practices

  1. Match request type to use case: Choose the most appropriate type for your application
  2. Configure fallbacks: Set backup providers that support the same request type
  3. Validate inputs: Ensure your application sends the correct message format for the type
  4. Use structured outputs: Combine chat workflows with structured outputs for consistent responses
  5. Monitor usage: Track which request types consume the most tokens

Next steps