Migration Tutorial: to /v2/llm/chat

Eden AI has released a new unified and OpenAI-compatible endpoint for all LLM and multimodal chat models:

🔗 New endpoint: https://api.edenai.run/v2/llm/chat

The previous endpoints /v1/chat and /v1/multimodal/chat are being deprecated and will no longer be supported after June 1st, 2025.

Follow this quick guide to migrate your existing code.

✅ Before – Old Endpoint (/v2/text/chat)

import json  
import requests

headers = {  
    "Accept": "application/json",  
    "Content-Type": "application/json",  
    "Authorization": "Bearer \<YOUR_API_KEY>"  
}

url = "<https://api.edenai.run/v2/text/chat">

payload = {  
    "providers": "openai/o1",  
    "text": "Describe the movie Dune",  
    "chat_global_action": "Act as an assistant",  
    "previous_history": \[],  
    "temperature": 1,  
    "max_tokens": 1000  
}

response = requests.post(url, json=payload, headers=headers)  
result = json.loads(response.text)  
print(result)

✅ Before – Old Endpoint (/v2/text/chat)

import json
import requests

headers = {
    "Authorization": "Bearer <your_api_key>",
    "Content-Type": "application/json"
}

url = "https://api.edenai.run/v2/chat/multimodal"

image_base64 = "/9j/4AAQSkZ..."

payload = {
    "provider": "openai/gpt-4-turbo",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What's happening in this image?"
                },
                {
                    "type": "image",
                    "image": {
                        "image_base64": image_base64,
                        "filename": "filename.jpg"
                    }
                }
            ]
        }
    ],
    "temperature": 0.7,
    "max_tokens": 1000
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

🆕 After – New Endpoint (/v2/llm/chat)

import json  
import requests

headers = {  
    "Accept": "application/json",  
    "Content-Type": "application/json",  
    "Authorization": "Bearer \<YOUR_API_KEY>"  
}

url = "<https://api.edenai.run/v2/llm/chat">

payload = {  
    "model": "openai.gpt-3.5-turbo",  
    "messages": [  
        {"role": "system", "content": "You are a helpful assistant."},  
        {"role": "user", "content": "Describe the movie Dune"}  
    ],  
    "temperature": 1,  
    "max_tokens": 1000,  
    "fallback_model": "mistral.mixtral-8x7b"  
}

response = requests.post(url, json=payload, headers=headers)  
result = json.loads(response.text)  
print(result)

✅ Example messages Object (with multimodal)

'messages':[{
  "role": "user",
  "content": [
    {"type": "text", "text": "What's in this image?"},
    {
      "type": "image_url",
      "image_url": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
      },
    },
  ],
}]

🔄 Key Changes

Old Parameter	New Equivalent
providers	model (e.g. "openai.gpt-3.5-turbo")
text	messages array with role/content
chat_global_action	system message (in messages)
previous_history	Use prior messages with proper roles

🟩 New Endpoint Parameters

🧠 Required Parameters

Name	Type	Description
`model`	`string`	ID of the model to use (e.g., `"gpt-4"`, `"claude-3-5-sonnet-latest"`).
`messages`	`array of objects`	List of user/assistant messages (with rich content structure, including text and media).

🧩 messages Structure

Each message must follow this structure:

Key	Type	Description
`role`	`string`	`"user"` or `"assistant"`or `system`
`content`	`array` of content blocks	Each block has `type` and `content` keys. See below.

🔹 content Blocks

`type`	Required `content` format
`text`	`{ "text": "..." }`
`media_url`	`{ "media_url": { "url": "..." } }`

🆕 Optional Parameters (New Endpoint Only)

Name	Type	Description
`reasoning_effort`	`string`	`"low"`, `"medium"`, or `"high"`
`metadata`	`array of objects`	List of `{ key, value }` pairs to pass metadata
`frequency_penalty`	`float` (-2 to 2)	Penalizes frequent tokens to reduce repetition
`logit_bias`	`object`	Adjust likelihoods for specific token IDs
`logprobs`	`boolean`	Return log probabilities of top tokens
`top_logprobs`	`integer` (0–20)	Number of top logprobs per token to return
`max_completion_tokens`	`integer` (≥1)	Limit on the number of tokens in the completion
`n`	`integer` (≥1)	Number of completion alternatives to return
`modalities`	`array of strings`	List of allowed input/output formats, e.g., `["text", "image", "audio"]`
`prediction`	`object`	Custom object to store prediction data
`audio`	`object`	Audio metadata (e.g., language, format)
`presence_penalty`	`float` (-2 to 2)	Encourage/discourage new topics
`response_format`	`object`	Response structure, e.g., JSON output with schema
`seed`	`integer`	Deterministic random seed
`service_tier`	`string`	`"auto"` or `"default"`
`stop`	`array of strings`	Strings that stop the generation
`stream`	`boolean`	Enable streaming responses
`stream_options`	`object`	Streaming config, e.g., `{ "include_usage": true }`
`temperature`	`float` (0–2)	Controls creativity (higher = more random)
`top_p`	`float` (0–1)	Controls token pool diversity
`tools`	`array of objects`	Tool definitions available to the model
`tool_choice`	`string`	`"auto"`, `"none"`, or specific tool name
`parallel_tool_calls`	`boolean`	Allow multiple tools to be called at once
`user`	`string`	Optional user ID for tracking
`function_call`	`string`	`"auto"`, `"none"`, or specific function name
`functions`	`array of objects`	Function definitions for the model

📚 Additional Notes

The new endpoint follows OpenAI’s chat format for easy migration from OpenAI tools or SDKs.
You can now specify a fallback_model to automatically retry with another model if the primary one fails.
It supports both text and multimodal models in a single, unified schema.

📖 See full documentation: https://docs.edenai.co/reference/chat