Core AI Settings API

All the relevant APIs needed to modify Core AI setting of your Convai Character.

This API is available only on the Professional Plan and above.

Character Model Selection

POST https://api.convai.com/character/update

Update API can be used to change the LLM to be used for Character. Currently following models are supported.

Realtime / Live Models

OpenAI

Model

Model Code

Flagship

GPT Realtime 1.5 (beta)

gpt-realtime-1.5

GPT Realtime Mini (beta)

gpt-realtime-mini

Google

Model

Model Code

Flagship

Gemini 2.5 Flash Live (beta)

gemini-2.5-flash-live

Gemma 4 31B Fast (beta)

realtime-gemma-4-31b-it

Gemma 4 26B A4B Fast (beta)

realtime-gemma-4-26b-a4b-it

Standard Models

OpenAI

Anthropic

Model

Model Code

Flagship

Claude 4.5 Sonnet (beta)

claude-4-5-sonnet

Claude 4.5 Haiku (beta)

claude-4-5-haiku

Claude Sonnet (latest)

claude-sonnet

Claude Haiku (latest)

claude-haiku

Google

Model

Model Code

Flagship

Gemini 3.5 Flash

gemini-3.5-flash

Gemini Flash (latest)

gemini-flash

Gemini 3.1 Flash Lite

gemini-3.1-flash-lite

Gemini Flash Lite (latest)

gemini-flash-lite

Gemini 2.5 Flash

gemini-2.5-flash

Gemini 2.5 Flash Lite

gemini-2.5-flash-lite

Qwen

Model

Model Code

Flagship

Qwen3.6 27B (beta)

qwen3.6-27b

Qwen3.6 35B A3B (beta)

qwen3.6-35b-a3b

Llama

Model

Model Code

Flagship

Llama 4 Maverick (beta)

llama-4-maverick

Llama 4 Scout (beta)

llama-4-scout

Llama3 70B

llama3-70b

xAI

Model

Model Code

Flagship

Grok 4.3

grok-4.3

When calling update API to update Model for your Character, please ensure to pass the Model Code corresponding to the Model from the table above.

Headers

Name

Type

Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name

Type

Description

charID

String

Id of your character.

model_group_name

String

Model Code of the Model to which you want to update. See the table above.

{"STATUS": "SUCCESS"}

{
    "API_ERROR": "Invalid API key provided.
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/update"

headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "charID": "<Your-Character-Id>",
    "model_group_name": "claude-3-5-sonnet"
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)

curl -X POST "https://api.convai.com/character/update" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
           "charID": "<Your-Character-Id>",
           "model_group_name": "claude-3-5-sonnet"
         }'

Temperature Setting

POST https://api.convai.com/character/update

When chatting with AI, the temperature setting is like adjusting how creative or predictable the responses will be. A lower temperature makes the AI stick closer to what it knows for sure (Less Hallucinations), while a higher temperature lets it get more imaginative and potentially surprising (better Role Play).

Headers

Name

Type

Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name

Type

Description

charID

String

Id of your character.

temperature

Float

Temperature value. Must be between 0 and 1.

{"STATUS": "SUCCESS"}

{
    "API_ERROR": "Invalid API key provided.
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import requests
import json

url = "https://api.convai.com/character/update"

headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

# Create a dictionary for the JSON payload
payload = { 
    "charID": "<Your-Character-Id>",
    "temperature": 0.42
}

# Convert the payload to JSON
json_payload = json.dumps(payload)

response = requests.post(url, headers=headers, data=json_payload)

print(response.text)

curl -X POST "https://api.convai.com/character/update" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
           "charID": "<Your-Character-Id>",
           "temperature": 0.42
         }'

Reasoning Level Setting

POST https://api.convai.com/character/update

Controls how much internal reasoning the model performs before answering. More reasoning generally improves multi-step questions and instruction following, at the cost of higher latency and token usage.

Support is per model. Query /character/getSupportedModel to find out which levels a model accepts before setting one — a value the model does not support is rejected.

Headers

Name

Type

Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name

Type

Description

charID

String

Id of your character.

reasoning_effort

String

A level the selected model supports, or "auto". Send an empty string to clear the setting.

Values

Value

Behavior

(not set)

The character inherits whatever the model is configured with. This is the state of every character that has never had a level set.

"auto"

No reasoning parameter is sent to the provider, so the model applies its own adaptive default — reasoning more on hard requests and less on easy ones.

A supported level

Sent to the provider explicitly. Common values are none, minimal, low, medium, high, xhigh and max, but the accepted set is model-specific.

Not set and "auto" are different. Not set preserves the model's configured behavior. "auto" actively suppresses it so the provider's own adaptive default applies. Sending an empty string clears the setting and returns the character to the not-set state.

{"STATUS": "SUCCESS"}

{
    "ERROR": "Invalid reasoning_effort 'xhigh' for model 'gemini-3.6-flash'. Supported values: minimal, low, medium, high, auto."
}

{
    "API_ERROR": "Invalid API key provided."
}

import requests
import json

url = "https://api.convai.com/character/update"

headers = {
    'CONVAI-API-KEY': '<Your-API-Key>',
    'Content-Type': 'application/json'
}

payload = {
    "charID": "<Your-Character-Id>",
    "reasoning_effort": "auto"
}

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

print(response.text)

curl -X POST "https://api.convai.com/character/update" \
     -H "CONVAI-API-KEY: <Your-API-Key>" \
     -H "Content-Type: application/json" \
     -d '{
           "charID": "<Your-Character-Id>",
           "reasoning_effort": "auto"
         }'

Discovering supported reasoning levels

POST https://api.convai.com/character/getSupportedModel

Models that support reasoning control carry a reasoning block in their entry. Models without one do not support the setting.

{
  "model_group_name": "gpt-5.6-luna-none",
  "display_name": "GPT-5.6 Luna",
  "reasoning": {
    "levels": ["none", "low", "medium", "high"],
    "supports_auto": true,
    "default": "medium"
  }
}

Field

Type

Description

levels

String[]

The levels this model accepts, ordered from least to most reasoning.

supports_auto

Boolean

Whether "auto" is a valid value for this model.

default

String

The provider's own default level, when known. Applies when "auto" is selected.

Build any level picker from this block rather than hardcoding a list. Providers add and rename levels over time, and the accepted set differs between model families — Gemini's lowest level is minimal while OpenAI's is none.

PreviousMindview API

NextNarrative Design API

Last updated 27 days ago

Was this helpful?