Add a model manually

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

Connects a model to a key from any provider. Supply one modelId or a batch using modelIds (1 to 100 strings). For keys of all providers except the Custom provider, metadata priority is: request body → live list → defaults. Manual connection by model ID works if the list is unavailable. Single requests to the Custom provider keep their existing contract: any string up to 200 characters that is nonblank after trimming surrounding whitespace, with body metadata taking priority.

Requires the vibe:ai scope. The public API accepts only your own USER key. A key owned by another user, a missing key or a PORTAL key returns 404 not_found.

Parameters

Request fields (body)

Examples

curl — personal key

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

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

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

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

Response example

Single modelId request, HTTP status 201 Created:

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

Batch request { "modelIds": ["gpt-4o-mini", "gpt-4o"] }, HTTP status 200 OK. The gpt-4o model was already connected to the key:

{
  "success": true,
  "data": {
    "created": [
      { "modelId": "gpt-4o-mini", "rowId": "aimodel_xyz789" }
    ],
    "skipped": [
      { "modelId": "gpt-4o", "reason": "already_connected" }
    ]
  }
}

Error response example

404 not_found — the key was not found or belongs to another user:

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Credential not found"
  }
}

Errors

For the full list of common API errors, see Errors.

Model registration limit: 30 requests per minute. The current limit is returned in the x-ratelimit-limit header.

Known specifics

Price is zero. Key models are always registered with a zero price (inputPrice = 0, outputPrice = 0). The platform does not bill such records — you pay the provider directly.

Batch connection. Supply { "modelIds": ["gpt-4o-mini", "gpt-4o"] } without modelId. The entire batch is validated before writing. IDs for providers other than the Custom provider use only [A-Za-z0-9._:/@-], up to 200 characters. One snapshot of the list is used for the whole batch. Response 200: created contains { modelId, rowId }, skipped contains { modelId, reason: "already_connected" }. In a batch response, modelId is the raw provider ID. Duplicates and concurrent requests for the same model appear in skipped.

A key holds at most 1000 rows. Exceeding this returns 409 key_models_limit without partial batch writes. A single duplicate returns 409 already_exists, and a successful single request still returns 201. A new row inherits capabilities and reasoningControl from the platform model with the same ID. If there is no such row, capabilities from the provider list are used.

Model list request limits. They are shared by available-models, fetch-models and connection: 20 seconds including all retries and pages, up to 5 MiB per response before JSON parsing, and at most 1000 models and 10 pages. A repeated cursor stops pagination. Only one such request runs per account at a time, and at most 10 run per minute. Incomplete lists never change absent models to DEPRECATED.

See also

• Preview available models
• Fetch the model catalog
• Key model list
• Delete a key model
• Create a chat completion