Custom LLM API

Manage your private LLM integrations on Convai. Register, update, or delete OpenAI-compatible custom models securely through simple API endpoints.

Custom LLM integrations are available only on the Enterprise Plan.

Introduction

The Convai Custom LLM Models API allows developers and enterprises to register and manage their own custom large language models (LLMs) on the Convai platform. With these endpoints, you can connect private, OpenAI-compatible LLMs, control access, and manage lifecycle events such as registration, updates, and removal.

All endpoints are POST requests and both accept and return JSON objects.

---

Base URL

https://api.convai.com

---

Authentication

Each request must include your Convai API key in the header. Without it, requests return 401 Unauthorized.

Header	Description	Example
CONVAI-API-KEY	Required on every request	245a4u6864dj6848516l2dr6df

Example error for missing/invalid key:

{
  "status": "error",
  "message": "Unauthorized: missing or invalid CONVAI-API-KEY",
  "transactionID": "..."
}

---

Common Response Fields

All endpoints share the following base structure in their responses.

Field	Type	Description
status	string	"success" or "error"
message	string	Human-readable summary
transactionID	string	Unique identifier for tracing
...	—	Endpoint-specific data

---

Endpoint Reference

#	Method & Path	Purpose
2.1 Register a Model	POST /llm-models/register	Register a new custom model
2.2 Update a Model	POST /llm-models/update	Update an existing custom model
2.3 Deregister a Model	POST /llm-models/deregister	Remove a registered model
2.4 List Models	POST /llm-models/list	List all custom models linked to your API key

---

2.1 Register a Model

Endpoint:

POST https://api.convai.com/llm-models/register

Request Body

Field	Type	Required	Notes
model_group_name	string	✓	Unique, immutable identifier
model_name	string	✓	Model name, e.g., "gpt-4o-mini"
api_key	string	✓	Secret key for the remote LLM endpoint
is_uncensored	boolean	✓	True if jailbreak-free
display_name	string	—	Optional UI label (defaults to group name)
base_url	string	—	OpenAI-compatible endpoint (default: https://api.openai.com/v1)

Example cURL

MacOS/Linux

curl -X POST https://api.convai.com/llm-models/register \
  -H "Content-Type: application/json" \
  -H "CONVAI-API-KEY: YOUR_API_KEY" \
  -d '{
        "model_group_name": "my-turbo",
        "model_name": "gpt-4o-mini",
        "api_key": "sk-proxy-123",
        "is_uncensored": false,
        "display_name": "Turbo (Private)",
        "base_url": "https://api.openai.com/v1"
      }'

Windows

Success Response (200 OK)

{
  "status": "success",
  "model_group_name": "my-turbo",
  "model_name": "gpt-4o-mini",
  "display_name": "Turbo (Private)",
  "message": "Model 'my-turbo' registered successfully",
  "transactionID": "14b0cf96-5230-4b0f-a971-2f4f4f6d5e6a"
}

Possible Errors

Code	Message	Cause
400	Missing required field	Validation failure
409	Model group name already exists	Duplicate identifier
500	Database error	Internal server error

---

2.2 Update a Model

Endpoint:

POST https://api.convai.com/llm-models/update

Request Body

Field	Type	Required	Notes
model_group_name	string	✓	Model to update
display_name	string	—	New friendly name
base_url	string	—	Updated endpoint URL
api_key	string	—	New API secret
is_uncensored	boolean	—	Toggle censorship

At least one optional field is required.

Example cURL

MacOS/Linux

curl -X POST https://api.convai.com/llm-models/update \
  -H "Content-Type: application/json" \
  -H "CONVAI-API-KEY: YOUR_API_KEY" \
  -d '{
        "model_group_name": "my-turbo",
        "display_name": "Turbo v2",
        "api_key": "sk-proxy-456"
      }'

Windows

Success Response (200 OK)

{
  "status": "success",
  "message": "Model 'my-turbo' updated successfully",
  "updated_fields": ["display_name", "api_key"],
  "transactionID": "5c0b6c67-97e4-4d78-9d5c-2a3de9d9c8ee"
}

Possible Errors

Code	Message	Cause
404	Model not found	Invalid or unauthorized model name
409	Display name already exists	Duplicate user label
400	No valid fields to update	Missing updatable fields

---

2.3 Deregister a Model

Endpoint:

POST https://api.convai.com/llm-models/deregister

Request Body

Field	Type	Required
model_group_name	string	✓

Example cURL

MacOS/Linux

curl -X POST https://api.convai.com/llm-models/deregister \
  -H "Content-Type: application/json" \
  -H "CONVAI-API-KEY: YOUR_API_KEY" \
  -d '{ "model_group_name": "my-turbo" }'

Windows

Success Response (200 OK)

{
  "status": "success",
  "message": "Model 'my-turbo' deregistered successfully",
  "transactionID": "b11ac4f7-4cd3-4f43-8a79-3c942a14a8c9"
}

Possible Errors

Code	Message	Cause
404	Model not found	Model does not exist or is not owned by the requester

---

2.4 List Models

Endpoint:

POST https://api.convai.com/llm-models/list

This endpoint requires no request body.

Example cURL

MacOS/Linux

curl -X POST https://api.convai.com/llm-models/list \
  -H "Content-Type: application/json" \
  -H "CONVAI-API-KEY: YOUR_API_KEY"

Windows

Success Response (200 OK)

{
  "status": "success",
  "models": [
    {
      "model_group_name": "my-turbo",
      "model_name": "gpt-4o-mini",
      "display_name": "Turbo (Private)",
      "base_url": "https://api.openai.com/v1",
      "is_uncensored": false,
      "category": "Private",
      "created_at": "2025-07-08T09:41:38.123Z"
    },
    {
      "model_group_name": "raw-mixtral",
      "model_name": "mixtral-8x22b-base",
      "display_name": "Mixtral Raw",
      "base_url": "https://llm.my-org.net/v1",
      "is_uncensored": true,
      "category": "Private",
      "created_at": "2025-05-21T14:02:05.551Z"
    }
  ],
  "count": 2,
  "transactionID": "2caa4b99-eda9-46e2-a9ee-b4f251afcb1f"
}

---

3. Error Reference (All Endpoints)

HTTP Code	Typical Reason
400	Missing or malformed parameters
401	Invalid or missing API key
404	Model not found or not owned by user
409	Duplicate group or display name
429	Rate limit exceeded
500	Internal server error

Example Error:

{
  "status": "error",
  "message": "Model 'x' not found or access denied",
  "transactionID": "..."
}

---

4. Usage Notes & Best Practices

Convai currently supports only OpenAI-compatible endpoints. Most major providers (OpenAI, Google, Cohere, Hugging Face, vLLM, SGlang) support this format.

model_group_name is immutable; choose carefully (e.g., llama3.1-70b-companyX instead of generic names).

display_name values must be unique per user.

Before using deregister for a model, make sure that all characters using the model have been switched to another model, or they will not work.

---

Conclusion

The Custom LLM API provides a streamlined way to integrate, manage, and control custom LLM endpoints within Convai. By maintaining unique identifiers, secure API keys, and OpenAI-compatible URLs, you ensure stable and private model deployments for your use-case.