## Список провайдеров

`GET /v1/ai/providers`

Возвращает справочник провайдеров, доступных для подключения BYOK-ключа. Используйте перед [`POST /v1/ai/credentials`](/docs/ai/credentials/create), чтобы получить корректный `providerId` и узнать, какие поля провайдер ожидает в `credentials`.

## Параметры

Параметров запроса нет.

## Примеры

### curl — личный ключ

```bash
curl https://vibecode.bitrix24.tech/v1/ai/providers \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl https://vibecode.bitrix24.tech/v1/ai/providers \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/ai/providers', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
data.forEach((p) => {
  const fields = Object.keys(p.credentialFields).join(', ')
  console.log(`${p.name} (${p.slug}) — нужны поля: ${fields}`)
})
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/ai/providers', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
const openai = data.find((p) => p.slug === 'openai')
console.log('ID OpenAI:', openai.id)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Массив провайдеров, отсортирован по `name` |
| `data[].id` | string | ID провайдера — используйте в `providerId` запроса к [`POST /v1/ai/credentials`](/docs/ai/credentials/create) |
| `data[].name` | string | Отображаемое название |
| `data[].slug` | string | Системное имя провайдера: `openai`, `anthropic`, `custom-openai-compat` и т. п. |
| `data[].credentialFields` | object | Описание полей, которые нужно передать в `credentials` при создании ключа |
| `data[].credentialFields.<field>.type` | string | Тип ввода: `password`, `url`, `text` |
| `data[].credentialFields.<field>.label` | string | Метка поля |
| `data[].credentialFields.<field>.required` | boolean | Обязательность |
| `data[].credentialFields.<field>.placeholder` | string | Подсказка для пустого поля |
| `data[].credentialFields.<field>.hint` | string | Подсказка для пользователя. У большинства провайдеров — домен страницы, где выпускается ключ |
| `data[].credentialFields.<field>.help` | string | Поясняющий текст к полю. Приходит у провайдера `custom-openai-compat` для поля `baseUrl` |

## Пример ответа

```json
{
  "success": true,
  "data": [
    {
      "id": "anthropic",
      "name": "Anthropic",
      "slug": "anthropic",
      "credentialFields": {
        "apiKey": {
          "type": "password",
          "label": "API Key",
          "required": true
        }
      }
    },
    {
      "id": "cprv_custom_seed",
      "name": "Custom OpenAI-Compatible",
      "slug": "custom-openai-compat",
      "credentialFields": {
        "apiKey": {
          "type": "password",
          "label": "API Key",
          "required": true
        },
        "baseUrl": {
          "type": "url",
          "label": "Base URL",
          "required": true,
          "placeholder": "https://api.example.com/v1",
          "help": "OpenAI-compatible endpoint."
        }
      }
    },
    {
      "id": "openai",
      "name": "OpenAI",
      "slug": "openai",
      "credentialFields": {
        "apiKey": {
          "type": "password",
          "label": "API Key",
          "required": true
        }
      }
    }
  ]
}
```

## Пример ответа при ошибке

`403 scope_missing` — у API-ключа нет скоупа `vibe:ai`:

```json
{
  "success": false,
  "error": {
    "code": "scope_missing",
    "message": "API key does not have the vibe:ai scope"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 403 | `scope_missing` | API-ключу не хватает скоупа `vibe:ai` |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Провайдер `bitrix` исключён.** Список не содержит платформенного провайдера `bitrix` — его модели (BitrixGPT 5.5, GPT-OSS, Whisper и др.) доступны всем без подключения BYOK.

**Большинство провайдеров требует только `apiKey`.** Поле `baseUrl` обязательно только для `custom-openai-compat`. Для всех остальных провайдеров `baseUrl` фиксирован платформой и в `credentials` не передаётся.

**Системное имя `custom-openai-compat` — для произвольных сервисов.** Используйте, чтобы подключить любой OpenAI-совместимый сервис: Minimax, Cerebras, Cohere, корпоративный `vLLM`/`Ollama`, локальный inference-сервер. После подключения модели либо загружаются автоматически через [`fetch-models`](/docs/ai/credentials/fetch-models), либо регистрируются вручную через [`models-add`](/docs/ai/credentials/models-add).

**Подсказки `hint`.** У части провайдеров поле `hint` содержит домен страницы получения ключа: `platform.deepseek.com`, `console.groq.com`, `aistudio.google.com`. Показывайте его пользователю рядом с полем ввода ключа.

## Смотрите также

- [Подключить ключ](/docs/ai/credentials/create)
- [Свои ключи (BYOK)](/docs/ai/credentials)
- [AI Router](/docs/ai)