Connection basics and troubleshooting
Every client needs an API address, an API key, and a model ID. Match the address to the protocol before you configure the client to avoid duplicated paths and incompatible requests.
Prepare your connection details
- API key: create one in Token management. Use a separate token for each tool.
- Model ID: copy the complete identifier from Models, including case, hyphens, and version suffixes. Your token group and model restrictions determine access.
- API address: use
https://api.nbility.ai. The web console address is not the API endpoint.
Choose the correct base URL
| Client field or protocol | Value | Resulting request path |
|---|---|---|
| OpenAI SDK, Cline, or Cherry Studio Base URL | https://api.nbility.ai/v1 | /v1/chat/completions or /v1/responses |
| Anthropic SDK or Claude Code Base URL | https://api.nbility.ai | /v1/messages |
| Gemini CLI GOOGLE_GEMINI_BASE_URL | https://api.nbility.ai | /v1beta/models/{model}:generateContent |
| Chatbox API Host | https://api.nbility.ai | With its default API Path /v1/chat/completions |
| Tools requesting a complete endpoint | Origin plus the entire path | For example, https://api.nbility.ai/v1/chat/completions |
A base URL and a complete endpoint are different settings. Do not append /chat/completions to an SDK base URL or repeat /v1 when the client adds it. Check the field description in your installed version.
Check available models first
Set the key in your current terminal, then request the models visible to that token:
export NBILITY_API_KEY="YOUR_API_KEY"
curl --fail-with-body "https://api.nbility.ai/v1/models" \
-H "Authorization: Bearer $NBILITY_API_KEY"
Copy an exact id from the returned data array. If the model is missing, check the token group and restrictions. A successful model listing establishes basic connectivity; tools, images, and protocol compatibility still need their own checks.
Diagnose errors in order
| Symptom | Check first | Next step |
|---|---|---|
| 401 | Whitespace, expired key, or revoked key | Update the credentials saved by the client |
| 403 | Model, IP, or group restrictions | Review token settings without sharing the key |
| 404 | API origin, repeated /v1, protocol, and model ID | Inspect the final request URL using the table above |
| 429 | Request rate, concurrency, or upstream capacity | Reduce concurrency, respect Retry-After, and cap backoff retries |
| 5xx or timeout | Service status and your network | Record time, model, and request ID; check Usage logs |
| Chat works but file editing fails | Tool support and client approval settings | Test a small task with a tool-capable model |
See API errors for error structures and retry advice. If a stream fails midway, do not append the output of a retried request to the incomplete answer.
Save and verify
After changing shell variables, launch the tool from that same terminal. Running processes do not inherit new variables. Desktop apps launched from a dock or start menu may not see shell variables; prefer their credential settings.
Send a short message first. Confirm the model and status in Usage logs before enabling editing, automatic commands, or long tasks. Store keys in the client's credential store or environment variables. Keep them out of Git, tickets, chat transcripts, and public screenshots.
Pick a tutorial
- Terminal: Claude Code, Codex, OpenCode, Gemini CLI
- Editors: Cursor, Cline, Roo Code, Kilo Code, Zed Agent
- Desktop chat: Cherry Studio, Chatbox
- Application code: SDK quickstart