For AI agents: markdown of this page — /docs-content-en/ai/credentials/models-add.md documentation index — /llms.txt

Add a model manually

POST /v1/ai/credentials/:id/models

Registers a single model bound to a Custom key. Used for providers that do not expose a catalog via GET /v1/models (Minimax, a corporate vLLM/Ollama, Cohere). The endpoint works only with the custom-openai-compat provider.

Parameters

Parameter Type Required Description
id (path) string yes Custom key ID from GET /v1/ai/credentials

Request fields (body)

Field Type Required Default Description
modelId string yes — The model ID at the provider without the custom-openai-compat/ prefix. The response adds the prefix; use the returned modelId as the model in requests to /v1/chat/completions
name string no value of modelId Display name of the model. null uses the default value
contextLength integer no 4096 Maximum context size in tokens. An integer from -2147483648 to 2147483647; null uses the default value
maxOutputTokens integer no null Maximum tokens in the response. An integer from -2147483648 to 2147483647, or null

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/ai/credentials/cred_custom_xyz/models \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "abab6.5-chat",
    "name": "MiniMax abab6.5-chat",
    "contextLength": 32768,
    "maxOutputTokens": 8192
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/ai/credentials/cred_custom_xyz/models \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "abab6.5-chat",
    "name": "MiniMax abab6.5-chat",
    "contextLength": 32768,
    "maxOutputTokens": 8192
  }'

JavaScript — personal key

javascript 
const id = 'cred_custom_xyz'
const res = await fetch(`https://vibecode.bitrix24.com/v1/ai/credentials/${id}/models`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    modelId: 'abab6.5-chat',
    name: 'MiniMax abab6.5-chat',
    contextLength: 32768,
    maxOutputTokens: 8192,
  }),
})

const { data } = await res.json()
console.log('Registered model with id:', data.id)

JavaScript — OAuth application

javascript 
const id = 'cred_custom_xyz'
const res = await fetch(`https://vibecode.bitrix24.com/v1/ai/credentials/${id}/models`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    modelId: 'abab6.5-chat',
    name: 'MiniMax abab6.5-chat',
    contextLength: 32768,
    maxOutputTokens: 8192,
  }),
})

const { data } = await res.json()
console.log('Registered model with id:', data.id)

Response fields

Field Type Description
success boolean Always true on success
data.id string Unique ID of the AiModel record (needed for deletion)
data.modelId string The registered modelId with the custom-openai-compat/ prefix
data.name string Model name
data.contextLength integer The saved context size

Response example

HTTP status 201 Created:

JSON 
{
  "success": true,
  "data": {
    "id": "aimodel_xyz789",
    "modelId": "custom-openai-compat/abab6.5-chat",
    "name": "MiniMax abab6.5-chat",
    "contextLength": 32768
  }
}

Error response example

400 not_custom_provider — the key does not belong to a Custom provider:

JSON 
{
  "success": false,
  "error": {
    "code": "not_custom_provider",
    "message": "Manual model registration is only available for custom-openai-compat credentials"
  }
}

Errors

HTTP Code Description
400 invalid_request modelId is missing, is not a string, is empty after trim, or the original string is longer than 200 characters
400 invalid_request name is provided and is neither a string nor null; the message identifies the name field
400 invalid_request contextLength or maxOutputTokens is provided and is neither an integer from -2147483648 to 2147483647 nor null; the message identifies the invalid field
400 not_custom_provider The endpoint works only with the custom-openai-compat provider
409 already_exists A model with the same modelId is already registered for this key
404 not_found A key with this id was not found or does not belong to you
403 scope_missing The API key lacks the vibe:ai scope

Full list of common API errors — Errors.

Model registration limit: 30 requests per minute. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas).

Known specifics

Duplicate registration is an error. A call with the same modelId for the same key returns 409 already_exists. The existing record is not updated.

The modelId prefix. In the request body, pass the provider identifier without a prefix, for example abab6.5-chat for Minimax or the loaded model name for a corporate vLLM. The saved and returned modelId includes the prefix: custom-openai-compat/abab6.5-chat.

Price is zero. Custom-provider models are always registered with a zero price (inputPrice = 0, outputPrice = 0). Platform billing skips such records — you pay the provider directly.

See also