# aicentos Docs > aicentos is an AI API aggregation platform for developers and enterprises. One API Key for OpenAI, Anthropic, Google, xAI and more — a self-built official account pool connecting directly to vendor APIs, with multi-account fallback and automatic failover, plus live availability, contracts and private deployment. This file combines documents available in English, with a source URL for each page. [Documentation index](https://docs.aicentos.com/en/llms.txt) # Native Claude Format Source: https://docs.aicentos.com/en/api/chat/claude Language: en Chat `POST /messages` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Request Body `application/json` TypeScript type definition Use the request body type in TypeScript ## Response Body ### `application/json` ### `application/json` ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X POST "https://aicentos.com/v1/messages" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-6", "max_tokens": 256, "messages": [ { "role": "user", "content": "Introduce yourself in one sentence" } ] }' ``` ```bash { "id": "string", "type": "message", "role": "assistant", "content": [ { "type": "text", "text": "string" } ], "model": "string", "stop_reason": "end_turn", "usage": { "input_tokens": 0, "output_tokens": 0 } } ``` ```bash { "error": { "message": "Incorrect API key provided", "type": "authentication_error", "code": "invalid_api_key" } } ``` ```bash { "error": { "message": "Incorrect API key provided", "type": "authentication_error", "code": "invalid_api_key" } } ``` --- # Gemini Text Chat Source: https://docs.aicentos.com/en/api/chat/gemini/text Language: en Chat — native Gemini format `POST /v1beta/models/{model}:generateContent` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Path Parameters model\*string ## Request Body `application/json` TypeScript type definition Use the request body type in TypeScript ## Response Body ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X POST "https://aicentos.com/v1beta/models/gemini-2.0-pro:generateContent" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ { "text": "Introduce yourself in one sentence" } ] } ] }' ``` ```bash { "candidates": [ { "content": {}, "finishReason": "string", "index": 0 } ], "usageMetadata": { "promptTokenCount": 0, "candidatesTokenCount": 0, "totalTokenCount": 0 } } ``` --- # ChatCompletions Format Source: https://docs.aicentos.com/en/api/chat/openai/chat-completions Language: en Chat — native OpenAI format `POST /chat/completions` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Request Body `application/json` TypeScript type definition Use the request body type in TypeScript ## Response Body ### `application/json` ### `application/json` ### `application/json` ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X POST "https://aicentos.com/v1/chat/completions" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [ { "role": "user", "content": "Introduce yourself in one sentence" } ] }' ``` ```bash { "id": "chatcmpl-abc123", "object": "chat.completion", "created": 0, "model": "string", "choices": [ { "index": 0, "message": { "role": "system", "content": "string", "name": "string" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 } } ``` ```bash { "error": { "message": "Incorrect API key provided", "type": "authentication_error", "code": "invalid_api_key" } } ``` ```bash { "error": { "message": "Incorrect API key provided", "type": "authentication_error", "code": "invalid_api_key" } } ``` ```bash { "error": { "message": "Incorrect API key provided", "type": "authentication_error", "code": "invalid_api_key" } } ``` --- # Responses Format Source: https://docs.aicentos.com/en/api/chat/openai/responses Language: en Chat — native OpenAI format `POST /responses` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Request Body `application/json` TypeScript type definition Use the request body type in TypeScript ## Response Body ### `application/json` ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X POST "https://aicentos.com/v1/responses" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-5", "input": "Introduce yourself in one sentence" }' ``` ```bash { "id": "string", "object": "response", "status": "completed", "output": [], "usage": {} } ``` ```bash { "error": { "message": "Incorrect API key provided", "type": "authentication_error", "code": "invalid_api_key" } } ``` --- # Native Gemini Format Source: https://docs.aicentos.com/en/api/images/nano-banana/gemini Language: en Images — Nano Banana `POST /v1beta/models/gemini-3-pro-image-preview:generateContent` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Request Body `application/json` TypeScript type definition Use the request body type in TypeScript ## Response Body ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X POST "https://aicentos.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contents": [ { "role": "user", "parts": [ { "text": "A capybara in a spacesuit floating in space" } ] } ], "generationConfig": { "responseModalities": [ "IMAGE" ] } }' ``` ```bash { "candidates": [ { "content": { "role": "string", "parts": [ { "text": "string", "inlineData": { "mimeType": "string", "data": "string" } } ] }, "finishReason": "string", "index": 0 } ], "usageMetadata": { "promptTokenCount": 0, "candidatesTokenCount": 0, "totalTokenCount": 0 }, "modelVersion": "string" } ``` --- # Edit Image Source: https://docs.aicentos.com/en/api/images/openai/edits Language: en Images — native OpenAI format `POST /images/edits` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Request Body `multipart/form-data` TypeScript type definition Use the request body type in TypeScript ## Response Body ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X POST "https://aicentos.com/v1/images/edits" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -F image="[ \"string\" ]" \ -F prompt="string" ``` ```bash { "created": 0, "background": "string", "output_format": "string", "size": "string", "data": [ { "url": "string", "b64_json": "string" } ], "usage": { "input_tokens": 0, "output_tokens": 0, "total_tokens": 0 } } ``` --- # Generate Image Source: https://docs.aicentos.com/en/api/images/openai/generations Language: en Images — native OpenAI format `POST /images/generations` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Request Body `application/json` TypeScript type definition Use the request body type in TypeScript ## Response Body ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X POST "https://aicentos.com/v1/images/generations" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "A futuristic city skyline at sunset, neon lights, cinematic", "size": "1024x1024", "quality": "hd" }' ``` ```bash { "created": 0, "background": "string", "output_format": "string", "quality": "string", "size": "string", "data": [ { "url": "string", "b64_json": "string", "revised_prompt": "string" } ], "usage": { "input_tokens": 0, "output_tokens": 0, "total_tokens": 0, "input_tokens_details": { "text_tokens": 0, "image_tokens": 0 }, "output_tokens_details": { "text_tokens": 0, "image_tokens": 0 } } } ``` --- # Native Gemini Format Source: https://docs.aicentos.com/en/api/models/gemini Language: en Models `GET /v1beta/models` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Response Body ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X GET "https://aicentos.com/v1beta/models" \ -H "Authorization: Bearer $AICENTOS_API_KEY" ``` ```bash { "models": [ { "name": "models/gemini-2.0-pro", "displayName": "string", "description": "string", "inputTokenLimit": 0, "outputTokenLimit": 0, "supportedGenerationMethods": [ "string" ] } ] } ``` --- # Native OpenAI Format Source: https://docs.aicentos.com/en/api/models/openai Language: en Models `GET /models` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Response Body ### `application/json` ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X GET "https://aicentos.com/v1/models" \ -H "Authorization: Bearer $AICENTOS_API_KEY" ``` ```bash { "object": "list", "data": [ { "id": "gpt-4o-mini", "object": "model", "created": 1715000000, "owned_by": "openai" } ] } ``` ```bash { "error": { "message": "Incorrect API key provided", "type": "authentication_error", "code": "invalid_api_key" } } ``` --- # Dreamina · Create Video Source: https://docs.aicentos.com/en/api/videos/dreamina/create Language: en > Submit a Dreamina video generation task; returns a task ID and the initial status Videos — Dreamina format `POST /videos` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Request Body `application/json` TypeScript type definition Use the request body type in TypeScript ## Response Body ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X POST "https://aicentos.com/v1/videos" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "veo-3.1-fast-generate-preview", "prompt": "a DJ mixing tracks", "size": "1920x1080", "seconds": "8" }' ``` ```bash { "id": "string", "task_id": "string", "status": "queued" } ``` --- # Dreamina · Get Video Task Status Source: https://docs.aicentos.com/en/api/videos/dreamina/get-task Language: en > Query Dreamina video generation progress and results by task ID Videos — Dreamina format `GET /videos/{task_id}` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Path Parameters task\_id\*string ## Response Body ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X GET "https://aicentos.com/v1/videos/string" \ -H "Authorization: Bearer $AICENTOS_API_KEY" ``` ```bash { "id": "string", "task_id": "string", "status": "queued", "progress": 0, "url": "string", "error": "string" } ``` --- # Sora · Create Video Source: https://docs.aicentos.com/en/api/videos/sora/create Language: en > Submit a Sora video generation task; returns a task ID and the initial status. Use the task ID to query progress Videos — Veo (OpenAI-compatible) `POST /videos` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Request Body `application/json` TypeScript type definition Use the request body type in TypeScript ## Response Body ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X POST "https://aicentos.com/v1/videos" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "veo-3.1-fast-generate-preview", "prompt": "a DJ mixing tracks", "size": "1920x1080", "seconds": "8" }' ``` ```bash { "id": "string", "task_id": "string", "status": "queued" } ``` --- # Sora · Get Video Content Source: https://docs.aicentos.com/en/api/videos/sora/get-content Language: en > Once a task completes, get the URL of the Sora-generated video file by task ID Videos — Veo (OpenAI-compatible) `GET /videos/{task_id}/content` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Path Parameters task\_id\*string ## Response Body ### ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X GET "https://aicentos.com/v1/videos/string/content" \ -H "Authorization: Bearer $AICENTOS_API_KEY" ``` ```bash { "url": "string", "expires_at": 0 } ``` --- # Sora · Get Video Task Status Source: https://docs.aicentos.com/en/api/videos/sora/get-task Language: en > Query Sora video generation progress by task ID to get the status and failure reason Videos — Veo (OpenAI-compatible) `GET /videos/{task_id}` ## Authentication Store your API key in `AICENTOS_API_KEY`; the shell examples expand it in the `Authorization: Bearer` header. The API Key obtained under "Token Management" in the console Location: `header` ## Path Parameters task\_id\*string ## Response Body ### `application/json` ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" curl -X GET "https://aicentos.com/v1/videos/string" \ -H "Authorization: Bearer $AICENTOS_API_KEY" ``` ```bash { "id": "string", "task_id": "string", "status": "queued", "progress": 0, "url": "string", "error": "string" } ``` --- # Errors Source: https://docs.aicentos.com/en/billing/errors Language: en > HTTP status codes, error response structure, common errors and solutions aicentos follows the **OpenAI error response format** exactly. When an SDK throws, just catch the corresponding exception. ## Error response structure Every error response has this shape: ```bash { "error": { "message": "Your API key does not have access to gpt-5", "type": "permission_denied", "code": "model_not_allowed", "param": "model" } } ``` | Field | Meaning | | --------- | ------------------------------------------------- | | `message` | Human-readable error description | | `type` | Error category (see table below) | | `code` | Fine-grained error code (for programmatic checks) | | `param` | Name of the offending parameter, if any | ## HTTP status code reference | Status | Type | Common causes | | ------ | ------------------------ | ----------------------------------------------------------------- | | `400` | `invalid_request_error` | Malformed request body, invalid parameters, misspelled model name | | `401` | `authentication_error` | API key missing / wrong / revoked | | `402` | `insufficient_quota` | Insufficient balance | | `403` | `permission_denied` | Key disabled, model not authorized, IP not on the allowlist | | `404` | `not_found` | Wrong endpoint path, wrong model ID | | `408` | `request_timeout` | Upstream timeout (usually no response for over 60s) | | `413` | `payload_too_large` | Request body too large (images, files) | | `415` | `unsupported_media_type` | Wrong Content-Type | | `422` | `invalid_request_error` | Request body parses but is semantically invalid | | `429` | `rate_limit_exceeded` | Rate limit hit; lower the request rate and retry | | `500` | `server_error` | Internal platform error (rare) | | `502` | `bad_gateway` | Upstream service failure | | `503` | `service_unavailable` | Upstream overloaded; retry later | | `504` | `gateway_timeout` | Upstream response timed out | ## Common errors and fixes ### 401 — Invalid API key ```bash { "error": { "message": "Incorrect API key provided", "type": "authentication_error" } } ``` **Checklist**: * Is the `Authorization` header in `Bearer sk-xxx` format (note the space) * Did copying the key from the console pick up spaces / newlines * Is the key deleted / disabled / expired * Did a test key end up in production ### 402 — Insufficient quota ```bash { "error": { "message": "Insufficient quota", "type": "insufficient_quota" } } ``` Top up → **Wallet Management** in the console. Turn on [balance alerts](https://docs.aicentos.com/en/billing/pricing#balance-alerts) to keep it from happening again. ### 403 — Model not allowed ```bash { "error": { "message": "Model gpt-5 not allowed for this key", "code": "model_not_allowed" } } ``` The token was created with an **allowed models** allowlist, and the requested model is not on it. Change the token settings or use another key. ### 404 — Model not found ```bash { "error": { "message": "The model 'gpt-4-turbo-2024-04-09' does not exist", "code": "model_not_found" } } ``` The model ID is misspelled or has been retired. Check the [model marketplace](https://aicentos.com/pricing) for currently available IDs. ### 429 — Rate limit exceeded The `Retry-After` response header tells you how many seconds to wait before retrying. Lower your concurrency and request rate to recover. ### 500 / 502 / 503 — Service errors Usually upstream turbulence. **Retrying 2-3 times automatically** usually succeeds. If it lasts more than 5 minutes: * Check the [status page](https://status.aicentos.com) (if available) * Contact support ### 408 / 504 — Timeouts No response after 60 seconds. Common causes: * The prompt is so long that the model "thinks" past the timeout * Streaming is not enabled (add `stream: true` for long responses) **Fixes**: * Shorten the prompt * Enable streaming: `{ "model": "...", "messages": [...], "stream": true }` * Switch to a faster model (e.g. from `gpt-4o` to `gpt-4o-mini`) ## SDK error handling examples ```bash export AICENTOS_API_KEY="sk-your-aicentos-api-key" ``` ### Python ```python import os from openai import OpenAI, APIError, RateLimitError, AuthenticationError client = OpenAI(api_key=os.environ["AICENTOS_API_KEY"], base_url="https://aicentos.com/v1") try: resp = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "hi"}], ) except AuthenticationError: print("Invalid API key") except RateLimitError as e: print(f"Rate limited, retry in {e.response.headers.get('Retry-After')}s") except APIError as e: print(f"Other API error: {e.status_code} {e.message}") ``` ### Node.js ```js import OpenAI, { APIError } from 'openai'; const client = new OpenAI({ apiKey: process.env.AICENTOS_API_KEY, baseURL: 'https://aicentos.com/v1', }); try { const resp = await client.chat.completions.create({ ... }); } catch (err) { if (err instanceof APIError) { console.log(err.status, err.code, err.message); } } ``` ## Retry and fallback recommendations | Error type | Recommended handling | | ------------------------------------- | --------------------------------------------------- | | `400` / `401` / `402` / `403` / `404` | **Do not retry** — code / config error; debug first | | `429` | Retry per `Retry-After` with exponential backoff | | `500` / `502` / `503` / `504` / `408` | Retry 1-3 times immediately, 1-5s apart | The official OpenAI SDKs ship with sensible retry policies by default — **use the SDK in production code instead of hand-rolled fetch calls**. --- # Supported Models Source: https://docs.aicentos.com/en/billing/models-list Language: en > Full model list from Google / xAI / OpenAI / Anthropic / Alibaba / DeepSeek / Zhipu / Moonshot / MiniMax aicentos integrates models from OpenAI, Anthropic, Google, xAI, Alibaba Qwen, DeepSeek, Zhipu, Moonshot, MiniMax and other major vendors, covering chat, reasoning, code, image, video, embeddings and more. ## Vendors and flagship models Vendors and models on sale change as upstreams add or retire them; the live model marketplace is authoritative for actual counts. The table below lists representative models only: | Vendor | Flagship models | | ------------ | ------------------------------------------------------- | | Google | `gemini-3.8-flash`, `gemini-3.1-pro`, `nano-banana-2` | | xAI | `grok-4.7`, `grok-4.6`, `grok-build-0.1` | | OpenAI | `gpt-5.6-sol`, `gpt-6-astra`, `gpt-image-2.5` | | Anthropic | `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-5` | | Alibaba Qwen | `qwen3.8-max`, `qwen3-coder-plus` | | DeepSeek | `deepseek-v4-pro`, `deepseek-v4.1-flash` | | Zhipu | `glm-5.3`, `glm-5.2` | | Moonshot | `kimi-k3`, `kimi-k2.6` | | MiniMax | `minimax-m3`, `minimax-m2.7` | See the console for the complete, live model list and pricing: Model marketplace The marketplace can be filtered by **vendor**, **available token group**, **billing type** and **tag**, and switches between card view and table view. [👉 Open the model pricing page](https://aicentos.com/pricing) ## What to fill in when calling models Fill the `model` field with the **model ID** (one-click copy on each card of the model pricing page). Common examples: | You want | Set `model` to | | ------------------ | ------------------ | | Latest Claude Opus | `claude-opus-4-8` | | Claude Sonnet | `claude-sonnet-5` | | Claude Haiku | `claude-haiku-4-5` | | GPT flagship | `gpt-5.6-sol` | | GPT image | `gpt-image-2.5` | | Gemini Pro | `gemini-3.1-pro` | | Gemini Flash | `gemini-3.8-flash` | | Grok | `grok-4.7` | | DeepSeek | `deepseek-v4-pro` | | Qwen | `qwen3.8-max` | | Zhipu GLM | `glm-5.3` | | Kimi | `kimi-k3` | | MiniMax | `minimax-m3` | ## Check real-time model availability Upstream models undergo maintenance or rate limiting from time to time. Before integrating, check the **model health panel** to confirm recent availability and latency for your target models: [👉 Open the model status monitor](https://docs.aicentos.com/status) Each check round records every model's 1-hour / 24-hour / 7-day availability, response latency and endpoint PING; consecutive failures are flagged automatically. ## Restrict available models To limit a key to a few specific models, tick **Allowed models** when creating the **API key** to set an allowlist. For example, a public demo key could allow only `claude-haiku-4-5` and `gemini-3.8-flash`. ## Can't find the model you want? We adapt new models as upstream vendors release them. If a model you need is not available yet, reach out through the contact channels in the console, or follow [X / Twitter](https://x.com/aicentos) for update announcements. --- # Official Pricing Reference Source: https://docs.aicentos.com/en/billing/official-pricing Language: en > Every model available on aicentos, with the official API pricing from OpenAI / Anthropic / Google The table below lists **every model available on aicentos**, priced at the **official API rates** published on each vendor's website (as of May 2026). * Units: **USD per 1M tokens** (image, speech and video are noted separately). * "Cache read" is the input price when the cache is hit; Anthropic also has a cache write price (1.25× the standard input price). * Variants of the same base model (`-thinking` / `-nothinking` / dated versions / `-high/-low/-medium`, etc.) are **priced the same as the base model officially** and are merged in the tables. > Actual prices when calling through aicentos are far below official rates — see the [aicentos pricing page](https://docs.aicentos.com/en/billing/pricing) and the [model marketplace](https://aicentos.com/pricing) for live prices. ## OpenAI ### GPT-5.x series | Model | Official input | Official output | Cache read | | ---------------------------------------------------------------------- | -------------- | --------------- | ---------- | | `gpt-5`, `gpt-5-codex`, `gpt-5-chat-latest` | $1.25 | $10.00 | $0.125 | | `gpt-5-mini` | $0.25 | $2.00 | $0.025 | | `gpt-5-nano` | $0.05 | $0.40 | $0.005 | | `gpt-5-pro` | $15.00 | $120.00 | — | | `gpt-5.1`, `gpt-5.1-codex`, `gpt-5.1-codex-max`, `gpt-5.1-chat-latest` | $1.25 | $10.00 | $0.125 | | `gpt-5.1-codex-mini` | $0.25 | $2.00 | $0.025 | | `gpt-5.2`, `gpt-5.2-codex`, `gpt-5.2-chat-latest` | $1.75 | $14.00 | $0.175 | | `gpt-5.2-pro` | $21.00 | $168.00 | — | | `gpt-5.3-codex`, `gpt-5.3-chat-latest` | $1.75 | $14.00 | $0.175 | | `gpt-5.4` | $2.50 | $15.00 | $0.25 | | `gpt-5.4-mini` | $0.75 | $4.50 | — | | `gpt-5.4-nano` | $0.20 | $1.25 | — | | `gpt-5.4-pro` | $30.00 | $180.00 | — | | `gpt-5.5` | $5.00 | $30.00 | $0.50 | > GPT-5.x context is about 400K (higher for the 5.4 / 5.5 flagships). `-codex` is the coding edition, `-chat` the conversation edition and `-pro` the high-compute edition; their official pricing matches the table above. ### GPT-4o series | Model | Official input | Official output | Cache read | | -------------------------------------------------- | -------------- | --------------- | ---------- | | `gpt-4o`, `gpt-4o-2024-08-06`, `gpt-4o-2024-11-20` | $2.50 | $10.00 | $1.25 | | `gpt-4o-2024-05-13` | $5.00 | $15.00 | — | | `chatgpt-4o-latest` | $5.00 | $15.00 | — | | `gpt-4o-mini`, `gpt-4o-mini-2024-07-18` | $0.15 | $0.60 | $0.075 | | `gpt-4o-search-preview` | $2.50 | $10.00 | — | | `gpt-4o-mini-search-preview` | $0.15 | $0.60 | — | > Context 128K. `-search-preview` additionally charges $10 per 1,000 searches. ### GPT-4.1 series | Model | Official input | Official output | Cache read | Context | | ----------------------------------------- | -------------- | --------------- | ---------- | ------- | | `gpt-4.1`, `gpt-4.1-2025-04-14` | $2.00 | $8.00 | $0.50 | 1M | | `gpt-4.1-mini`, `gpt-4.1-mini-2025-04-14` | $0.40 | $1.60 | $0.10 | 1M | | `gpt-4.1-nano`, `gpt-4.1-nano-2025-04-14` | $0.10 | $0.40 | $0.025 | 1M | ### GPT-4 / GPT-3.5 (legacy) | Model | Official input | Official output | Context | | --------------------------------------------------------------------------------------------- | -------------- | --------------- | ------- | | `gpt-4.5-preview`, `gpt-4.5-preview-2025-02-27` | $75.00 | $150.00 | 128K | | `gpt-4-turbo-2024-04-09`, `gpt-4-turbo-preview`, `gpt-4-0125-preview`, `gpt-4-vision-preview` | $10.00 | $30.00 | 128K | | `gpt-4-0613` | $30.00 | $60.00 | 8K | | `gpt-4-32k-0613` | $60.00 | $120.00 | 32K | | `gpt-3.5-turbo`, `gpt-3.5-turbo-0125` | $0.50 | $1.50 | 16K | | `gpt-3.5-turbo-1106` | $1.00 | $2.00 | 16K | | `gpt-3.5-turbo-instruct` | $1.50 | $2.00 | 4K | | `gpt-3.5-turbo-16k`, `gpt-3.5-turbo-16k-0613` | $3.00 | $4.00 | 16K | | `gpt-3.5-turbo-0613` | $1.50 | $2.00 | 4K | | `babbage-002` | $0.40 | $0.40 | 16K | | `davinci-002` | $2.00 | $2.00 | 16K | > `gpt-4.5-preview` has been marked deprecated by OpenAI; listed for historical reference only. ### o-series reasoning models | Model | Official input | Official output | Cache read | Context | | -------------------------------------------------------------------- | -------------- | --------------- | ---------- | ------- | | `o1`, `o1-2024-12-17`, `o1-preview`, `o1-preview-2024-09-12` | $15.00 | $60.00 | $7.50 | 200K | | `o1-mini`, `o1-mini-2024-09-12` | $1.10 | $4.40 | $0.55 | 128K | | `o1-pro`, `o1-pro-2025-03-19` | $150.00 | $600.00 | — | 200K | | `o3` | $2.00 | $8.00 | $0.50 | 200K | | `o3-pro`, `o3-pro-2025-06-10` | $20.00 | $80.00 | — | 200K | | `o3-mini`, `o3-mini-2025-01-31` (including `-high`/`-low`/`-medium`) | $1.10 | $4.40 | $0.55 | 200K | | `o3-deep-research` | $10.00 | $40.00 | $2.50 | 200K | | `o4-mini` | $1.10 | $4.40 | $0.275 | 200K | | `o4-mini-deep-research`, `o4-mini-deep-research-2025-06-26` | $2.00 | $8.00 | $0.50 | 200K | ### Image / speech / realtime | Model | Official price | | --------------------------------------------------- | ------------------------------------------------------------------ | | `gpt-image-1` | Text input $5 / image input $10 / image output $40 (per 1M tokens) | | `gpt-image-1.5` | Text input $5 / image output about $30 (per 1M tokens) | | `gpt-image-2` | Not published officially; contact us for a quote | | `dall-e-3` | $0.040 / image (1024×1024 standard), $0.080 / image (HD) | | `dall-e-2` | $0.016–$0.020 / image | | `gpt-4o-realtime-preview` (and dated versions) | Text $5 / $20, audio input $40 / audio output $80 | | `gpt-4o-mini-realtime-preview` (and dated versions) | Text $0.60 / $2.40, audio input $10 / output $20 | | `gpt-realtime-2`, `gpt-realtime-2025-08-28` | Text $4 / $16 + audio usage billed separately | | `gpt-4o-audio-preview` (and dated versions) | Text $2.50 / $10, audio input $40 / output $80 | | `gpt-4o-mini-audio-preview` | Text $0.15 / $0.60, audio input $10 / output $20 | | `gpt-4o-mini-tts` | About $0.015 / minute | ## Anthropic Claude | Model | Official input | Official output | Cache write (5m) | Cache read | Context | | ------------------------------------------------- | -------------- | --------------- | ---------------- | ---------- | ------- | | `claude-opus-4-7`, `claude-opus-4-7-thinking` | $5.00 | $25.00 | $6.25 | $0.50 | 1M | | `claude-opus-4-6`, `claude-opus-4-6-thinking` | $5.00 | $25.00 | $6.25 | $0.50 | 1M | | `claude-opus-4-5-20251101` (and `-thinking`) | $5.00 | $25.00 | $6.25 | $0.50 | 200K | | `claude-opus-4-1-20250805` (and `-thinking`) | $15.00 | $75.00 | $18.75 | $1.50 | 200K | | `claude-opus-4-20250514` | $15.00 | $75.00 | $18.75 | $1.50 | 200K | | `claude-sonnet-4-6`, `claude-sonnet-4-6-thinking` | $3.00 | $15.00 | $3.75 | $0.30 | 1M | | `claude-sonnet-4-5-20250929` (and `-thinking`) | $3.00 | $15.00 | $3.75 | $0.30 | 1M | | `claude-sonnet-4-20250514` (and `-thinking`) | $3.00 | $15.00 | $3.75 | $0.30 | 200K | | `claude-haiku-4-5-20251001` (and `-thinking`) | $1.00 | $5.00 | $1.25 | $0.10 | 200K | > Anthropic cache reads are uniformly **0.1×** the standard input price (90% cheaper on a cache hit); cache writes cost 1.25× (5 minutes) or 2× (1 hour). Opus 4 / Sonnet 4 have been marked deprecated by Anthropic. Opus 4.7 uses a new tokenizer and may consume about 35% more tokens for the same text. ## Google Gemini | Model | Official input | Official output | Cache read | Context | | ---------------------------------------------------------------------- | ------------------------------------------------- | ----------------- | ------------ | ------- | | `gemini-3.5-flash` | $1.50 | $9.00 | $0.15 | 1M | | `gemini-3.1-pro-preview` (and `-customtools`/`-high`/`-low`/`-medium`) | $2.00 / $4.00\* | $12.00 / $18.00\* | $0.20–$0.40 | 1M | | `gemini-3.1-flash-lite`, `gemini-3.1-flash-lite-preview` | $0.25 | $1.50 | $0.025 | 1M | | `gemini-3-pro-preview` (and `-thinking`) | $2.00 / $4.00\* | $12.00 / $18.00\* | $0.20–$0.40 | 1M | | `gemini-3-flash-preview` (and `-thinking`) | $0.50 | $3.00 | $0.065 | 1M | | `gemini-2.5-pro` (and `-thinking`/`-nothinking`) | $1.25 / $2.50\* | $10.00 / $15.00\* | $0.125–$0.25 | 1M | | `gemini-2.5-flash` (and `-thinking`/`-nothinking`) | $0.30 | $2.50 | $0.03 | 1M | | `gemini-2.5-flash-lite` | $0.10 | $0.40 | $0.01 | 1M | | `gemini-flash-latest`, `gemini-pro-latest`, `gemini-flash-lite-latest` | Same as the current Flash / Pro / Flash-Lite tier | | | 1M | | `gemini-embedding-001` | $0.15 | — | — | — | | `gemini-embedding-2-preview` | $0.20 | — | — | — | > \*The Gemini Pro series is priced in two tiers by prompt length: ≤200K tokens at the lower price, >200K tokens at the higher price. ### Image / speech / video | Model | Official price | | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `gemini-2.5-flash-image` (Nano Banana) | Input $0.30, image output about $30 / 1M tokens (about $0.039 / image) | | `gemini-3-pro-image-preview`, `gemini-3.1-flash-image-preview` | Billed by image tokens, about $0.04–$0.13 / image | | `gemini-2.5-flash-preview-tts`, `gemini-2.5-pro-preview-tts`, `gemini-3.1-flash-tts-preview` | Speech synthesis, billed by audio tokens | | `veo-3.0-generate-001`, `veo-3.1-generate-preview` | $0.40 / second | | `veo-3.0-fast-generate-001`, `veo-3.1-fast-generate-preview` | $0.15 / second | # All of the above are official list prices from each vendor. Calls routed through aicentos cost more than 10x less. **One API Key for every model above.** [Sign up now →](https://aicentos.com/) | [See live aicentos prices →](https://docs.aicentos.com/en/billing/pricing) --- # Billing Source: https://docs.aicentos.com/en/billing/pricing Language: en > Top-ups and pay-as-you-go — Alipay top-up, per-token billing, balance and usage queries aicentos uses **prepaid balance + pay-as-you-go billing**. Top-ups go into your wallet balance, and each request is charged for what it actually consumes. Balances are settled in **CNY (¥)**. New accounts get **¥1** in free credit at sign-up — run your first request without topping up. ## Top-up Console → **Wallet** → **Add funds**: Wallet ### Top-up tiers **Top-ups of ¥100 and above get a discount — you pay less than the top-up amount**: | Top-up amount | Discount | You pay | | -------------------- | -------- | ---------- | | ¥1 / ¥10 / ¥20 / ¥50 | None | Full price | | ¥100 | 1% OFF | ¥99 | | ¥500 | 2% OFF | ¥490 | | ¥1,000 | 3% OFF | ¥970 | | ¥10,000 | 5% OFF | ¥9,500 | The discount is applied directly to the payment: top up ¥500 and pay ¥490, saving ¥10. Custom amounts and redemption codes for credit are also supported. Top-up tiers ### Payment methods Payment methods * **Alipay**: pay by scanning a QR code, credited quickly * You can also redeem **redemption codes** for credit * See the wallet page for other available payment channels ### Credit validity **Your balance never expires.** Top up with confidence — no need to worry about unused credit. ## Pay-as-you-go Each API request is charged by the **number of tokens actually consumed**: ```bash cost = (input tokens × input price + output tokens × output price) × group multiplier ``` * Each model has its own input / output prices, usually quoted **per 1M tokens** * The **group multiplier** depends on the group your key belongs to; it varies by group * See the [model pricing page](https://aicentos.com/pricing) for live prices and multipliers ### Models billed per request Multimedia models such as image and video models may be billed **per request** or **per image** instead of per token — see the model pricing page for details. ## Check balance / usage Open **Wallet** in the left sidebar of the console to see your balance and total usage: | Metric | Meaning | | ------------------- | ------------------------------- | | **Current balance** | Remaining credit in the account | | **Total usage** | Credit consumed to date | | **API requests** | Total request count | For finer-grained details, open **Usage Logs**: filter by time, model or key to see the token count and charge for each request. The **Dashboard** provides per-model call trends and quota statistics. ## Balance alerts Console → **Profile** → notification settings: set a balance alert threshold. You are notified automatically when the balance drops below it, so your work is not interrupted by an exhausted balance. Available thresholds and notification channels depend on what the console shows. ## Refunds and invoices * Balances are **not refundable in cash** * Erroneous charges / accidental calls can be compensated with credit after support verifies them * Balances on long-idle accounts **do not expire** * Invoices: available to enterprise customers who sign a contract; invoice types and process are confirmed during business communication ## Team / shared credit Allocate credit to team members: * Create a separate key for each member under **API Keys** * Set an individual **quota cap** per key * Use **Allowed models** when needed to restrict which models a key can call * Audit consumption per key in **Usage Logs** ## Referral rewards Console → **Wallet** → **Referral program**: invite friends to sign up and both of you earn rewards. Users who register with your personal referral link are linked to your account, and accumulated rewards can be transferred to your balance at any time. See the wallet page for current reward rates. ## Next steps * [Quickstart](https://docs.aicentos.com/en/quickstart) — get connected in three steps and run your first request * [Supported models](https://docs.aicentos.com/en/billing/models-list) — the full model list * [Error handling](https://docs.aicentos.com/en/billing/errors) — troubleshoot insufficient balance and other errors --- # Amp Source: https://docs.aicentos.com/en/clients/amp Language: en > Use aicentos in Amp — override the backend address through the configuration file Amp is a coding agent from Sourcegraph; the CLI and the IDE extensions share the same account and settings. Instead of the usual "OpenAI-compatible Base URL" input, you point the entire backend at a custom endpoint via the `amp.url` setting, with credentials stored separately in a secrets file. ## Prerequisites First create a dedicated key for Amp on the console's "API Keys" page (naming it `amp-cli` makes usage easier to track): * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | API Key | The key created in the console | | Base URL | `https://aicentos.com/v1` | | Model | A model name from the Model Gallery in the console | ## Setup steps All of Amp's settings carry the `amp.` prefix; the user-level configuration file is located at: * macOS / Linux: `~/.config/amp/settings.json` * Windows: `%USERPROFILE%\.config\amp\settings.json` Create the directories first, then write the backend address: ```bash mkdir -p ~/.config/amp ~/.local/share/amp ``` ```json { "amp.url": "https://aicentos.com/v1" } ``` The API Key does not go in this file; it lives in a separate secrets file under the key `apiKey@`: ```json { "apiKey@https://aicentos.com/v1": "sk-your-API-Key" } ``` Once the configuration takes effect, `amp login` is no longer needed and requests go straight to the endpoint you specified. If you previously signed in, run `amp logout` first and then restart `amp` to avoid a leftover login state overriding the configuration. You can also override temporarily with environment variables, which is handy for a one-off verification: ```bash export AMP_URL="https://aicentos.com/v1" export AMP_API_KEY="sk-your-API-Key" ``` **Note:** once these two variables are set, Amp skips the login flow and they take precedence over the configuration file. ## Test Send a lightweight request first to confirm the endpoint has been switched: ```bash amp -x "Answer in one sentence: what is 1+1?" ``` A normal response means the configuration is active. If you get a 401, the key in the secrets file most likely does not exactly match `amp.url` (including whether `/v1` is at the end). ## Notes * Amp's backend protocol is its own management API, not the generic OpenAI-compatible protocol, so `amp.url` must point at an endpoint that also serves the Anthropic Messages (`/v1/messages`) style API. * aicentos offers a native Claude format API (see [Native Claude format](https://docs.aicentos.com/en/api/chat/claude)) and an OpenAI-compatible API (see [Chat Completions](https://docs.aicentos.com/en/api/chat/openai/chat-completions)); Amp uses the former. * Amp requests fixed model IDs; if the endpoint has no model with that name, it falls back or errors. When that happens, check the model name against the Model Gallery in the console. * Settings for the IDE extensions (VS Code / Cursor / Windsurf) are maintained separately from the CLI; the Amp URL and Amp API Key need to be filled in there as well. * A `.amp/settings.json` in the workspace overrides user-level settings; when troubleshooting, first make sure no such file exists in the current directory. ## Related links * Official settings documentation: [https://ampcode.com/docs/cli/settings](https://ampcode.com/docs/cli/settings) --- # Antigravity CLI Source: https://docs.aicentos.com/en/clients/antigravity-cli Language: en > Use aicentos in Antigravity CLI — connect through API Key mode Antigravity CLI is a command-line tool from Google that supports connecting to Gemini API-compatible services through API Key mode. This document describes how to configure Antigravity CLI to use a custom API endpoint. ## Installation Choose the installation method for your operating system: ### macOS / Linux ```bash curl -fsSL https://antigravity.google/cli/install.sh | bash ``` ### Windows (PowerShell) ```powershell irm https://antigravity.google/cli/install.ps1 | iex ``` ### Windows (CMD) ```cmd curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd ``` ### Verify the installation ```bash agy --version ``` ## Configuration ### Enable API Key mode Edit `~/.gemini/antigravity-cli/settings.json` and add to the existing JSON: ```json { "modelProvider": "gemini" } ``` ⚠️ **Note**: setting only `GEMINI_API_KEY` does not switch the authentication method. `modelProvider` must be set to the lowercase `"gemini"`. ### Set environment variables ```bash export GOOGLE_GEMINI_BASE_URL="https://aicentos.com" export GEMINI_API_KEY="your_api_key_here" ``` **Important:** * `GOOGLE_GEMINI_BASE_URL` takes the service root address, without any specific API path. The endpoint must be Gemini API-compatible. * Put your API Key in `GEMINI_API_KEY`. * Run the commands above in the same shell that launches `agy`. The CLI does not read `.env` files or `GOOGLE_API_KEY`. To make it permanent, add the two `export` lines to `~/.zshrc` or `~/.bashrc`. ## Launch and verify ```bash agy --model gemini-2.0-flash ``` Once `Gemini API key` shows at the top, start a conversation. ### Troubleshooting * **Still asks to sign in**: check `"modelProvider": "gemini"`, then quit and restart `agy`. * **Missing key at startup**: set `GEMINI_API_KEY` again in the current shell. * **Request failures**: check the API Key, the service root address, and access permission for the chosen model. ## Notes * Both the `modelProvider` setting and the environment variables must be in place for API Key mode to work * Environment variables must be set in the shell session that launches the CLI, or written to a shell configuration file to persist * The service endpoint must be compatible with the Gemini API specification ## Related links * Official documentation: [https://docs.aicentos.com/clients/antigravity-cli.html](https://docs.aicentos.com/clients/antigravity-cli.html) --- # Antigravity Source: https://docs.aicentos.com/en/clients/antigravity Language: en > Google Antigravity does not currently support a custom Base URL — the limitation and available alternatives Antigravity is Google's agentic IDE. One caveat up front: **the official Antigravity desktop IDE does not support custom API endpoints and offers no BYOK (bring your own key)**. The model picker shows a fixed list maintained by Google and currently cannot point at aicentos. This document explains the basis for this limitation, how to verify it, and three workable alternative paths. ## Why it cannot connect directly Google's account plans documentation states explicitly that Antigravity does not yet support bring-your-own-model or bring-your-own-endpoint. Several configuration keys circulating in the community (for example `antigravity.ai.provider` or `antigravity.openai-compatible.endpoint` written into `~/.antigravity/settings.json`) are not officially supported: in practice requests are not routed to the custom endpoint, or silently fall back to the default model, and no custom entry appears in the model picker. In other words, this is not a case of "the configuration was written wrong" — the current version simply does not expose the capability. The IDE's `Settings → Models` has no Base URL field to fill in either. ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | API Key | The key created in the console | | Base URL | `https://aicentos.com/v1` | | Model | A model name from the Model Gallery in the console | The table above lists the generic aicentos-side parameters, for use with any of the alternatives below. ## Alternatives ### Option 1: Switch to Antigravity CLI (recommended, Gemini protocol only) The command-line tool of the same name, `agy`, supports endpoint overrides: connecting via `GOOGLE_GEMINI_BASE_URL` + `GEMINI_API_KEY` works, but it only accepts the Gemini protocol and can only call Gemini-family models. See [Connect Antigravity CLI](https://docs.aicentos.com/en/clients/antigravity-cli) for the details. If what you want is "Antigravity's interaction style in the terminal", this is the easiest path. ### Option 2: Wrap local models or third-party services as MCP tools Antigravity's Customizations panel supports registering MCP Servers. You can wrap a local service as an MCP tool and attach it as an **invocable tool**. Keep in mind: this does not replace the IDE's reasoning model — it just gives the agent one more tool. ### Option 3: Community forks or local proxies * The community fork `open-antigravity` supports any OpenAI-compatible endpoint with custom models — the cleanest path outside the official build. * Some people also use local interception proxies to rewrite the IDE's outbound traffic. This route has no official support, the configuration is fragile and breaks on every upgrade; it is not recommended for production use. ## Test Whichever path you choose, confirm connectivity with a simple prompt first before putting it to real use. For agent-style tasks, start with a small repository. ## Notes * **Do not treat "a configuration key appears to exist" as "the feature works"**. Most `antigravity.*` keys inside the IDE are community guesses; writing them produces no error but has no effect either. * If you need the OpenAI-compatible protocol or want to call Claude / GPT-family models, the Antigravity desktop IDE currently cannot do it — prefer clients that support a custom Base URL such as [Cursor](https://docs.aicentos.com/en/clients/cursor) and [Windsurf](https://docs.aicentos.com/en/clients/windsurf). * Antigravity CLI and the desktop IDE are two separate configurations; the CLI's endpoint override does not affect the IDE. * Before using any third-party fork or proxy, evaluate its security and maintenance status yourself. ## Related links * [Connect Antigravity CLI](https://docs.aicentos.com/en/clients/antigravity-cli) --- # Augment Code Source: https://docs.aicentos.com/en/clients/augment-code Language: en > Augment Code does not open up custom endpoints, so the model cannot be switched to aicentos — the reasoning and the alternatives Augment Code is a coding plugin for VS Code / JetBrains / Vim, plus the `auggie` CLI. It **does not support a custom Base URL and offers no BYOK**: models come from the official catalog, the account must sign in through `auggie auth login`, and requests cannot be pointed at aicentos. ## Why it cannot connect directly * The configuration files have no fields such as `baseUrl` or `apiKey`, and the plugin settings panel has no endpoint input box either. * The CLI recognizes only two related environment variables: `AUGMENT_SESSION_AUTH` (sign-in state) and `AUGMENT_DISABLE_AUTO_UPDATE` (turn off auto-update). There is no variable that overrides the endpoint. * `--model` only accepts names from the official model catalog (Claude, GPT, Gemini, GLM, Kimi and so on); a third-party model name is rejected. * The official docs index `docs.augmentcode.com/llms.txt` has no entry for BYOK or a custom provider. ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | API Key | The key created in the console | | Base URL | `https://aicentos.com/v1` | | Model | A model name from the Model Gallery in the console | The table above lists the generic aicentos-side parameters, for use with any of the alternatives below. ## Alternatives ### Alternative 1: Switch to a coding agent that supports custom endpoints [Craft Agent](https://docs.aicentos.com/en/clients/craft-agent), [Gajae Code](https://docs.aicentos.com/en/clients/gajae-code), and [Oh My Pi](https://docs.aicentos.com/en/clients/oh-my-pi) are all terminal coding agents whose configuration accepts `baseUrl` directly. ### Alternative 2: Stay in VS Code and change the plugin [Cline](https://docs.aicentos.com/en/clients/cline), [Roo Code](https://docs.aicentos.com/en/clients/roo-code), and [Kilo](https://docs.aicentos.com/en/clients/kilo) all support an OpenAI-compatible provider and can take `https://aicentos.com/v1` directly. ### Alternative 3: Move only the batch jobs If your team already pays for an Augment subscription and does not want to give up its completion experience, keep the official model for everyday editing and move batch refactoring and scripted tasks to a CLI that supports custom endpoints. ## Test After switching to any of the alternative clients, first confirm connectivity with one simple prompt, then check in the console whether usage is being recorded against the new key. ## Notes * Some tutorials online write keys such as `augment.modelProvider: "openai-compatible"`, `augment.baseUrl`, `augment.apiKeyEnv`. They do not exist in the official configuration: writing them raises no error and has no effect, and `--model` still only accepts the official catalog. * Do not take "the config key raised no error" as "the configuration took effect". The way to verify is to ask it for the current model name and compare that against the official catalog. * Augment's cloud index and completion have no equivalent replacement; switching clients means switching the whole workflow, so try it on a small repository first. ## Related links * [Augment Code CLI docs](https://docs.augmentcode.com/cli/overview) --- # CC Switch Source: https://docs.aicentos.com/en/clients/cc-switch Language: en > One-click import from the aicentos console into CC Switch to manage Claude Code / Codex / Gemini CLI CC Switch is a cross-platform AI CLI configuration manager that centrally manages model Provider configurations for tools such as Claude Code, Codex and Gemini CLI, letting you switch between CLI tools or configuration sets in one click instead of editing environment variables over and over. The aicentos console has **CC Switch one-click import** built in: no need to copy the Base URL and key by hand — a few clicks write the configuration into CC Switch. ## Prerequisites 1. Sign in to the [aicentos console](https://aicentos.com/) 2. Make sure the account has a balance (new accounts get ¥1 in trial credit; top up under **Wallet** when it runs out) 3. Install CC Switch (see below) ## Install CC Switch CC Switch is an open-source project hosted on GitHub: [farion1231/cc-switch](https://github.com/farion1231/cc-switch). Open the [Releases page](https://github.com/farion1231/cc-switch/releases) and, in the latest release's asset list, pick the installer for your operating system: * macOS: `.dmg` * Windows: `.msi` * Linux: `.AppImage` / `.deb` After downloading, install it the normal way for your system and **open CC Switch at least once**, so the console's import link can detect the local installation. ## One-click import (recommended) ### Step 1: Start the import in the console Open **API Keys** in the console's left sidebar, click **⋯** on the row of the key you want to use, and choose **CC Switch** in the menu: Choosing CC Switch in the API key list ### Step 2: Choose the app and models In the **Fill into CC Switch** dialog, choose the target app (Claude / Codex / Gemini) and confirm the models to use: Filling in the CC Switch configuration | Field | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | App | Which CLI's configuration to write. **Claude** uses the Anthropic protocol, **Codex** uses the OpenAI-compatible format, **Gemini** uses the native Gemini format | | Name | The configuration name shown in CC Switch after the import; customizable | | Main model | The default model for this configuration; required | | Haiku / Sonnet models | Tiered models under the Claude app; set as needed | For model names, see [Supported models](https://docs.aicentos.com/en/billing/models-list), e.g. `claude-opus-4-8`, `claude-sonnet-5`, `claude-haiku-4-5`. When done, click **Open CC Switch**. ### Step 3: Confirm the launch in the browser The browser asks whether to open CC Switch; click **Open CC Switch.app**: Browser asking to open CC Switch > If you check "Always allow aicentos.com to open links of this type in the associated app", this confirmation dialog will not appear again on future imports. ### Step 4: Confirm the import in CC Switch CC Switch pops up **Confirm provider import**; verify the information and click **Import**: CC Switch confirming the import The dialog lists the endpoint, key and tiered models that will be written; after verifying, click **Import**. Once the import completes, `aicentos Claude` appears in CC Switch's configuration list; click it to switch: Import complete ## Manual configuration If you would rather not use one-click import, click **Add new provider** in CC Switch and fill in manually: CC Switch adding a new provider | Field | What to enter | | ------------- | ------------------------------------------------------------------------------------- | | Provider name | `aicentos` (custom, anything recognizable) | | API Key | The key created on the console's **API Keys** page, shaped like `sk-xxxxxxxx` | | Request URL | Enter `https://aicentos.com` for Claude / Gemini; `https://aicentos.com/v1` for Codex | > **For the Anthropic protocol, enter the root address only** — do not manually append `/v1/messages`; the client concatenates it automatically. ## Next steps * [Model status monitoring](https://docs.aicentos.com/status) — real-time availability of each model * [Supported models](https://docs.aicentos.com/en/billing/models-list) — the full model list and IDs * [Billing](https://docs.aicentos.com/en/billing/pricing) — top-ups and pay-as-you-go pricing --- # Chatbot UI Source: https://docs.aicentos.com/en/clients/chatbot-ui Language: en > Use aicentos in Chatbot UI — connect through custom OpenAI-compatible settings Chatbot UI is an open-source ChatGPT-style web frontend that supports a custom OpenAI-compatible interface. ## Self-hosted deployment configuration For self-hosted instances, configure the custom interface through environment variables: ```bash OPENAI_API_KEY=codex_your_api_key OPENAI_API_HOST=https://aicentos.com/v1 ``` Restart the service after configuring and the new interface takes effect. Once the environment variables are set, the corresponding inputs in the UI are disabled (to keep shared instances from leaking the configuration). ## UI configuration For instances that do not restrict UI settings, fill in the following in the settings panel: * **OpenAI API Key**: your `codex_...` or `sk-...` key * **OpenAI API Host / Base URL**: `https://aicentos.com/v1` ## Notes * Chatbot UI needs Supabase for authentication and data storage * The API Host should be the service root path including `/v1` * Available models are determined by the list returned by `GET /v1/models` ## Related links * GitHub: [https://github.com/mckaywrigley/chatbot-ui](https://github.com/mckaywrigley/chatbot-ui) --- # Chatbox Source: https://docs.aicentos.com/en/clients/chatbox Language: en > Use aicentos in Chatbox — connect through custom OpenAI-compatible settings Chatbox is a desktop AI client that supports the OpenAI-compatible interface; connect it to this service through the "OpenAI API Compatible" mode. ## Open the settings Click the **Settings** icon in the left sidebar and go to the **Model** tab. ## Select the AI provider Choose `OpenAI API Compatible` in the **Model Provider** dropdown. ## Configuration to fill in Fill in the following fields: | Field | Value | | -------- | --------------------------------------------- | | API Key | Your `codex_...` or `sk-...` key | | API Host | `https://aicentos.com` | | Model | `gpt-5-codex-mini` or another available model | **Note:** the Chatbox **API Host** field only takes the service root address — **do not** add the `/v1` suffix. Example: `https://aicentos.com` ## Test After saving, start a conversation and confirm it returns normally. ## Notes * Enter the service root path without `/v1` in the API Host field; Chatbox appends the API path automatically * Available models are determined by the list returned by `GET /v1/models` ## Related links * Official documentation: [https://docs.chatboxai.app/en/guides/providers](https://docs.chatboxai.app/en/guides/providers) --- # Cherry Studio Source: https://docs.aicentos.com/en/clients/cherry-studio Language: en > Use aicentos in Cherry Studio — add an OpenAI-compatible provider to access every model Cherry Studio supports custom OpenAI-compatible model providers. Once aicentos is added, every model aicentos offers becomes available inside the app. ## Prerequisites | Field | Value | | ---------------------- | --------------------------------------------------------- | | Provider name | `aicentos` | | API address (Base URL) | `https://aicentos.com/v1` | | API Key | Created in the aicentos console | | Model name | The full model name from the Model Gallery in the console | For how to get an API Key, see [Quickstart](https://docs.aicentos.com/en/quickstart). ## Setup steps * Open Cherry Studio's settings and go to **Model Services / Provider Management**. * Add a new **OpenAI-compatible** provider. * Enter `aicentos` as the provider name. * Fill in the API Key and the API address `https://aicentos.com/v1`. * Save the configuration; if there is a "Check / Test connection" button, click it to verify. ### Adding models If no models are detected automatically, add the model names manually. > Model names must be copied in full — the case, hyphens and date suffixes must not change. Follow the [Model Gallery](https://aicentos.com/pricing) / [Supported models](https://docs.aicentos.com/en/billing/models-list). ## Test and troubleshoot Send a test message to confirm connectivity, for example: ```bash Hello, introduce yourself in one sentence. ``` Common issues: * **Authentication error**: check the API Key for extra spaces. * **Timeout**: check the network or the service status. * **Model unavailable**: use the full model name from the console. * **Conversation fails**: confirm the aicentos provider is selected. --- # Claude Code Source: https://docs.aicentos.com/en/clients/claude-code Language: en > Install Claude Code from scratch and connect it to aicentos — Node.js environment, Windows / Mac installation, environment variables and CC Switch configuration, plus a mobile Termux tutorial Claude Code is compatible with the Anthropic protocol. Just point the Base URL at aicentos and fill in your API Key to use every Claude model aicentos offers. ## Step 1: Install Claude Code ### Install the Node.js environment Go to the [Node.js website](https://nodejs.org/) and download the latest LTS version. Make sure to pick the installer that matches your operating system. Node.js website download After the installation finishes, open a terminal (use git bash or cmd on Windows) and enter: ```bash node -v ``` If you see a version number, the installation succeeded. ### Install Claude Code Before installing, make sure the Node.js environment above is set up. **Windows:** press `Win + R`, type `cmd` and hit Enter to open a terminal, then run: ```bash npm install -g @anthropic-ai/claude-code ``` **Mac / Linux:** run the following in a terminal: ```bash npm install -g @anthropic-ai/claude-code ``` Or use the officially recommended curl script: ```bash curl -fsSL https://claude.ai/install.sh | bash ``` Once installed, test whether it works: ```bash claude --version ``` If a version number shows up, the installation succeeded. claude --version installed successfully ## Step 2: Get an API key Go to the [aicentos website](https://aicentos.com/) console to create your API key. For detailed key creation steps, see [Quickstart](https://docs.aicentos.com/en/quickstart). ## Step 3: Configure the connection Two options are provided below: **manage everything with CC Switch** (recommended), or **configure it manually**. ### Option 1: Use CC Switch (recommended) If you frequently switch between multiple Providers or CLI tools, CC Switch lets you manage configurations centrally without editing environment variables over and over. See [Connect with CC Switch →](https://docs.aicentos.com/en/clients/cc-switch) ### Option 2: Manual configuration If you would rather not install an extra tool, just set the environment variables. Pick one of the three options below. #### Temporary (current terminal session) Good for quick tests; only effective in the current terminal window: ```bash export ANTHROPIC_BASE_URL="https://aicentos.com" export ANTHROPIC_AUTH_TOKEN="sk-your-API-Key" export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 claude ``` If your version does not recognize `ANTHROPIC_AUTH_TOKEN`, use this instead: ```bash export ANTHROPIC_API_KEY="sk-your-API-Key" ``` #### Persistent (config file, recommended for the manual route) Edit `~/.claude/settings.json` and add: ```bash { "env": { "ANTHROPIC_BASE_URL": "https://aicentos.com", "ANTHROPIC_AUTH_TOKEN": "sk-your-API-Key", "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1", "CLAUDE_CODE_ATTRIBUTION_HEADER": "0" } } ``` On **Windows** you can also open System Environment Variables and, under **User variables**, click **New** to create the following two variables: | Variable | Value | | ---------------------- | ------------------------- | | `ANTHROPIC_BASE_URL` | `https://aicentos.com` | | `ANTHROPIC_AUTH_TOKEN` | The key created in Step 2 | Restart Claude Code after saving for the change to take effect. #### Shell configuration (global) Add the environment variables to `~/.zshrc` or `~/.bashrc`: ```bash nano ~/.zshrc ``` Append the following at the end of the file: ```bash # aicentos API Key (the key created in Step 2) export ANTHROPIC_AUTH_TOKEN="your-api-key" # aicentos Base URL export ANTHROPIC_BASE_URL="https://aicentos.com" ``` Save and exit, then run `source ~/.zshrc` (or reopen the terminal) for it to take effect. ## Step 4: Run Claude Code Go to your project directory and start it: ```bash cd /path/to/your/project claude ``` ## Specifying a model Use `--model` at launch to pick a specific model: ```bash claude --model claude-opus-4-7 ``` Model names follow those listed in the Model Gallery of the aicentos console; see [Supported models](https://docs.aicentos.com/en/billing/models-list). ## Common commands | Command | Purpose | | ------------------------- | ------------------------------------------------------------ | | `/add-dir` | Add an extra working directory | | `/resume` | Go back to a previous conversation | | `/clear` | Clear the conversation history | | `/compact [instructions]` | Compact the conversation, optionally with focus instructions | | `/config` | View / modify configuration | | `/cost` | Show token usage statistics | | `/doctor` | Check the health of the Claude Code installation | | `/help` | Get usage help | | `/init` | Initialize the project with a CLAUDE.md guide | | `/login` | Switch Anthropic accounts | | `/logout` | Sign out of the Anthropic account | | `/mcp` | Manage MCP server connections and OAuth authentication | | `/memory` | Edit CLAUDE.md memory files | | `/model` | Select or change the AI model | | `/permissions` | View or update permissions | | `/pr_comments` | View pull request comments | | `/review` | Request a code review | | `/status` | View account and system status | | `/terminal-setup` | Install the Shift+Enter key binding (iTerm2 and VSCode only) | | `/vim` | Enter vim mode, toggling between insert and command modes | ## Running on a phone (Termux + Ubuntu) For moments like "no computer at hand, a bug to fix on the go, or a commute that could use some vibe coding". No root and no flashing required — everything happens inside Termux. The whole setup takes 10-20 minutes depending on your network speed. ### What you'll get * A full **Ubuntu** environment running on your phone (no impact on the system, barely takes any space) * The full **Claude Code** command-line tool (identical to the desktop version) * Low-cost access through **aicentos**, switching between Opus / Sonnet / Haiku in seconds ### Prerequisites Only two things are needed: * **An Android phone** (iOS cannot install Termux, so this tutorial does not apply) * **A [aicentos](https://aicentos.com) account + API Key** ([top up the wallet →](https://aicentos.com/wallet), [create a Key →](https://aicentos.com/keys)) **Do not install Termux from Google Play** — that version is outdated and unmaintained, and the scripts below will fail to install. Get the latest release from [F-Droid](https://f-droid.org/packages/com.termux/) or the [Termux GitHub Releases](https://github.com/termux/termux-app/releases). ### Step 1: Install the tmoe-linux one-line script Open Termux, wait for the command prompt (a line with `~ $`), then copy the following line in **whole** and press Enter: ```bash . <(curl -L l.tmoe.me) ``` > This mirror is intended for mainland China; users elsewhere should use `. <(curl -L git.io/linux.sh)`. When it finishes, a **graphical menu** pops up, like this: tmoe main menu Use the volume keys to move up and down and Enter to confirm (or just tap the screen). ### Step 2: Install the Ubuntu container In the tmoe menu, keep choosing `安装 Linux 发行版` / `Install GNU/Linux container` until you reach the distro list: Linux distro selection **Ubuntu is strongly recommended** (best compatibility, the most apt documentation, and the easiest to search for solutions). Pick the latest LTS (e.g. 22.04 / 24.04). Download + extraction takes a few minutes depending on your network speed — just wait. ### Step 3: Enter the container and learn "where you are" After installation you will most likely be dropped into the container automatically. **This is where beginners get lost most easily**, so here is how to tell the difference: **Inside the Ubuntu container** (the prompt looks roughly like this): Inside the container **Still in Termux, not inside** (a plainer prompt): Still in Termux If it is the latter, go back to Termux and enter: ```bash tmoe ``` Open the menu again and find `启动容器` / `Start container` to enter. **Remember this rule**: installing Node, installing Claude Code, running the claude command — **all of this must be done inside the Ubuntu container**. Termux's own `pkg` package system cannot install Claude Code. ### Step 4: Install Node.js and Claude Code Once you have confirmed you are inside the Ubuntu container, run: ```bash # 1. Update the apt package index apt update # 2. Install Node.js + npm (the version shipped with Ubuntu is fine) apt install -y nodejs npm # 3. Install Claude Code globally npm install -g @anthropic-ai/claude-code ``` If npm reports a permission error, prefix the command with `sudo`. If there is no `sudo` command at all, you are the root user — just run it directly. ### Step 5: Connect Claude Code to aicentos Claude Code connects to the official endpoint by default, which means two problems for users in mainland China: **no quota, and no connection**. We change two environment variables to point it at aicentos: ```bash # 1. Install the nano text editor (may not be present in the container by default) apt install -y nano # 2. Edit your shell configuration nano ~/.bashrc ``` Use the arrow keys to move to the very end of the file, then paste on a new line: ```bash export ANTHROPIC_BASE_URL=https://aicentos.com export ANTHROPIC_AUTH_TOKEN=your-aicentos-api-key ``` Replace `your-aicentos-api-key` with the API Key you created in the [aicentos console](https://aicentos.com/keys) (usually starting with `sk-`). The result looks roughly like this: bashrc export at the end of the file **Save and exit**: * Press `Ctrl + X` (the Ctrl key on your phone's keyboard; Termux shows this virtual key by default) * Press `Y` when asked to save * Press `Enter` to confirm the file name Make the configuration take effect immediately: ```bash source ~/.bashrc ``` ### Step 6: Launch ```bash claude ``` **On first launch** you will be asked to choose a sign-in method: * If you previously signed in with an official account and want to clear it, type `/logout` in Claude Code; once it signs out, starting `claude` again will use your environment variables * With a fresh install it may skip this and use the environment variables directly Once you see the Claude Code prompt, you are done — ask it something to try: ```bash Hello, write me a Python hello world script ``` ### Quick command reference on mobile Inside Claude Code: | Command | Purpose | | ---------- | ----------------------------------------------------------------------------------- | | `/model` | Switch models (Opus / Sonnet / Haiku) | | `/logout` | Sign out of the current account (needed once after switching environment variables) | | `/clear` | Clear the current session context | | `/help` | See all commands | | `Ctrl + C` | Interrupt the current generation | Outside the container (in Termux): | Command | Purpose | | --------------- | ----------------------------------------- | | `tmoe` | Open the tmoe main menu | | Start container | Choose "Start container" in the tmoe menu | ### Common pitfalls on mobile **1. `npm install -g` stalls or hangs** Likely the network. Inside the container you can first run `npm config set registry https://registry.npmmirror.com` to switch to the npmmirror registry, then `npm install -g @anthropic-ai/claude-code`. **2. `claude` command not found** The path of the command installed by `npm install -g` is not in `PATH`. Append the following to the end of `~/.bashrc`: ```bash export PATH="$PATH:$(npm config get prefix)/bin" ``` Then `source ~/.bashrc`. **3. 401 / insufficient balance** Check your [aicentos wallet](https://aicentos.com/wallet) balance, and whether `ANTHROPIC_AUTH_TOKEN` was copied in full (watch for stray spaces at either end). **4. Want Sonnet instead of burning money on Opus** After entering `claude`, type `/model` and pick sonnet. Or add `export ANTHROPIC_MODEL=claude-sonnet-5` to `.bashrc` to pin the default model. ### Going further on mobile * For more comfortable typing: install [Termux:Styling](https://f-droid.org/packages/com.termux.styling/) to change the font and color scheme * For a graphical interface: the tmoe menu includes a VNC desktop, so you can run full GNOME/XFCE on the phone * For long-running background jobs: use `tmux` or `screen` so the session survives closing Termux That's the end of the tutorial. If you run into problems, feel free to report them to the [aicentos community](https://aicentos.com). ## Notes * Get the API Key from the "API Keys" page in the console. * `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_API_KEY` — **pick one, never set both**. * The Base URL should be just the root address `https://aicentos.com`; **do not** manually append `/v1/messages` — Claude Code concatenates it automatically. * After changing the configuration, remember to restart the terminal / restart Claude Code. * Never commit your API Key to a code repository. --- # Cline Source: https://docs.aicentos.com/en/clients/cline Language: en > Set aicentos as an OpenAI-compatible provider in the Cline VS Code extension with your Base URL and API Key Cline officially supports the OpenAI Compatible provider, so it can connect to this service directly. ## Installation Per the official Cline documentation: * If you use VS Code, Cursor, Windsurf or Antigravity, open the extension marketplace, search for `Cline` and install the official extension * If you use JetBrains, go to `Settings / Plugins / Marketplace`, search for `Cline`, install it and restart the IDE * If you only want the terminal version, see the official Cline CLI documentation: `https://docs.cline.bot/cline-cli/installation` ## Open the settings Click the settings button in the Cline panel to get to the provider configuration. ## Configuration to fill in Set `API Provider` to `OpenAI Compatible`, then fill in: * Base URL: `https://aicentos.com/v1` * API Key: your `codex_...` or `sk-...` key * Model ID: `gpt-5-codex-mini` If the model does not show up in the dropdown automatically, you can also type `gpt-5-codex-mini` manually. ## Test After filling it in, click `Verify` in Cline or simply start a new task. If it connects normally and the session starts, the integration is working. ## Notes * The official Cline documentation uses exactly this OpenAI Compatible provider setup * The Base URL should be the OpenAI-compatible root path * For this service, there is no need to enter the bare service root address, nor to extend the URL into the full `/chat/completions` path --- # CodeBuddy Source: https://docs.aicentos.com/en/clients/codebuddy Language: en > Connect to aicentos' OpenAI-compatible endpoint in CodeBuddy (IDE / CLI) through models.json CodeBuddy supports custom models: through a user-level or project-level `models.json` you can point requests at aicentos' OpenAI-compatible endpoint. The IDE and the CodeBuddy Code CLI share the same configuration. ## Prerequisites First create a dedicated key for CodeBuddy on the console's "API Keys" page (naming it `codebuddy` is recommended). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Wallet top-up: [https://aicentos.com/wallet](https://aicentos.com/wallet) ## Configuration to fill in | Field | Value | | ------------------------------------ | -------------------------------------------------- | | Base URL | `https://aicentos.com/v1` | | Endpoint URL (`url` field) | `https://aicentos.com/v1/chat/completions` | | API Key (`apiKey`) | The key created in the console | | Model ID (`id`) | A model name from the Model Gallery in the console | | `supportsToolCall` | `true` | | `maxInputTokens` / `maxOutputTokens` | Set according to the chosen model | Note: the `url` field in `models.json` requires the **full endpoint path** and must end with `/chat/completions`. ## Setup steps * Open CodeBuddy once so it generates the configuration directory. * Create or edit the user-level configuration file: * macOS / Linux: `~/.codebuddy/models.json` * Windows: `C:\Users\\.codebuddy\models.json` * If it should only apply to a single project, use the project-level `/.codebuddy/models.json` instead, which takes precedence over the user-level file. * Write the following, replacing `id` with a model name you have confirmed works in the console: ```json { "models": [ { "id": "gpt-5", "name": "GPT-5 (aicentos)", "vendor": "aicentos", "apiKey": "${AICENTOS_API_KEY}", "url": "https://aicentos.com/v1/chat/completions", "maxInputTokens": 128000, "maxOutputTokens": 16384, "supportsToolCall": true, "supportsImages": false, "supportsReasoning": false } ] } ``` * Set the environment variable (both `apiKey` and `url` support `${VAR_NAME}` references): ```bash export AICENTOS_API_KEY="sk-your-aicentos-key" ``` * Quit CodeBuddy completely and reopen it (restarting the IDE panel is enough). * Select the newly configured model in the model picker. If you would rather not edit files, click the model picker below the chat panel in the CodeBuddy IDE → **Configure custom model** → choose **Custom** as the provider, then fill in the Base URL `https://aicentos.com/v1`, the API Key and the model name. ## Test After saving, start a new conversation or coding task and run a lightweight test with a simple prompt first; only start real use once responses come back normally. ## Notes * Only APIs in **OpenAI interface format** are currently supported. * `url` must be written as the full `/v1/chat/completions` path; `https://aicentos.com/v1` will not work. * The outermost structure must be `{"models": [...]}`; `models` is a required top-level field. * `availableModels` is a whitelist: once set, the model dropdown only shows the listed models and built-in models disappear as well. Omit the field if you do not need the restriction. * Save the file as **UTF-8 without BOM**; JSON with a BOM breaks reading of the local model configuration. * Environment variables are resolved at startup; if a variable does not exist, `${AICENTOS_API_KEY}` in the configuration file is kept literally and calls fail. * Set `models.json` permissions to `600` and do not commit it to version control. * The CLI can also be configured with environment variables: `CODEBUDDY_API_KEY`, `CODEBUDDY_BASE_URL`, `CODEBUDDY_MODEL`. When setting `CODEBUDDY_BASE_URL` directly, do not include `/chat/completions` — the CLI appends it itself. * See the docs site for more details: [https://docs.aicentos.com](https://docs.aicentos.com) --- # Codebuff Source: https://docs.aicentos.com/en/clients/codebuff Language: en > Connect aicentos's OpenAI-compatible endpoint in the Codebuff command-line agent Codebuff is an AI coding agent that runs in the terminal and schedules multiple sub-agents per task to read code, draft plans and modify files. By default it connects to the official hosted service; if your version supports overriding the OpenAI-compatible endpoint, environment variables can point the requests at aicentos. ## First check whether your version supports a custom endpoint Codebuff officially pushes the hosted mode: sign in to use the official quota, or use the official API through `CODEBUFF_API_KEY`. Not every version offers a custom Base URL, so confirm first: * Run `codebuff --help` and look for options like `--base-url` or `--provider`. * Check whether your version reads `OPENAI_BASE_URL` (some versions use `CODEBUFF_BASE_URL`) to override the endpoint. * If neither is supported, the current version only talks to the official service and cannot connect to aicentos directly. ## Prerequisites If your version does support a custom endpoint, first create a dedicated key for Codebuff on the console's "API Keys" page (naming it `codebuff-cli` is a good idea). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) Also make sure Node.js is installed locally and Codebuff is installed globally: ```bash npm install -g codebuff ``` ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | Base URL | `https://aicentos.com/v1` | | API Key | The key created in the console | | Model | A model name from the Model Gallery in the console | ## Setup steps * Write the endpoint and key into your shell configuration (`~/.zshrc` or `~/.bashrc`): ```bash export OPENAI_API_KEY="sk-your-aicentos-key" export OPENAI_BASE_URL="https://aicentos.com/v1" ``` * Reload the configuration: `source ~/.zshrc`. * Go to your project directory and run `codebuff` directly. * If the version supports the `--model` flag, specify the model explicitly at launch; otherwise switch models with the model selection command in the interactive interface. Some versions keep the configuration in a JSON file under the user configuration directory (credential files default to `600` permissions; do not commit them to version control). If your version uses a configuration file instead of environment variables, fill in the same Base URL and key under the field names given by `codebuff --help` or the official documentation. ## Test After launching, run a lightweight test with a simple prompt first — for example, have it read a file and summarize the contents — and only start real use once results come back normally. ## Notes * Custom endpoints are an advanced use case, and field names may vary between versions; trust the `codebuff --help` output on your machine. * `OPENAI_BASE_URL` only goes up to `https://aicentos.com/v1`; do not extend it to the full `/v1/chat/completions`. * Codebuff sends code snippets and terminal output as context; confirm this complies with your team's data compliance requirements before use. * When errors occur, check in order: whether the environment variables are active in the current terminal, whether the model name matches the console, and whether the account balance is sufficient ([https://aicentos.com/wallet](https://aicentos.com/wallet)). * More details on the docs site: [https://docs.aicentos.com](https://docs.aicentos.com) --- # Codex CLI Source: https://docs.aicentos.com/en/clients/codex-cli Language: en > Use aicentos in Codex CLI — manually configure model_providers in config.toml Codex CLI is OpenAI's official command-line coding agent; model providers are defined in `~/.codex/config.toml`. Point a custom provider at aicentos and the models aicentos offers become usable in the terminal. If you prefer managing multiple configurations graphically, [CC Switch](https://docs.aicentos.com/en/clients/cc-switch) offers one-click switching; this guide covers manual configuration only. ## Prerequisites First create a dedicated key for Codex CLI on the console's "API Keys" page (naming it `codex-cli` makes usage easier to track): * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) Confirm Codex CLI is installed: ```bash codex --version ``` ## Configuration to fill in | Field | Value | | ---------------------------- | -------------------------------------------------- | | Provider ID | `aicentos` | | Provider name | `aicentos` | | API Key environment variable | `AICENTOS_API_KEY` | | Base URL | `https://aicentos.com/v1` | | Model | A model name from the Model Gallery in the console | ## Setup steps ### 1. Set the API Key environment variable ```bash export AICENTOS_API_KEY="sk-your-API-Key" ``` To persist it, add the line to `~/.zshrc` or `~/.bashrc`, `source` the file, and verify with `echo $AICENTOS_API_KEY`. ### 2. Edit config.toml Add the following to `~/.codex/config.toml`: ```toml model = "your-model-name" model_provider = "aicentos" [model_providers.aicentos] name = "aicentos" base_url = "https://aicentos.com/v1" env_key = "AICENTOS_API_KEY" wire_api = "responses" ``` Replace `your-model-name` with a model name listed in the Model Gallery of the console; see [Supported models](https://docs.aicentos.com/en/billing/models-list). ### 3. Start Codex ```bash codex ``` Send a simple request to confirm the provider works. ## Test ``` codex exec "Answer in one sentence: what is 1+1?" ``` A normal response means the integration works. The response consumes a small amount of quota, which you can check in the console's usage logs. ## Notes * **Enter the Base URL only up to `/v1`** — do not extend it to the full `/v1/chat/completions` path. * Fields such as `base_url` and `env_key` only take effect in the user-level `~/.codex/config.toml`. A `.codex/config.toml` inside the project is ignored and may trigger a startup warning. * Set `wire_api` to `responses`, which corresponds to aicentos' [Responses API](https://docs.aicentos.com/en/api/chat/openai/responses). The official documentation currently only supports this value; if your version reports `unknown variant`, the CLI is too old — upgrade first. * `openai`, `ollama` and `lmstudio` are reserved provider IDs. You **cannot** repoint the built-in `openai` provider's base\_url at a third-party gateway; you must create a new provider name (`aicentos` in this guide). * Troubleshooting order: does the model name match the console → is the Base URL only up to `/v1` → are the environment variables visible in **the terminal that launched codex** → is the account balance sufficient. ## Related links * [Connect Codex (via CC Switch)](https://docs.aicentos.com/en/clients/codex) --- # Codex++ Source: https://docs.aicentos.com/en/clients/codex-plus Language: en > Connect the aicentos GPT API to the Codex on your computer with the Codex++ enhancement launcher — pure API mode, graphical configuration, done in minutes [Codex++](https://github.com/BigPizzaV3/CodexPlusPlus) is an **external enhancement launcher and management tool** for the Codex App. It does not modify the Codex App's original installation files; instead it launches Codex through an external launcher and injects enhancement scripts via the Chromium DevTools Protocol — so you can use it with peace of mind, your original Codex stays untouched. This tutorial shows you how to connect **aicentos' GPT API** to the Codex on your computer: a few clicks in Codex++'s graphical interface, no hand-writing `config.toml`. ## Prerequisites * A computer (Windows / macOS both supported) * A [aicentos](https://aicentos.com) account, with a Key created on the [API Keys page](https://aicentos.com/keys) — include `codex` in the name to make usage easier to track When creating the Key, pay attention to its **group**: it must be in the same group as the models you fill in below, otherwise you will get a permission error. ## Step 1: Download and install Codex++ Open the official GitHub Releases page: [github.com/BigPizzaV3/CodexPlusPlus/releases](https://github.com/BigPizzaV3/CodexPlusPlus/releases) Codex++ Releases download page In the latest release, pick the installer **for your system**, download it, then install and open it. What you see after opening is the Codex++ management tool: Codex++ management tool interface ## Step 2: Add a provider Click **Add Provider** to create a new connection configuration: Add provider Fill in as follows: | Field | What to enter | | ------------------- | --------------------------------------------------------------------------------------------------------- | | Name | The relay's name — anything you can recognize (e.g. `aicentos`) | | Connection mode | **Pure API** | | Models to configure | Models supported by aicentos — **copy the full model names**, separated by commas, e.g. `gpt-5.5,gpt-5.4` | ## Step 3: Fill in the Codex target Under **Codex target**, **enable it ✅** and fill in the following two items: | Field | Value | | -------- | ---------------------------------------------------------------------- | | Base URL | `https://aicentos.com` | | Key | The Key generated in aicentos Token Management, for the matching group | Fill in the Base URL and Key For **Upstream protocol**, make sure to select **chat completions** — other protocols will make requests fail. Selecting chat completions as the upstream protocol When done, click **Save** at the top. ## Step 4: Restart Codex After saving, click **Restart** in the top-right corner for the configuration to take effect: Restart Codex ## Step 5: Sign in with the Key After the restart, choose **Sign in with another method**: Sign in with another method Paste the Key generated in [aicentos Token Management](https://aicentos.com/keys) and click **Continue**: Paste the Key and continue That completes the integration — you can start using Codex right away. ## Troubleshooting When requests fail, compare the Codex output with the usage logs in the [aicentos console](https://aicentos.com). Common causes: * **Wrong model name**: follow aicentos' [Supported models](https://docs.aicentos.com/en/billing/models-list) and copy the full model name. * **Wrong upstream protocol**: it must be **chat completions**. * **Wrong Base URL**: enter `https://aicentos.com`, with no stray spaces or extra path segments at either end. * **401 / no permission**: check that the Key was copied in full and that the Key's group includes the models you want to use; check your balance on the [Wallet](https://aicentos.com/wallet) page. --- # Codex Source: https://docs.aicentos.com/en/clients/codex Language: en > Use aicentos in Codex — one-click import with CC Switch, or configure config.toml manually Codex is compatible with the OpenAI protocol. Point the model provider at aicentos and you can use every model aicentos offers. Two integration options are provided below: **manage everything with CC Switch** (recommended), or **edit config.toml manually**. ## Option 1: Use CC Switch (recommended) CC Switch can also manage Codex's provider configuration, letting you switch between multiple setups in one click. See [Connect with CC Switch →](https://docs.aicentos.com/en/clients/cc-switch) ## Option 2: Manual configuration ### Prerequisites | Item | Value | | ---------------------------- | ------------------------- | | Provider ID | `aicentos` | | Provider name | `aicentos` | | Base URL | `https://aicentos.com/v1` | | API Key environment variable | `AICENTOS_API_KEY` | First create a dedicated key on the console's "API Keys" page; including `codex` in the name makes usage easier to track. ### Set the API Key Set the environment variable in your terminal: ```bash export AICENTOS_API_KEY="sk-your-API-Key" ``` To persist it, add the line to `~/.zshrc` or `~/.bashrc`, then reload: ```bash source ~/.zshrc ``` Confirm the variable is active: ```bash echo $AICENTOS_API_KEY ``` ### Configure the Codex provider Edit `~/.codex/config.toml` and add: ```bash model = "your-model-name" model_provider = "aicentos" [model_providers.aicentos] name = "aicentos" base_url = "https://aicentos.com/v1" env_key = "AICENTOS_API_KEY" wire_api = "responses" ``` Replace `your-model-name` with a model name listed in the Model Gallery of the console; see [Supported models](https://docs.aicentos.com/en/billing/models-list). ### Launch Codex ```bash codex ``` Send a simple request to confirm the provider works. ## Troubleshooting When a request fails, compare Codex's terminal output with the usage logs in the console. Common causes: * The model name is wrong (follow the Model Gallery). * The Base URL format is wrong (fill in only up to `/v1`; do not add extra paths). * The environment variable was not picked up by the current terminal (reopen the terminal or `source` the config file). --- # Command Code Source: https://docs.aicentos.com/en/clients/command-code Language: en > Use aicentos in Command Code — add a BYOK provider through providers.json Command Code is a terminal coding agent that uses its built-in providers by default and also supports BYOK: register a custom provider in `~/.commandcode/providers.json` and point the baseURL at aicentos. ## Prerequisites First create a dedicated key for Command Code on the console's "API Keys" page (naming it `command-code` makes usage easier to track): * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) ## Configuration to fill in | Field | Value | | ----------- | -------------------------------------------------- | | Config file | `~/.commandcode/providers.json` | | baseURL | `https://aicentos.com/v1` | | apiKey | `$AICENTOS_API_KEY` | | Model | A model name from the Model Gallery in the console | ## Setup steps ### 1. Set the environment variable ```bash export AICENTOS_API_KEY="sk-your-API-Key" ``` Add it to `~/.zshrc` or `~/.bashrc` to persist it. ### 2. Edit providers.json Edit `~/.commandcode/providers.json` and add an entry under the `provider` object: ```json { "provider": { "aicentos": { "name": "aicentos", "api": "openai-completions", "baseURL": "https://aicentos.com/v1", "apiKey": "$AICENTOS_API_KEY", "models": { "gpt-4o": {} } } } } ``` Field descriptions: | Field | Description | | --------- | ----------------------------------------------------------------------------------------- | | `name` | Display name, shown in `/connect` and `/model` | | `api` | `openai-completions` (default) or `anthropic-messages` | | `baseURL` | Required. API root address, must include `/v1` | | `apiKey` | Supports `$VAR`, `{env:VAR}`, `!command`, or set to `false` for unauthenticated endpoints | | `models` | Required; `{}` is enough, model IDs must match the endpoint | Replace the model IDs in `models` with names from the Model Gallery in the console; see [Supported models](https://docs.aicentos.com/en/billing/models-list). ### 3. Select the provider Once inside Command Code: * Run `/connect`, select `aicentos` and complete the key confirmation; * Run `/model` and choose the model to use. Note: **after modifying `providers.json`, you need to reopen `/model`** for the new configuration to load. ## Test After picking the model, send a simple prompt: ``` Answer in one sentence: what is 1+1? ``` A normal response means the integration works. You can also press `u` on the provider in `/connect` to have it call the endpoint's `/models` and refresh the model list. ## Notes * Command Code uses OpenAI-compatible Chat Completions by default, so setting `api` to `openai-completions` is enough. * To use Claude-family models, you need a separate provider entry with `api: "anthropic-messages"` — the two protocols build paths differently (the OpenAI SDK appends `/chat/completions`, the Anthropic SDK appends `/v1/messages`), so a single baseURL cannot serve both. * `baseURL` must include `/v1`; Command Code appends the remaining path itself. * Pasting a plain-text key directly into `apiKey` is rejected; use the `$VAR` form. * Troubleshooting order: can you see the model in `/model` → are the environment variables visible in the terminal you launched from → does baseURL stop at `/v1` → is the balance sufficient. ## Related links * Official BYOK documentation: [https://commandcode.ai/docs/byok](https://commandcode.ai/docs/byok) --- # GitHub Copilot Source: https://docs.aicentos.com/en/clients/copilot Language: en > Use aicentos's OpenAI-compatible endpoint in GitHub Copilot Chat through bring-your-own-key (BYOK) GitHub Copilot in VS Code offers bring-your-own-key (BYOK), which lets you point chat requests at a custom OpenAI-compatible endpoint. Set the endpoint to aicentos and fill in the key created in the console, and the models aicentos offers become available in Copilot Chat / Agent. ## Prerequisites First create a dedicated key for Copilot on the console's "API Keys" page (naming it `copilot-vscode` or `copilot-work` makes usage easier to track). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) Also make sure your local VS Code and the GitHub Copilot Chat extension are updated to a version that supports custom endpoints; older versions only offer built-in vendor BYOK with no generic "custom endpoint" entry. ## Configuration to fill in | Field | Value | | ------------ | ---------------------------------------------------------------------------- | | Provider | Custom Endpoint (OpenAI Compatible in older versions) | | Base URL | `https://aicentos.com/v1` | | API type | Chat Completions (corresponds to `https://aicentos.com/v1/chat/completions`) | | API Key | The key created in the console | | Model ID | A model name from the Model Gallery in the console | | Tool Calling | `true` (required to use Agent mode) | ## Setup steps ### Option 1: Graphical interface * Open the Chat view in VS Code. * Click the model picker above the input box and choose **Manage Language Models** (**Manage Models...** in older versions). * Click **Add Models** and pick **Custom Endpoint** (**OpenAI Compatible** in older versions) from the provider list. * Enter a group name and the API Key. * Choose **Chat Completions** as the API type. * Complete the model details as prompted: `id` is the model name from the console, `url` is `https://aicentos.com/v1/chat/completions`. * After saving, go back to Chat and select the newly added model in the model dropdown. ### Option 2: settings.json Run **Preferences: Open User Settings (JSON)** from the command palette and add: ```json { "github.copilot.chat.customOAIModels": { "aicentos-gpt": { "name": "aicentos GPT", "url": "https://aicentos.com/v1/chat/completions", "toolCalling": true, "vision": false, "maxInputTokens": 128000, "maxOutputTokens": 16384 } } } ``` The outermost key of the object (e.g. `aicentos-gpt`) is the model ID shown in the model picker and must be unique. Reference documentation: [https://code.visualstudio.com/docs/copilot/customization/language-models](https://code.visualstudio.com/docs/copilot/customization/language-models) ## Test After saving the settings, start a new conversation in Chat and send a simple prompt first; a normal response means the connection works. Then move on to Agent / Edit mode for real work. ## Notes * BYOK only applies to **Chat / Agent / Edit**; it does not cover inline code completion (Tab completion). Semantic search, embeddings and similar features still go through Copilot's own service. * To use **Agent** mode, the model must support **tool calling** and `toolCalling` must be `true`; otherwise the model will not appear in the model picker. * The `url` field must be the full `https://aicentos.com/v1/chat/completions`, not just up to `/v1`. * `github.copilot.chat.customOAIModels` is the older form; newer versions use `chatLanguageModels.json` together with `customendpoint`. Follow whatever entry point your current VS Code version actually offers. * With GitHub Copilot Business / Enterprise, administrators may disable BYOK through policy. * If a newly added model does not show up right away, restart VS Code once. * When errors occur, check in order: whether the key has extra spaces, whether the model name matches the console, whether the account balance is sufficient, and whether the API type is correct. Top up at [https://aicentos.com/wallet](https://aicentos.com/wallet) if the balance runs out. --- # Craft Agent Source: https://docs.aicentos.com/en/clients/craft-agent Language: en > Connect aicentos in Craft Agent — a custom OpenAI-compatible connection that works for both the desktop app and craft-cli Craft Agent's LLM connections support a `Custom` type, officially described as "any URL, any OpenAI-compatible or Anthropic-compatible endpoint". Point the Base URL at aicentos and both the desktop app and `craft-cli` can use it. ## Prerequisites First create a dedicated key for Craft Agent in the console (naming it `craft-agent` is recommended) so usage can be tracked per key. * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up wallet: [https://aicentos.com/wallet](https://aicentos.com/wallet) Install the desktop app: ```bash curl -fsSL https://thecraftagents.com/install-app.sh | bash ``` Headless server and pure command-line usage are supported as well. ## Configuration to fill in | Field | Value | | --------------- | --------------------------------------------------------------------------------------------- | | Connection type | Custom | | Protocol | `openai-completions`, or `anthropic-messages` | | Base URL | `https://aicentos.com/v1` (OpenAI-compatible) / `https://aicentos.com` (Anthropic-compatible) | | API Key | The key created in the console | | Model | A model name from the Model Gallery in the console | ## Setup steps Desktop app: open the LLM connections in settings, add one, choose Custom as the type, and fill it in per the table above. The command-line equivalent: ```bash export AICENTOS_API_KEY="sk-your-API-Key" craft-cli run --provider openai \ --base-url https://aicentos.com/v1 \ --api-key "$AICENTOS_API_KEY" \ --model your-model-name \ "Hello" ``` You can also edit the config file `~/.craft-agent/config.json` directly: ```json { "llmConnections": [ { "providerType": "pi_compat", "baseUrl": "https://aicentos.com/v1", "customEndpoint": { "api": "openai-completions" }, "models": [{ "id": "your-model-name" }], "defaultModel": "your-model-name" } ] } ``` The key is not written into the plaintext config; it is stored in `credentials.enc` in the same directory. Fill it in once through the UI and do not edit this file by hand. ## Test ```bash craft-cli run --provider openai \ --base-url https://aicentos.com/v1 \ --api-key "$AICENTOS_API_KEY" \ --model your-model-name \ "Introduce yourself in one sentence" ``` A normal response means it works. Then go back to the console and check usage to confirm the requests are recorded against this key. ## Notes * Keep `providerType` as `pi_compat`; that is its identifier for a custom endpoint. Changing it to the name of a built-in provider routes to the official models. * `models` must be filled in by hand; it does not fetch the model list automatically. Names must match the Model Gallery in the console exactly (see [Supported models](https://docs.aicentos.com/en/billing/models-list)). * When using the Anthropic-compatible endpoint, the Base URL is `https://aicentos.com` without `/v1`, and `--provider` becomes `anthropic`. * Menu positions in the desktop app change between versions; when you cannot find something, go by the `config.json` form. ## Related links * [Craft Agents docs](https://thecraftagents.com/docs) * [craft-agents repository](https://github.com/craft-ai-agents/craft-agents-oss) --- # Crush Source: https://docs.aicentos.com/en/clients/crush Language: en > Use aicentos in Crush — add a custom provider through crush.json Crush is a terminal coding agent from Charmbracelet, written in Go, that lets you declare any OpenAI-compatible custom provider in `crush.json`. Point base\_url at aicentos and the models aicentos offers become usable right in the TUI. ## Prerequisites First create a dedicated key for Crush on the console's "API Keys" page (naming it `crush` makes usage easier to track): * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) Confirm Crush is installed: ```bash crush --version ``` ## Configuration to fill in | Field | Value | | ----------- | -------------------------------------------------- | | Config file | `~/.config/crush/crush.json` | | type | `openai-compat` | | base\_url | `https://aicentos.com/v1` | | api\_key | `$AICENTOS_API_KEY` | | Model | A model name from the Model Gallery in the console | ## Setup steps ### 1. Set the API Key environment variable ```bash export AICENTOS_API_KEY="sk-your-API-Key" ``` To persist it, add the line to `~/.zshrc` or `~/.bashrc`, then `source` the file. ### 2. Edit crush.json The global configuration file lives at `~/.config/crush/crush.json` (`%USERPROFILE%\AppData\Local\crush\crush.json` on Windows); a `.crush.json` or `crush.json` in the project root overrides the global configuration. Write: ```json { "$schema": "https://charm.land/crush.json", "providers": { "aicentos": { "type": "openai-compat", "base_url": "https://aicentos.com/v1", "api_key": "$AICENTOS_API_KEY", "models": [ { "id": "gpt-4o", "name": "GPT-4o", "context_window": 128000, "default_max_tokens": 8192, "can_reason": true } ] } } } ``` `models[].id` must exactly match the model ID on the endpoint side — follow the Model Gallery in the console; see [Supported models](https://docs.aicentos.com/en/billing/models-list). ### 3. Select the model After starting `crush`, press `Ctrl+L` in the TUI (or type `/model`) and confirm you can see `aicentos` and its models. ## Test Do a quick check in non-interactive mode: ```bash crush run "Answer in one sentence: what is 1+1?" ``` Add `--debug` when you need request logs. If you get a 404, check that `base_url` includes `/v1`. ## Notes * **Do not set `type` to `openai`**. `openai` is for proxies that actually go through OpenAI (or Azure OpenAI); when pointing at a third-party compatible endpoint you must use `openai-compat`, otherwise you get model recognition errors or API errors. * Enter `base_url` up to `/v1`, with no trailing slash. * `api_key` supports `$VAR` and `$(command)` expansion; keep the key in an environment variable or a secrets file rather than hard-coding plain text. * For an Anthropic-protocol endpoint (`type` set to `anthropic`), `base_url` should stop at `/api` — Crush appends `/v1/messages` itself, and you additionally need to declare `anthropic-version` in `extra_headers`. * Known issue: with a custom provider, the token counter and cost statistics in the TUI may show 0; this does not affect actual requests or billing. * To enable reasoning output, use `"can_reason": true` together with `"reasoning_effort"` for OpenAI-style models, and `"think": true` for Anthropic-style models. ## Related links * Custom Provider documentation: [https://github.com/charmbracelet/crush](https://github.com/charmbracelet/crush) --- # Cursor Source: https://docs.aicentos.com/en/clients/cursor Language: en > Use aicentos in Cursor — connect through custom OpenAI-compatible settings Cursor supports a custom OpenAI-compatible API. Point the Base URL at aicentos and fill in the API Key, and the models aicentos offers become available in Chat / Composer. ## Prerequisites First create a dedicated key for Cursor on the console's "API Keys" page (naming it `cursor-desktop` or `cursor-work` makes usage easier to track). ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | API Key | The key created in the console | | Base URL | `https://aicentos.com/v1` | | Model | A model name from the Model Gallery in the console | ## Setup steps * Open Cursor's settings. * Go to the **Models** or **API Keys** area. * Find the **OpenAI API Key** / custom OpenAI-compatible settings / **Base URL** override option. * Enter the API Key you created in the aicentos console. * Set the Base URL to: `https://aicentos.com/v1` * To add models manually, enter the model names from the console (see [Supported models](https://docs.aicentos.com/en/billing/models-list)). * Save and click **Verify**, or simply start a new conversation to test. ## Test After saving, send a simple prompt first to confirm the connection works before using Composer / Chat for real. ## Notes * A custom API Key usually only applies to standard chat models. * **Tab completion** and some **Agent** capabilities may still go through Cursor's own service. * If Verify fails, check: whether the Base URL is correct (only up to `/v1`), whether the key has extra spaces, whether the model is available, whether the account balance is sufficient, and whether the custom OpenAI provider is selected. --- # Devin CLI Source: https://docs.aicentos.com/en/clients/devin-cli Language: en > Use aicentos in Devin CLI — connect through the OpenAI-compatible configuration Devin CLI is Devin's command-line client. It supports specifying an OpenAI-compatible API address through environment variables or a configuration file. Point the Base URL at aicentos and fill in the API Key, and the models aicentos offers become available in the terminal. ## Prerequisites First create a dedicated key for Devin CLI on the console's "API Keys" page (naming it `devin-cli` makes usage easier to track). ## Installation Node.js 18+ and npm are required first: ```bash node -v npm -v ``` Install globally with npm: ```bash npm install -g devin-cli ``` Verify after installing: ```bash devin --version ``` ## Setup steps Both environment variables and a configuration file are supported; environment variables take precedence. ### Option 1: Environment variables (recommended) ```bash export DEVIN_BASE_URL="https://aicentos.com/v1" export DEVIN_API_KEY="your_api_key_here" ``` To persist them, write them into `~/.zshrc` or `~/.bashrc`, then run `source ~/.zshrc`. ### Option 2: Configuration file Edit `~/.devin/config.json`: ```json { "apiKey": "your_api_key_here", "baseURL": "https://aicentos.com/v1", "model": "gpt-4o" } ``` ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | API Key | The key created in the console | | Base URL | `https://aicentos.com/v1` | | Model | A model name from the Model Gallery in the console | ## Test Once configured, run: ```bash devin ``` Send a simple prompt in the interactive session; receiving a normal reply means the integration works. On an authentication error, check whether `DEVIN_API_KEY` is correct, whether `DEVIN_BASE_URL` carries the `/v1` suffix, and whether the account balance is sufficient. ## Notes * The Base URL only goes up to `/v1`; do not extend it to the full `/v1/chat/completions` path * When both environment variables and the configuration file exist, the environment variables win * It is a good idea to confirm the visible models with `GET /v1/models` first, then fill in the Model ID --- # Devin Desktop Source: https://docs.aicentos.com/en/clients/devin-desktop Language: en > Use aicentos in Devin Desktop — connect through custom OpenAI-compatible settings Devin Desktop is Devin's desktop client and supports a custom OpenAI-compatible API address. Point the Base URL at aicentos and fill in the API Key, and the models aicentos offers become available in the client. ## Prerequisites First create a dedicated key for Devin Desktop on the console's "API Keys" page (naming it `devin-desktop` makes usage easier to track). ## Installation Download the installer for your platform from the official Devin site: * macOS: download the `.dmg` and drag it into "Applications" * Windows: download the `.exe` installer and run it * Linux: download the `.AppImage` or `.deb` and install it the way your distro expects After installing, start the app, sign in and go to the settings screen. ## Setup steps * Open **Settings**. * Go to the **Models** or **AI Provider** area. * Find the **OpenAI Compatible** / **Custom Provider** / **Base URL** override option. * Enter the API Key you created in the aicentos console. * Set the Base URL to: `https://aicentos.com/v1` * To add models manually, enter the model names from the Model Gallery in the console. * Save the settings. ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | API Key | The key created in the console | | Base URL | `https://aicentos.com/v1` | | Model | A model name from the Model Gallery in the console | ## Test After saving, start a new conversation or coding task and send a simple prompt; a normal result means the integration works. ## Notes * Settings entry names differ between versions; the key is finding the editable Base URL option * The Base URL only goes up to `/v1`; do not write the full `/v1/chat/completions` path * If the version only supports the official built-in models and the Base URL cannot be changed, it cannot connect to this gateway directly * If Verify fails, check: whether the key has extra spaces, whether the model is available, and whether the account balance is sufficient --- # Droid Source: https://docs.aicentos.com/en/clients/droid Language: en > Use aicentos in Factory Droid — register custom models through settings.json (BYOK) Droid is a command-line coding agent from Factory with BYOK support: register a custom model in `~/.factory/settings.json` and point `baseUrl` at aicentos. Droid requires a model context window of at least 64k — keep that in mind when choosing a model. ## Prerequisites First create a dedicated key for Droid on the console's "API Keys" page (naming it `droid` makes usage easier to track): * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) ## Configuration to fill in | Field | Value | | ----------- | -------------------------------------------------- | | Config file | `~/.factory/settings.json` | | provider | `generic-chat-completion-api` | | baseUrl | `https://aicentos.com/v1` | | apiKey | `${AICENTOS_API_KEY}` | | Model | A model name from the Model Gallery in the console | ## Setup steps ### 1. Set the API Key environment variable ```bash export AICENTOS_API_KEY="sk-your-API-Key" ``` Add it to `~/.zshrc` or `~/.bashrc` to persist it. ### 2. Edit settings.json Edit `~/.factory/settings.json` and add a `customModels` array: ```json { "customModels": [ { "model": "gpt-4o", "displayName": "GPT-4o (aicentos)", "baseUrl": "https://aicentos.com/v1", "apiKey": "${AICENTOS_API_KEY}", "provider": "generic-chat-completion-api", "maxOutputTokens": 8192 } ] } ``` Key fields: | Field | Description | | ------------- | --------------------------------------------------------------------------------------- | | `model` | The model ID actually sent to the endpoint; must match the Model Gallery in the console | | `displayName` | Display name in the model picker; customizable | | `baseUrl` | API address; `/v1` recommended | | `apiKey` | Supports `${VAR_NAME}` expansion | | `provider` | `anthropic` / `openai` / `generic-chat-completion-api` | ### 3. Select the model After starting `droid`, run `/model` and pick the model you just registered. **After changing the configuration, you need to restart `droid` in a new terminal** for the file to be re-read. ## Test After selecting the model, send a simple request: ``` Answer in one sentence: what is 1+1? ``` A normal response means the integration works. ## Notes * **Set `provider` to `generic-chat-completion-api`**. It uses the OpenAI Chat Completions protocol and is the right choice for most BYOK scenarios. `openai` uses the Responses API, and under some gateways that value ignores `base_url` and points straight at `api.openai.com`; `anthropic` uses `/v1/messages`. * **Clear environment variables first**. If `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL` or `ANTHROPIC_API_KEY` is exported in your shell, they override the configuration file and cause requests to bypass your configured gateway. It is advisable to `unset` these variables before connecting. * Droid reads both `~/.factory/settings.json` and the legacy `~/.factory/config.json`, with the former taking precedence. The legacy field names are snake\_case `custom_models` / `model_display_name` / `base_url` / `api_key`, and it does **not** support `${VAR_NAME}` expansion — stick to `settings.json`. * The model context window must be at least 64k; overly small local models may behave oddly. * Factory only benchmarks the official Anthropic / OpenAI endpoints, and compatibility of custom models is not guaranteed; subagents are known to occasionally fall back to the official Anthropic endpoint. * Troubleshooting order: can you see the model in `/model` → are the environment variables being overridden by ANTHROPIC\_\* → does baseUrl include `/v1` → is the balance sufficient. ## Related links * Official BYOK documentation: [https://docs.factory.ai/model-independence/byok](https://docs.factory.ai/model-independence/byok) --- # DSH Big Fat Fish Source: https://docs.aicentos.com/en/clients/dsh Language: en > Connect aicentos models inside DeepSeek Harness (DSH), raise a fish that scrolls Bilibili and Douyin, then put it in a QQ group DSH (DeepSeek Harness) is DeepSeek's open-source Agent framework. The desktop edition, DSH Desktop, packages the runtime, plugins, and sessions into one installer. "Big Fat Fish" (大肥鱼) is a community plugin for it named `dsh-bili-whale`: an AI fish that wakes on its own schedule, scrolls Bilibili, actually understands videos, keeps two diaries, and @-mentions you with the ones worth watching. This page has four parts: first point DSH at aicentos, then raise the Bilibili fish, then the Douyin edition, and finally wire it into QQ direct messages and groups with the official plugin. The plugins are maintained by the community and by Tencent respectively, and are not affiliated with Bilibili, Douyin, or DeepSeek. ## Prerequisites | Item | Requirement | Notes | | ---------------- | ----------- | --------------------------------------------------------------------------------------------------------- | | DSH Desktop | Required | Download the macOS / Windows installer from the official site; the runtime is bundled | | Node.js | 18+ | Only needed when starting DSH from the command line; the plugin toolchain is `.mjs` and needs a real node | | ffmpeg | Optional | Only used for frame extraction; without it, subtitles, danmaku, and top comments still work | | Bilibili account | One | The account the fish itself uses, to read cookies; a secondary account is recommended | | aicentos API Key | One | Create a dedicated key (named `dsh`) so usage is easy to track per project | * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up wallet: [https://aicentos.com/wallet](https://aicentos.com/wallet) ## Configuration to fill in | Field | Value | | ------------ | -------------------------------------------------- | | Provider ID | `aicentos` | | Display name | `aicentos` | | Base URL | `https://aicentos.com/v1` | | API protocol | `openai-completions` | | API Key | The key created in the console | | Model | A model name from the Model Gallery in the console | ## Setup steps ### Install DSH Desktop Open [https://www.dshdesktop.com/](https://www.dshdesktop.com/) and pick the installer for your system (Windows, macOS Apple silicon, macOS Intel), then double-click to install. On first launch, follow the guide: configure a model, create a session, and confirm it replies. ### Connect aicentos inside DSH The UI route is recommended: 1. Open **Settings → Models** and click **Add a custom provider**. 2. Fill in Provider ID, Display name, Base URL, API protocol, and API Key from the table above. 3. In **Model catalog**, click **Fetch available models** and select the models you need; if fetching fails, type the model ID manually. 4. Click **Save**, return to the chat view, and pick the model in the model selector at the top. You can also edit `~/.dsh/settings.yaml` directly: ```yaml agent-default-model: provider: aicentos model: your-model-name llm-pi-ai: providers: aicentos: api: openai-completions baseURL: https://aicentos.com/v1 apiKeyEnv: AICENTOS_API_KEY models: - id: your-model-name ``` Then export the variable and start: ```bash export AICENTOS_API_KEY="sk-your-API-Key" ``` The API Key is stored locally in `$DSH_HOME/.credentials.yaml`; the UI never shows it in plain text. ### Install the fish plugin No manual clone needed — just send one line in the DSH chat: ```bash 帮我安装这个插件，插件地址：https://github.com/Alterssss/dsh-bili-whale ``` After it finishes, refresh the DSH page and open **Settings → Raise a Fish** (养鱼) in the left sidebar. If that entry is missing, fully quit DSH and reopen it: plugins are assembled at startup, so skipping the restart is the same as not installing. ### Grant the session full permissions This is the step people miss most. Her session lives under **Workspace → Ungrouped** in the left sidebar (you cannot see it without expanding that folder). Open the session and switch permissions to **Full access** (`danger-full-access`), otherwise she cannot run commands, post comments, or write diaries after waking. ### Log in to the Bilibili account In **Settings → Raise a Fish → Bilibili login**, click **Scan to log in** and confirm with the Bilibili app on your phone. The QR code is valid for about 3 minutes; cancelling or letting it expire never replaces the existing login state. You can also paste cookies manually: log in to the account the fish uses in a browser, press F12, open **Application → Cookies → `https://www.bilibili.com`**, copy `SESSDATA`, `bili_jct`, and `buvid3`, paste them one by one, then click **Write credentials**. Do not read cookies with `document.cookie`. `SESSDATA` is HttpOnly and unreadable from scripts; doing it that way gives you an incomplete cookie and the health check will keep failing. ### Run the dependency health check Click **Dependency health check** on the settings page. It makes a real request to Bilibili to verify the login state, then checks cookies, ffmpeg, Node, the data directory, and the schedule item by item. It passes only when everything is green ("All available ✓"). If it reports ffmpeg missing, do not go hunting for a tutorial — send "install ffmpeg on this computer" in the DSH chat and let it handle the installation, then run the check again. Always click **Save** after editing. Inputs are staged locally and only written to disk when you save; the page itself warns that unsaved changes have not taken effect. Saving applies immediately — only replacing plugin code or version requires restarting DSH. ### Set the persona and schedule * **Who she is**: character name, how she addresses you, how she refers to herself. * **Her persona**: the body is written to `~/.bili-ai/persona.md`; click **Inject persona** when done (limit 20000 characters, only the first 3000 are injected, attached on every wake and listen). * **You (owner)**: fill in your `mid`; both @-mentions and direct messages use it. * **Share method**: @-mention you in comments, or Bilibili direct message. * **Schedule window**: defaults to 20:00–24:00; she wakes at a random moment inside the window, never on the hour. The plugin ships no built-in personality — the default is a neutral assistant that does not call you "master" and does not act cute. To make her "Big Fat Fish", spell out her identity and origin, speaking style, what she cares about, and what she must not do. ## Test Run the self-test on the command line first; it checks configuration, credentials, login state, data directory, and dependencies in one pass: ```bash node ~/.dsh/plugins/dsh-bili-whale/tools/bili.mjs selftest ``` On Windows, replace the path with `%USERPROFILE%\.dsh\plugins\dsh-bili-whale\tools\bili.mjs`: ```powershell node "$env:USERPROFILE\.dsh\plugins\dsh-bili-whale\tools\bili.mjs" selftest ``` Every item ticked and a final "全部通过 ✓ 可以用了" means you are ready. Common commands: ```bash node ~/.dsh/plugins/dsh-bili-whale/tools/bili.mjs deps # dependency health check node ~/.dsh/plugins/dsh-bili-whale/tools/bili.mjs dm --status # DM quota + mutual follow status node ~/.dsh/plugins/dsh-bili-whale/tools/bili.mjs traffic status # request protection values ``` To watch her run a round right away, set the schedule window on the settings page to a two-minute slot starting now, save, and wait for her to wake (health check → pick topics → understand → write both diaries → push to you). You can also ask her in the chat to wake up and scroll Bilibili once. Finally, open the usage page in the aicentos console and confirm the requests are recorded against the key you created for DSH. ## Connect Douyin The Douyin edition is a separate project with the same idea: `dsh-douyin-scroll`. It never looks at the picture — it reads captions, tags, author, duration, engagement counts, and top comments, picks a few videos a day, and writes a Markdown report. ### Install ```bash git clone https://github.com/NEWJO123/dsh-douyin-scroll.git cd dsh-douyin-scroll node selfcheck.mjs ``` Once the pre-check passes, install it into the `web` profile and restart DSH once: ```bash dsh plugin --profile web add "link:$PWD" ``` After the restart, open **Settings → Scroll Douyin** (刷抖音). ### First-time configuration 1. Click **Install main dependencies**: it creates a dedicated venv and installs `curl_cffi` and `httpx` (about 30 seconds; progress goes to `install.log`). 2. Log in: run `node tools/qr-login.mjs start` and scan, or paste the cookies of an already logged-in Douyin browser session into the settings page. 3. Set what to scroll: keywords, categories, specific authors, videos per day, candidates per round, then click **Run one round now**. Cookies stay on this machine at `$DSH_HOME/douyin-duty/douyin_cookie.txt`, never enter logs, and are never uploaded. ### Capabilities and limits | Item | Detail | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | | What it judges by | Captions, tags, author, duration, engagement ratios, top comments; no frames, no speech recognition | | Candidate source | Read-only recommendation feed plus the hot list; Douyin's web has no usable search API, so keywords only annotate the report | | Report | Written to `out/.md`; optional Windows notification or webhook | | Sending | DMs, share cards, and comments are off by default and each requires `confirm` | | Group chat | The author's observation is that messages "may not send in groups"; another account may behave differently | Plain-text URLs are not clickable inside Douyin — only share cards are. DMs, cards, and comments need Chrome installed (it looks for `chrome.exe` only, not Edge); fetching candidates and writing reports do not. Frequent commenting triggers rate limiting, and accuracy is lower than the Bilibili edition: without subtitles it can only read how the audience reacted. ## Connect a QQ group QQ Bot ships an official plugin, `@tencent-connect/dsh-qqbot`, installed into a dedicated `qqbot` profile. Bind it by scanning a QR code and it can talk in QQ direct messages and groups. ```bash npx @deepseek-ai/dsh plugin --profile qqbot add @tencent-connect/dsh-qqbot npx @deepseek-ai/dsh --profile qqbot ``` On first launch, scan the QR code as prompted; no manual key configuration is needed. After binding: * **Isolated sessions**: every direct message and every group has its own context, with no cross-talk, and sessions recover after a restart. * **Switch models in chat**: switch directly in the conversation and the existing context is kept, so you do not start over. * **Quiet mode**: set it to respond only when @-mentioned, so it does not flood the group. The model is configured inside the `qqbot` profile: open **Settings → Models → Add a custom provider** there and fill in aicentos using the table above. If you want to manage several IM channels in one place, look at the community bundle `dsh-im`, which covers ten channels in one bundle with multi-bot and streaming replies. Conversations in the group are read into the context and sent to the model, so do not let it handle accounts or keys in a group; binding credentials live in the local profile, so never sync that profile directory to a public repository. ## Desktop pet and comment cleanup Two optional plugins, separate projects from the fish: | Purpose | Project | How to install | | -------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | An animated fish on your desktop | [https://github.com/QCYTSN/dsh-dafeiyu](https://github.com/QCYTSN/dsh-dafeiyu) | Send the URL to DSH and let it install; a transparent native window appears, draggable, animating per task state | | Hide suspected AI accounts in comments | [https://github.com/liyupi/dafeiyu-cleaner](https://github.com/liyupi/dafeiyu-cleaner) | Browser extension: download the zip from Releases, unzip, open `chrome://extensions`, enable developer mode, load the unpacked extension | The cleaner only hides comments in your own browser — it deletes nothing, never auto-reports, and misjudged accounts can be restored. Its offline rule set detects roughly 85% of accounts, a figure measured in one comment section and not guaranteed to hold elsewhere. ## Notes * **Leave auto-commenting off at first.** It is disabled by default; once enabled it posts one comment per round, up to 20, and only once per video. Even so, public flooding becomes a "fish plague" for everyone else. Start with Bilibili direct messages to yourself. * **The DM channel needs two accounts.** Choosing Bilibili direct message requires two distinct accounts that follow each other (`relation.attribute === 6`). With a single account, watching videos, writing diaries, and generating reports still work; DMs do not. * **Authorize with a secondary account.** The plugin speaks with your own account, so do not hand your main account's cookies to a third-party plugin, and never buy accounts of unknown origin. * **Stop on rate limiting.** On 412 / 429, captchas, or throttling, the plugin pauses for 5–30 minutes and reports; do not retry in a loop, and signed endpoints are no guarantee against platform limits. * **Pick a cheap model.** She screens 5 videos, deep-reads 2–3, and writes two diaries every day, which means many requests per round. Choose a low-cost model with enough context in aicentos (see [supported models](https://docs.aicentos.com/en/billing/models-list)) and create a dedicated key for DSH to track cost. * **Headless mode does not work.** The plugin must run on a DSH instance with the web UI, otherwise it stays at `pending (waiting for services: sessionController, webServer, connection)`. * The plugin is the public release of a personal tool and is not affiliated with Bilibili or DeepSeek; you act with your own account and at your own risk, so follow the platform's community rules. ## Related links * [dsh-bili-whale plugin repository](https://github.com/Alterssss/dsh-bili-whale) * [dsh-douyin-scroll plugin repository](https://github.com/NEWJO123/dsh-douyin-scroll) * [QQ Bot official docs](https://bot.qq.com/wiki/agent-qqbot/) * [DSH Desktop official site](https://www.dshdesktop.com/) * [DSH Desktop source](https://github.com/dataelement/dsh-desktop) * [Plugin changelog](https://github.com/Alterssss/dsh-bili-whale/blob/main/CHANGELOG.md) * [Models supported by aicentos](https://docs.aicentos.com/en/billing/models-list) --- # Freebuff Source: https://docs.aicentos.com/en/clients/freebuff Language: en > Freebuff needs no API Key and has no custom endpoint configuration — the reason and the alternatives Freebuff's selling point is "no subscription, no credits, no API Key": models come from a built-in catalog and the cost is borne by its own account system. So it **has no Base URL or key configuration**, and cannot be connected to aicentos. ## Why it cannot connect directly The official README states plainly `No subscription, credits, or API key required`, and the configuration has no fields such as `baseUrl` or `apiKey`. Its desktop edition can host an already-installed Claude Code or Codex and reuse those tools' own provider accounts — but there it is the **hosted CLI** that decides the model, not Freebuff's own model configuration. To take that route to aicentos, configure it inside the hosted CLI (see [Claude Code](https://docs.aicentos.com/en/clients/claude-code) and [Codex CLI](https://docs.aicentos.com/en/clients/codex-cli)). ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | API Key | The key created in the console | | Base URL | `https://aicentos.com/v1` | | Model | A model name from the Model Gallery in the console | The table above lists the generic aicentos-side parameters, for use with the alternatives below. ## Alternatives * Want a terminal coding agent: [Craft Agent](https://docs.aicentos.com/en/clients/craft-agent), [Gajae Code](https://docs.aicentos.com/en/clients/gajae-code), [Oh My Pi](https://docs.aicentos.com/en/clients/oh-my-pi). * Want free credit to test the water first: use the trial credit in the console, and once you are sure the models fit, move to a client that supports custom endpoints. * Only want its desktop shell to host another CLI: configure aicentos on the Claude Code / Codex CLI side. ## Test After switching to any of the alternative clients, send one prompt to confirm connectivity, then check usage back in the console. ## Notes * "Free" means the model is not selectable and the provider cannot be changed, so do not go looking for settings on the assumption that it is configurable. * The official notes mention that some restricted regions, or turning on a VPN, get rate limited. ## Related links * [Freebuff CLI](https://freebuff.com/cli) * [freebuff repository](https://github.com/CodebuffAI/freebuff) --- # Fx Source: https://docs.aicentos.com/en/clients/fx Language: en > Use aicentos in Fx — add a custom model connection through the user-level settings.json Fx is a coding agent from Vercel Labs, written in Zig as a single native binary and model-agnostic. Custom model connections are defined in the user-level `~/.fx/settings.json`; point the base URL at aicentos. **One pitfall to call out first:** `.fx.json` in the project root is a different thing. It deliberately disallows most fields (including models) so that a cloned repository cannot swap out your model or endpoint. **Custom endpoints must be written in `~/.fx/settings.json`** — putting them in `.fx.json` has no effect. ## Prerequisites First create a dedicated key for Fx on the console's "API Keys" page (naming it `fx` makes usage easier to track): * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) Confirm Fx is installed: ```bash curl -fsSL https://fx.sh/setup.sh | bash fx --version ``` ## Configuration to fill in | Field | Value | | ----------- | -------------------------------------------------- | | Config file | `~/.fx/settings.json` | | Base URL | `https://aicentos.com/v1` | | API Key | The key created in the console | | Model | A model name from the Model Gallery in the console | ## Setup steps ### 1. Edit the user-level settings In `~/.fx/settings.json`, register a connection following the "custom model connection" format. The field structure of the connection object is defined by the official documentation: * Documentation: [https://fx.sh/docs](https://fx.sh/docs) * README: [https://github.com/vercel-labs/fx](https://github.com/vercel-labs/fx) Set the API address of the connection to: ``` https://aicentos.com/v1 ``` For the API Key, use the one you created in the console; take model names from the Model Gallery in the console. ### 2. Point Fx at the connection Fx lets you specify the provider and model at launch: ```bash fx provider local FX_MODEL=gpt-4o fx ask "Answer in one sentence: what is 1+1?" ``` Or specify it with an environment variable: ```bash export FX_MODEL="gpt-4o" ``` ### 3. Confirm the current provider Fx remembers your choice per provider; the next launch reuses the previous provider. ## Test First verify connectivity with a side-effect-free prompt: ```bash fx ask "Answer in one sentence: what is 1+1?" ``` A normal response means the integration works. On authentication errors, first check whether the base URL includes `/v1` and whether the API Key has stray spaces. ## Notes * **Do not touch `.fx.json`**. The project-level file only allows a few fields such as `provider_order` and `provider_strict`, has no `model` field, and is not used to configure custom endpoints. * `provider_order` / `provider_strict` are Vercel AI Gateway routing parameters; **they only apply to Gateway requests — custom model connections ignore them**. Do not expect them to switch the upstream. * Official support for custom model connections in Fx is still evolving; older versions may need a newer build to recognize them. After upgrading, run the test command above once before real use. * The binary install script downloads from the network; verify that you trust the source before running it. ## Related links * Project home: [https://github.com/vercel-labs/fx](https://github.com/vercel-labs/fx) --- # Gajae Code Source: https://docs.aicentos.com/en/clients/gajae-code Language: en > Connect aicentos in Gajae Code (gjc) — add an OpenAI-compatible provider in models.yml Gajae Code defines providers in `~/.gjc/agent/models.yml`, with the fields `baseUrl` / `api` / `apiKey`; one added block points it at aicentos. ## Prerequisites First create a dedicated key for Gajae Code in the console (naming it `gajae-code` is recommended), then install the CLI: ```bash curl -fsSL https://raw.githubusercontent.com/Yeachan-Heo/gajae-code/v0.15.3/scripts/install.sh -o gjc-install.sh sh gjc-install.sh gjc --version ``` ## Configuration to fill in | Field | Value | | ----------------------- | ------------------------------------------------------ | | provider name | Your choice, for example `aicentos` | | `baseUrl` | `https://aicentos.com/v1` | | `api` | `openai-completions` | | `apiKey` or `apiKeyEnv` | The key itself, or the name of an environment variable | | `models[].id` | A model name from the Model Gallery in the console | ## Setup steps Edit `~/.gjc/agent/models.yml`: ```yaml providers: aicentos: baseUrl: https://aicentos.com/v1 api: openai-completions apiKeyEnv: AICENTOS_API_KEY discovery: type: openai-models-list models: - id: your-model-name contextWindow: 128000 maxTokens: 8192 ``` Point the default model at it: ```yaml modelBindings: modelRoles: default: aicentos/your-model-name:high ``` Then export the key and start: ```bash export AICENTOS_API_KEY="sk-your-API-Key" gjc ``` The `discovery` block makes it fetch the model list automatically; if you want to control the visible models by hand, drop that block and keep only `models`. ## Test Start `gjc` and confirm the models under `aicentos` appear in the model picker, then send one prompt to confirm it returns. If the list is empty, check the indentation of `models.yml` and the `discovery` block first. ## Notes * `models.yml` is strictly validated, and an unknown field is an immediate error. Do not copy underscore spellings such as `api_key` or `base_url` from other tools; this one requires camelCase `baseUrl` and `apiKey`. * Fill `contextWindow` and `maxTokens` according to the actual model; values that are too large are rejected upstream. * In `modelRoles.default`, `:high` is the reasoning-effort suffix; change it to another level or drop it as needed. * The project describes itself as experimental, so fields may change after an upgrade; go by `docs/models.md` in the repository. ## Related links * [gajae-code repository](https://github.com/Yeachan-Heo/gajae-code) --- # Gemini CLI Source: https://docs.aicentos.com/en/clients/gemini-cli Language: en > Use aicentos in Gemini CLI — configure a custom gateway through environment variables Gemini CLI is an official command-line tool from Google that supports configuring a custom gateway through environment variables to connect to the Codex Proxy service, letting you chat with Gemini models in the terminal. ## Prerequisites Gemini CLI is installed globally via npm, so you need Node.js 18+ and npm ready first. ### Install Node.js * Visit the official Node.js download page: [https://nodejs.org/en/download](https://nodejs.org/en/download) * macOS/Windows: download and install the LTS version * Linux: install using the distro instructions on that page * macOS (Homebrew users): run `brew install node` ### Verify the installation ```bash node -v npm -v ``` ## Install Gemini CLI Install Gemini CLI globally with npm: ```bash npm install -g @google/gemini-cli ``` Verify the installation: ```bash gemini --version ``` ## Configure environment variables Gemini CLI supports connecting to a custom gateway through the following three environment variables: | Environment variable | Description | | ------------------------ | ----------------------------------------------------------------------- | | `GOOGLE_GEMINI_BASE_URL` | Root address of the gateway service; replaces Google's default endpoint | | `GEMINI_API_KEY` | Your API Key | | `GEMINI_MODEL` | The default model to use | ### Example configuration ```bash export GOOGLE_GEMINI_BASE_URL="https://aicentos.com" export GEMINI_API_KEY="your_api_key_here" export GEMINI_MODEL="gemini-2.0-flash" ``` ### Notes * `GOOGLE_GEMINI_BASE_URL` takes the service root address; no specific API path is needed * Quick tests: run the export commands above directly in the current shell session * To persist: add the export statements to `~/.zshrc` or `~/.bashrc`, then run `source ~/.zshrc` to apply them ## Launch Gemini CLI Once configured, start it by running: ```bash gemini ``` After launching, you can chat with Gemini models right in the terminal. ## Verify the connection Start a conversation in Gemini CLI; if replies come back normally, the integration is working. ### Troubleshooting * For authentication errors, confirm that `GEMINI_API_KEY` is correct * Check that `GOOGLE_GEMINI_BASE_URL` points to the correct service address ## Notes * The service already supports the Gemini-compatible interface and works with Gemini CLI directly * Add the environment variables to a shell configuration file so they persist * Gemini CLI appends the API path automatically; there is no need to add a specific API path to the BASE\_URL ## Related links * Official documentation: [https://docs.aicentos.com/clients/gemini-cli.html](https://docs.aicentos.com/clients/gemini-cli.html) --- # Goose Source: https://docs.aicentos.com/en/clients/goose Language: en > Use aicentos in Goose — declare a custom OpenAI-compatible provider Goose is Block's open-source coding agent. It supports two ways to point at an OpenAI-compatible endpoint: reuse the built-in `openai` provider and change the host, or declare a standalone custom provider. The latter is recommended — the endpoint details stay in one place, and it is easier to keep several configurations side by side. ## Prerequisites First create a dedicated key for Goose on the console's "API Keys" page (naming it `goose` makes usage easier to track): * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) ## Configuration to fill in | Field | Value | | -------------------- | -------------------------------------------------- | | Custom provider file | `~/.config/goose/custom_providers/aicentos.json` | | engine | `openai` | | base\_url | `https://aicentos.com/v1/chat/completions` | | api\_key\_env | `AICENTOS_API_KEY` | | Model | A model name from the Model Gallery in the console | ## Setup steps ### 1. Set the API Key environment variable ```bash export AICENTOS_API_KEY="sk-your-API-Key" ``` Add it to `~/.zshrc` or `~/.bashrc` to persist it. **Do not put the key into config.yaml** — the official guidance is to use environment variables or the system keychain. ### 2. Declare the custom provider Create `~/.config/goose/custom_providers/aicentos.json` (`%APPDATA%\Block\goose\config\custom_providers\` on Windows): ```json { "name": "aicentos", "engine": "openai", "display_name": "aicentos", "description": "Models available through aicentos", "api_key_env": "AICENTOS_API_KEY", "base_url": "https://aicentos.com/v1/chat/completions", "models": [ { "name": "gpt-4o", "context_limit": 128000 } ], "supports_streaming": true, "dynamic_models": true } ``` The required fields are `name`, `engine`, `display_name`, `base_url` and `models`; `engine` takes `openai` / `anthropic` / `ollama`. Model names follow the Model Gallery in the console; see [Supported models](https://docs.aicentos.com/en/billing/models-list). ### 3. Set it as the default in config.yaml Edit `~/.config/goose/config.yaml`: ```yaml GOOSE_PROVIDER: aicentos GOOSE_MODEL: gpt-4o ``` At startup Goose scans the `custom_providers/` directory and registers them automatically; you can also switch providers in the graphical interface afterwards. ## Test Verify with a non-interactive session first: ```bash goose run -t "Answer in one sentence: what is 1+1?" ``` A normal response means the integration works. ## Notes * **`base_url` must be the full path** (including `/v1/chat/completions` here), unlike how most clients do it. If you need to specify the path explicitly, newer versions also support a `base_path` field, which takes precedence over URL parsing. * **Environment variables take precedence over config.yaml**. If `OPENAI_HOST` is already exported in your shell, it silently overrides the file configuration; run `env | grep -i openai` first when troubleshooting. * Goose only starts properly once a provider is selected. If you wrote the configuration in `config.yaml` but never ran `goose configure`, you may see `No provider configured` — a common misconception, since the configuration itself is YAML format, not `.env`. * With `dynamic_models: true`, Goose calls the endpoint's `/v1/models` to fetch the model list; if you only want to expose specific models, remove the field or set it to `false`. * A simpler alternative is to reuse the built-in provider: set `GOOSE_PROVIDER: openai` in config.yaml and assemble the endpoint with `OPENAI_HOST` plus `OPENAI_BASE_PATH`. This is less work, but couples you more tightly to environment variables and runs into the override problem above. * Troubleshooting order: does the provider name match the JSON file name exactly → does `base_url` include the full path → are the environment variables visible → is the balance sufficient. ## Related links * Custom Provider documentation: [https://block.github.io/goose/docs/api/providers/custom](https://block.github.io/goose/docs/api/providers/custom) --- # Grok Build Source: https://docs.aicentos.com/en/clients/grok-build Language: en > Use aicentos in Grok Build — define a custom model provider through config.toml Grok Build is xAI's terminal coding agent. It calls the official xAI endpoint by default, but it supports declaring arbitrary OpenAI-compatible `[model.*]` endpoints in `~/.grok/config.toml`. Point the endpoint at aicentos and the same key can call the grok family as well as models from other vendors. ## Prerequisites * Install Grok Build (official script): ```bash curl -fsSL https://x.ai/cli/install.sh | bash ``` * Create a dedicated key in the aicentos console (naming it `grok-build` is a good idea). ## Configuration to fill in | Field | Value | | --------------- | ------------------------------------------------------------------------------------ | | base\_url | `https://aicentos.com/v1` | | api\_backend | `chat_completions` (default) | | env\_key | `AICENTOS_API_KEY` | | model | A model ID from the Model Gallery in the console, e.g. `grok-4.7`, `claude-opus-4-8` | | context\_window | Match the chosen model, e.g. `200000` | ## Setup steps * Write the key into your shell environment (add it to `~/.zshrc` or `~/.bashrc`, then `source` the file to apply it): ```bash export AICENTOS_API_KEY="your_api_key_here" ``` * Edit `~/.grok/config.toml` and add a custom model: ```toml [models] default = "aicentos-grok" [model.aicentos-grok] base_url = "https://aicentos.com/v1" env_key = "AICENTOS_API_KEY" api_backend = "chat_completions" context_window = 200000 max_completion_tokens = 8192 description = "aicentos gateway - grok-4.7" ``` The `` in `[model.]` is the model ID. To add more models, for example `grok-4.7` and `claude-opus-4-8`, write a separate `[model.grok-4.7]` and `[model.claude-opus-4-8]` block for each. * Start Grok Build and switch with the model picker or a command: ```bash grok /model aicentos-grok ``` ## Test First list the models to see whether yours is recognized: ```bash grok models ``` Then send a lightweight prompt (e.g. `grok -p "Introduce the current directory in one sentence" -m aicentos-grok`) and confirm it returns normally. ## Notes * Grok Build has **no `--base-url` command-line flag**; a custom endpoint can only be specified through the configuration file or environment variables. * `api_backend` defaults to `chat_completions`; if you explicitly write `responses` or `messages`, make sure the gateway supports the corresponding endpoint, otherwise requests fail. * Credentials are resolved in this order: the `api_key` in the model configuration → the environment variable named by `env_key` → the logged-in session token → the global `XAI_API_KEY`. Using `env_key` with your own variable name keeps things separate from the official xAI account. * If a newly added model omits `context_window`, Grok Build assumes 200,000 by default; setting it explicitly for the chosen model is recommended. * Once a custom endpoint is configured, the xAI subscription is no longer needed, but the selected model is still billed on the aicentos side — check the balance on the [wallet page](https://aicentos.com/wallet) first. --- # Grok CLI Source: https://docs.aicentos.com/en/clients/grok-cli Language: en > Use aicentos in Grok CLI — connect through environment variables or a configuration file Grok CLI is a command-line tool that uses the OpenAI-compatible interface, so a custom API address can be plugged in directly as its backend service. ## Prerequisites You need Node.js 18+ and npm installed first. The recommended source is the official Node.js download page: [https://nodejs.org/en/download](https://nodejs.org/en/download) * macOS/Windows: download and install the LTS version * Linux: install using the distro instructions macOS users can also use Homebrew: ```bash brew install node ``` After the installation, confirm: ```bash node -v npm -v ``` ## Install Grok CLI Install globally with npm: ```bash npm install -g @vibe-kit/grok-cli ``` After the installation, verify: ```bash grok --version ``` ## Configure the connection Grok CLI offers three configuration methods with the following precedence: command-line arguments > environment variables > configuration file. ### Method 1: Environment variables (recommended) Set the following environment variables: ```bash export GROK_BASE_URL="https://aicentos.com/v1" export GROK_API_KEY="your_api_key_here" ``` For a quick test, running the exports in the current shell is enough. To persist them, add the lines above to `~/.zshrc` or `~/.bashrc`, then run `source ~/.zshrc` to apply. ### Method 2: Configuration file Edit `~/.grok/user-settings.json`: ```json { "apiKey": "your_api_key_here", "baseURL": "https://aicentos.com/v1", "defaultModel": "gpt-4o" } ``` ### Method 3: Command-line arguments Specify it through arguments at launch: ```bash grok --base-url https://aicentos.com/v1 ``` ## Launch and use Once configured, simply run: ```bash grok ``` Start a conversation in Grok CLI; if replies come back normally, the integration is working. ## Verification and troubleshooting If you hit authentication errors, check: * Whether `GROK_API_KEY` is correct * Whether `GROK_BASE_URL` / `baseURL` points to the correct service address (the `/v1` suffix is required) After confirming the configuration is correct, just restart. ## Notes * Grok CLI uses the OpenAI-compatible interface, so configuration is simple and direct * The three configuration methods can be chosen freely; the environment variable method is recommended * The API address must include the `/v1` suffix * A custom default model is supported ## Related links * Official documentation: [https://docs.aicentos.com/clients/grok-cli.html](https://docs.aicentos.com/clients/grok-cli.html) --- # Hermes Agent Source: https://docs.aicentos.com/en/clients/hermes-agent Language: en > Use aicentos in Hermes Agent — point at an OpenAI-compatible endpoint through environment variables Hermes Agent reads model service connection details from environment variables. Point the Base URL at aicentos and all of the agent's inference requests go through the models aicentos offers. ## Prerequisites First create a dedicated key for Hermes Agent on the console's "API Keys" page (naming it `hermes-agent` makes usage easier to track). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Wallet top-up: [https://aicentos.com/wallet](https://aicentos.com/wallet) * Docs site: [https://docs.aicentos.com](https://docs.aicentos.com) ## Configuration to fill in | Field | Value | | ----------------- | -------------------------------------------------- | | OPENAI\_BASE\_URL | `https://aicentos.com/v1` | | OPENAI\_API\_KEY | The key created in the console | | Model | A model name from the Model Gallery in the console | ## Setup steps Set the variables in the same shell that runs the agent: ```bash export OPENAI_BASE_URL="https://aicentos.com/v1" export OPENAI_API_KEY="sk-your-Key" export OPENAI_MODEL="gpt-4o" ``` Then start Hermes Agent the way you normally do. To persist the settings, put the `export` lines above into `~/.zshrc` or `~/.bashrc` and `source` the file again. If Hermes Agent has its own configuration file, you can also specify base\_url / api\_key / model there with the same effect; when both exist, its own precedence rules apply (environment variables usually win). ## Test After starting, trigger the simplest possible inference (for example, ask it a general-knowledge question) and confirm a reply comes back. Then check the console's usage page to confirm the request was actually recorded against the key you created for Hermes Agent. ## Notes * The environment variables must be visible in the shell session that launches the agent; writing them into a different shell has no effect. * If you deploy with Docker, pass the variables in with `-e` or compose's `environment` — defining them only on the host is not enough. * Enter the Base URL only up to `/v1`. * Some agent frameworks read `OPENAI_API_BASE` first; if the variables above have no effect, add the alternate spelling and try again. * Create a separate key for the agent so its usage can be tracked per project. --- # Hindsight Source: https://docs.aicentos.com/en/clients/hindsight Language: en > Give the Hindsight memory service an aicentos model — four environment variables and an OpenAI-compatible endpoint Hindsight is an open-source agent memory system offering a self-hosted service, HTTP / MCP interfaces, an SDK, and a CLI. It is not a chat client itself, but **memory distillation needs an LLM**, and that LLM can point at aicentos. ## Prerequisites First create a dedicated key for Hindsight in the console (naming it `hindsight` is recommended). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up wallet: [https://aicentos.com/wallet](https://aicentos.com/wallet) The Hindsight server requires PostgreSQL 14 or later. The bundled `pg0` is only suitable for development; in production, connect your own instance. ```bash pip install hindsight-api ``` ## Configuration to fill in | Environment variable | Value | | ---------------------------- | -------------------------------------------------- | | `HINDSIGHT_API_LLM_PROVIDER` | `openai` | | `HINDSIGHT_API_LLM_BASE_URL` | `https://aicentos.com/v1` | | `HINDSIGHT_API_LLM_API_KEY` | The key created in the console | | `HINDSIGHT_API_LLM_MODEL` | A model name from the Model Gallery in the console | ## Setup steps Just put them into the startup environment; no code changes are needed: ```bash export HINDSIGHT_API_LLM_PROVIDER="openai" export HINDSIGHT_API_LLM_BASE_URL="https://aicentos.com/v1" export HINDSIGHT_API_LLM_API_KEY="sk-your-API-Key" export HINDSIGHT_API_LLM_MODEL="your-model-name" hindsight-api ``` When deploying with Docker, put these variables into the compose `environment`. Note that the official image does not include `llama.cpp`, so do not expect to run local models inside the container. ## Test ```bash curl -fsSL https://hindsight.vectorize.io/get-cli | bash hindsight health ``` Once the service is up, write one memory and retrieve it again; if that works end to end, LLM calls are working. You can also watch usage in the console directly: every memory Hindsight distills produces one request. ## Notes * `BASE_URL` must end with `/v1`, and the upstream must be able to serve `/chat/completions`; writing `https://aicentos.com` returns 404. * With no LLM key configured the service refuses to start; that is its hard validation, not a wrong key. * Memory distillation is background batch work, so usage grows with the number of memories; give Hindsight its own key so it is easier to watch. * Setting `HINDSIGHT_API_LLM_PROVIDER` to `openai` means the OpenAI-compatible protocol, not that only OpenAI models can be used. ## Related links * [Hindsight model configuration](https://hindsight.vectorize.io/developer/models) * [hindsight repository](https://github.com/vectorize-io/hindsight) --- # Jcode Source: https://docs.aicentos.com/en/clients/jcode Language: en > Use aicentos in Jcode — specify an OpenAI-compatible endpoint through the configuration file Jcode can point at an OpenAI-compatible API service through a configuration file. Set the Base URL to aicentos and fill in the API Key, and the models aicentos offers become available in Jcode. ## Prerequisites First create a dedicated key for Jcode on the console's "API Keys" page (naming it `jcode` makes usage easier to track). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) * Docs site: [https://docs.aicentos.com](https://docs.aicentos.com) ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | Provider | OpenAI Compatible | | Base URL | `https://aicentos.com/v1` | | API Key | The key created in the console | | Model | A model name from the Model Gallery in the console | ## Setup steps * Open Jcode's configuration file (usually under the user configuration directory, e.g. `~/.jcode/config.json`). * Add an OpenAI-compatible provider entry. * Set `baseURL` / `baseUrl` to: `https://aicentos.com/v1` * Set `apiKey` to the key created in the console. * Set `model` to a model name from the Model Gallery in the console (see [Supported models](https://docs.aicentos.com/en/billing/models-list)). * Save and restart Jcode for the configuration to take effect. Reference structure: ```json { "provider": "openai", "baseUrl": "https://aicentos.com/v1", "apiKey": "sk-your-key", "model": "gpt-4o" } ``` If your version keeps the configuration at `~/.config/jcode/config.json`, edit the file with the same name at that path instead. ## Test After restarting, start a new session and send a simple prompt; a normal response means the integration works. ## Notes * Field naming (`baseUrl` / `base_url`) may differ between versions; follow the field names in your local configuration template. * The Base URL only goes up to `/v1`; do not extend it to the full API path. * If your Jcode version offers no custom Base URL entry, that version cannot connect to third-party endpoints; switch to another client that supports a custom Base URL. * Never commit the key to version control; reference it through an environment variable if necessary. --- # Junie Source: https://docs.aicentos.com/en/clients/junie Language: en > Use aicentos in Junie CLI through a custom model profile Junie is JetBrains' coding agent, available as an IDE plugin and as the Junie CLI. **Only the Junie CLI supports pointing at a custom endpoint**: it connects to any OpenAI-compatible service through JSON profiles under `$JUNIE_HOME/models/`. The IDE plugin cannot currently target a custom endpoint. ## Prerequisites First create a dedicated key for Junie on the console's "API Keys" page (naming it `junie-cli` is a good idea). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) ## Configuration to fill in | Field | Value | | ------------------------------ | ----------------------------------------------------------------- | | `baseUrl` | `https://aicentos.com/v1/chat/completions` | | `apiType` | `OpenAICompletion` | | `apiKey` | The key created in the console (supports `${ENV_VAR}` references) | | `id` | A model name from the Model Gallery in the console | | `displayName` / `providerName` | Custom, e.g. `aicentos` | Note: Junie's profile is the opposite of most clients — `baseUrl` must be the **full endpoint** and must end with `/chat/completions`; Junie does not append the path for you. ## Setup steps * Create the profile file (the file name without `.json` is the profile identifier): * User level: `~/.junie/models/aicentos.json` (`$JUNIE_HOME` defaults to `~/.junie`) * Project level: `/.junie/models/aicentos.json` (the project must be trusted) * Write the following content: ```json { "id": "gpt-5", "baseUrl": "https://aicentos.com/v1/chat/completions", "apiType": "OpenAICompletion", "apiKey": "${AICENTOS_API_KEY}", "displayName": "aicentos GPT", "providerName": "aicentos", "fasterModel": { "id": "gpt-5-mini" } } ``` * Export the environment variable: ```bash export AICENTOS_API_KEY="sk-your-aicentos-key" ``` * Specify the profile at launch, or select it with `/model` in the interactive interface: ```bash junie --model custom:aicentos ``` ## Test After launching, send a simple prompt as a lightweight test; once results come back normally, move on to real agentic workflows. ## Notes * **The JetBrains IDE plugin does not support custom endpoints**; these profiles only take effect in the Junie CLI. * `baseUrl` must be the full endpoint (including `/v1/chat/completions`), unlike many clients that only need the Base URL. * `${VAR}` in `apiKey` and `extraHeaders` is resolved when the profile loads; an unset environment variable makes profile loading fail. * Project-level profiles are subject to project trust; untrusted projects report `Unknown custom model profile`. * Small models struggle with Junie's multi-step tool calling and long-context tasks; pick a capable model. * More details on the docs site: [https://docs.aicentos.com](https://docs.aicentos.com) --- # Kilo CLI Source: https://docs.aicentos.com/en/clients/kilo-cli Language: en > Connect aicentos in the Kilo command-line tool through a configuration file Kilo CLI declares providers and models in a JSON / JSONC configuration file and supports pointing `@ai-sdk/openai-compatible` at any OpenAI-compatible endpoint, so it can connect to aicentos directly. ## Prerequisites First create a dedicated key for the CLI on the console's "API Keys" page (naming it `kilo-cli` is recommended). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Wallet top-up: [https://aicentos.com/wallet](https://aicentos.com/wallet) Also confirm Kilo CLI is installed globally: ```bash npm install -g @kilocode/cli ``` ## Configuration to fill in | Field | Value | | ----------------------------------- | ----------------------------------------------------------------- | | Provider package (`npm`) | `@ai-sdk/openai-compatible` | | `options.baseURL` | `https://aicentos.com/v1` | | `options.apiKey` | The key created in the console (can be referenced as `{env:VAR}`) | | Model reference (top-level `model`) | In `provider/model` form, e.g. `aicentos/gpt-5` | | `limit.context` / `limit.output` | Fill in according to the chosen model | ## Setup steps * Create or edit the global configuration file: * `~/.config/kilo/kilo.json` (or `kilo.jsonc`); if `XDG_CONFIG_HOME` is set, that directory takes precedence. * A project-level `./kilo.jsonc` overrides entries of the same name in the global configuration. * Write the following: ```json { "$schema": "https://app.kilo.ai/config.json", "model": "aicentos/gpt-5", "provider": { "aicentos": { "npm": "@ai-sdk/openai-compatible", "name": "aicentos", "options": { "baseURL": "https://aicentos.com/v1", "apiKey": "{env:AICENTOS_API_KEY}" }, "models": { "gpt-5": { "name": "GPT-5", "limit": { "context": 128000, "output": 16384 } } } } } } ``` * Export the environment variable: ```bash export AICENTOS_API_KEY="sk-your-aicentos-key" ``` * Run `kilo` in the project directory, or switch models with `/model` in the interactive interface. ## Test After starting, try a lightweight test with a simple prompt first, and only start real work once results come back normally. ## Notes * `options.baseURL` should only go up to `https://aicentos.com/v1`; do not extend it to the full `/v1/chat/completions` path. * The `{env:VAR}` environment variable substitution syntax **only works in the global configuration file**; for security reasons, a project-level `kilo.jsonc` does not resolve `{env:...}`. * Custom models must declare `limit.context` and `limit.output` explicitly; otherwise the context length is treated as 0 and auto-compaction stops working. * If the gateway does not provide a `/v1/models` listing endpoint, automatic model discovery fails — declare the models manually as shown above. * See the docs site for more details: [https://docs.aicentos.com](https://docs.aicentos.com) --- # Kilo Code Source: https://docs.aicentos.com/en/clients/kilo-code Language: en > Add a Custom Provider in the Kilo Code extension using the aicentos Base URL and API Key Kilo Code officially supports the OpenAI Compatible provider, so it can connect to this service directly. ## Installation Official installation page: [https://marketplace.visualstudio.com/items?itemName=kilocode.kilo-code](https://marketplace.visualstudio.com/items?itemName=kilocode.kilo-code) If you use VS Code, the most direct way to install is: ```bash code --install-extension kilocode.kilo-code ``` If you use Windsurf, VSCodium or another Open VSX-compatible environment, install the corresponding marketplace version per the official Kilo documentation. ## Open the settings Click the settings button in the Kilo Code panel to get to the provider configuration. ## Configuration to fill in Set the API Provider to OpenAI Compatible, then fill in: * Base URL: [https://aicentos.com/v1](https://aicentos.com/v1) * API Key: your codex\_... or sk-... key * Model ID: gpt-5-codex-mini If the model list does not show it automatically, you can also type it in manually. ## Test After saving, start a new task and confirm Kilo Code connects normally and returns content. ## Notes * The official Kilo Code documentation uses the OpenAI Compatible provider configuration * Kilo Code also supports entering a full endpoint URL, but that is unnecessary for this service * Use the Base URL here; do not extend it into the full /chat/completions path * Reference documentation: [https://kilo.ai/docs/ai-providers/openai-compatible](https://kilo.ai/docs/ai-providers/openai-compatible) --- # Kilo Source: https://docs.aicentos.com/en/clients/kilo Language: en > Use aicentos in Kilo through a custom OpenAI-compatible provider Kilo supports custom providers, so chat and agent requests can be pointed at any OpenAI-compatible endpoint. Just add a Custom Provider in the settings and fill in aicentos's Base URL and key. ## Prerequisites First create a dedicated key for Kilo on the console's "API Keys" page (naming it `kilo` is a good idea). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) ## Configuration to fill in | Field | Value | | ------------------ | -------------------------------------------------- | | Provider ID / name | Custom, e.g. `aicentos` | | API type | OpenAI Compatible (Chat Completions) | | Base URL | `https://aicentos.com/v1` | | API Key | The key created in the console | | Model ID | A model name from the Model Gallery in the console | | Context Window | Match the chosen model | | Max Output Tokens | Match the chosen model | ## Setup steps * Open Kilo's settings panel (gear icon). * Go to **Providers**, scroll to the very bottom of the list and choose **Custom provider**. * Fill in the Provider ID and Display name freely, e.g. `aicentos`. * Choose **OpenAI Compatible (Chat Completions)** as the API type. * Enter `https://aicentos.com/v1` as the Base URL. * Enter the API Key created in the console. * Add the Model ID manually, using the model name from the console. * After saving, select a model under this provider in the model picker. ## Test After saving the settings, start a new task and send a simple prompt as a lightweight test; once content comes back normally, move on to real Agent-mode work. ## Notes * If the gateway does not offer a `/v1/models` listing endpoint, automatic model detection fails; just fill in the Model ID manually. * The Base URL only goes up to `https://aicentos.com/v1`; do not extend it to the full `/v1/chat/completions`. * Set Context Window and Max Output Tokens explicitly for custom models; leaving them out makes the context length treated as 0, which breaks auto-compaction and lets conversations grow without bound. * Official documentation: [https://kilo.ai/docs/ai-providers/openai-compatible](https://kilo.ai/docs/ai-providers/openai-compatible) * More details on the docs site: [https://docs.aicentos.com](https://docs.aicentos.com) --- # Kimchi Source: https://docs.aicentos.com/en/clients/kimchi Language: en > Connect aicentos in Kimchi — change the inference address with llmEndpoint, plus a note on the limits Kimchi is a terminal coding agent that also ships a VS Code extension and the Studio desktop app. Its configuration has an `llmEndpoint` field that defaults to `https://llm.kimchi.dev`; change it and inference requests go somewhere else. One caveat up front: **the official docs describe `llmEndpoint` only as the inference address and do not promise that it can point at any third-party OpenAI-compatible gateway**. The approach below works in the community, but it is a case of configuring by field semantics, not an officially supported BYOK path, and it may break after an upgrade. ## Prerequisites First create a dedicated key for Kimchi in the console (naming it `kimchi` is recommended), then install the CLI: ```bash brew install getkimchi/tap/kimchi ``` Or use the install script: ```bash curl -fsSL https://github.com/getkimchi/kimchi/releases/latest/download/install.sh | bash ``` ## Configuration to fill in | Field | Value | | ------------- | -------------------------------------------------- | | `llmEndpoint` | `https://aicentos.com/v1` | | `apiKey` | The key created in the console | | Model | A model name from the Model Gallery in the console | ## Setup steps The config file is at `~/.config/kimchi/config.json`, and a project-level `.kimchi/config.json` can also override it: ```json { "apiKey": "sk-your-API-Key", "llmEndpoint": "https://aicentos.com/v1" } ``` Custom models are registered in `models.json`, in the same format as self-hosted providers such as vLLM and LM Studio. The field spec is not fully public, so it is best to get the default model working first and only then consider adding custom entries. Restart `kimchi` after the change. ## Test After starting, send one prompt in the session. If you get a 401, first check that the key has no stray spaces; if you get a 404, check whether `llmEndpoint` stops at `/v1`. Then check usage in the console — **this is the key step**: if usage does not grow, the requests are not going through `llmEndpoint` at all and are falling back to the default endpoint, in which case this route does not hold for the current version. ## Notes * Kimchi requires signing in to its own account; the `apiKey` and the account sign-in state are two separate things, so do not do only half of it. * External models are treated as the `standard` tier with `vision: false` by default, so multimodal models do not carry images here. * The default model is picked automatically by its own harness, so you may not be able to name a specific aicentos model directly. * The official docs do not cover this route, so it works but is not guaranteed; have a fallback ready for production. ## Related links * [Kimchi CLI docs](https://docs.kimchi.dev/docs/kimchi-cli) * [kimchi repository](https://github.com/getkimchi/kimchi) --- # Kimi Source: https://docs.aicentos.com/en/clients/kimi Language: en > Use aicentos in Kimi Code CLI — register an OpenAI-compatible provider through config.toml Kimi Code CLI lets you register any OpenAI-compatible service as a provider. Point `base_url` at aicentos and fill in the API Key, and the models aicentos offers become callable straight from the terminal interface. ## Prerequisites First create a dedicated key for Kimi Code on the console's "API Keys" page (naming it `kimi-cli` makes usage easier to track). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) * Docs site: [https://docs.aicentos.com](https://docs.aicentos.com) The configuration file lives at `~/.kimi/config.toml` by default and is created automatically the first time Kimi Code runs. ## Configuration to fill in | Field | Value | | ------------- | -------------------------------------------------- | | provider type | `openai_legacy` (Chat Completions protocol) | | base\_url | `https://aicentos.com/v1` | | api\_key | The key created in the console | | model | A model name from the Model Gallery in the console | If the aicentos side uses the Responses protocol, switch the type to `openai_responses`. ## Setup steps Open `~/.kimi/config.toml` and append a custom provider plus a model alias: ```toml default_model = "aicentos-gpt-4o" [providers.aicentos] type = "openai_legacy" base_url = "https://aicentos.com/v1" api_key = "sk-your-key" [models.aicentos-gpt-4o] provider = "aicentos" model = "gpt-4o" max_context_size = 128000 ``` * The provider name (`aicentos`) and the model alias (`aicentos-gpt-4o`) are both customizable; `default_model` refers to the alias, not the server-side model ID. * If the alias contains a `.` (e.g. `gpt-4.1`), it must be quoted in TOML: `[models."gpt-4.1"]`, otherwise the `.` is parsed as a table separator. * If you would rather not hand-write TOML, type `/provider` in the TUI to open the provider manager, press Enter on the `[ Add New Platform ]` line and follow the wizard. Environment variables alone also work (for the `openai_legacy` / `openai_responses` types): ```bash export OPENAI_BASE_URL="https://aicentos.com/v1" export OPENAI_API_KEY="sk-your-key" ``` ## Test Start `kimi` and send a simple prompt in the TUI; a normal response means the integration works. Use `/model` to confirm the alias you just configured is selected. ## Notes * Provider credentials are resolved in the order: the `api_key` field > the `[providers..env]` sub-table > a startup error. Except for `openai_legacy` / `openai_responses`, credentials in the configuration file are not auto-filled from shell environment variables. * `type = "kimi"` is for Moonshot's official endpoint; use `openai_legacy` or `openai_responses` for aicentos. * Do not set `max_context_size` below the model's actual window; a value that is too small triggers context compaction early. * The Base URL only goes up to `/v1`; do not extend it to the full `/v1/chat/completions` path. * Model names follow the Model Gallery in the console (see [Supported models](https://docs.aicentos.com/en/billing/models-list)). --- # Kiro Source: https://docs.aicentos.com/en/clients/kiro Language: en > Kiro does not currently support a custom Base URL — why, and the workable alternatives **Kiro does not currently support a custom Base URL and cannot connect to aicentos directly.** Kiro is an agentic IDE from AWS (built on Code OSS). Its models all go through the bundled service backed by Amazon Bedrock. There is no official entry point for "custom model endpoints" or "bring your own API Key (BYOK)", and the community feature requests for this remain unimplemented. ## Prerequisites There is no need to create an aicentos API Key for Kiro — the current version has nowhere to enter a custom key. Reference information: * Console: [https://aicentos.com](https://aicentos.com) * Docs site: [https://docs.aicentos.com](https://docs.aicentos.com) If you have already connected other clients, first confirm whether that client supports custom endpoints. ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | Base URL | No such setting exists | | API Key | No such setting exists | | Model | Can only be chosen from Kiro's built-in model list | ## Setup steps Not possible. Kiro's settings only offer model switching (the `/model` command or the model picker) and a `model` field for custom Agents, and `model` only matches the available model IDs returned by Kiro's service — it cannot point at an external endpoint. ## Alternatives Kiro does not support custom endpoints, so the following options are available: * **Use a client that natively supports a custom Base URL**: for example Cursor, Windsurf, Cline, Roo Code, Zed Agent and others can all take `https://aicentos.com/v1` directly. See the other documents under "Client Integrations". * **Stay on Kiro's built-in models**: Kiro's built-in models are provided by AWS and are unrelated to aicentos; billing cannot be combined. * **Wait for official BYOM / BYOK support**: you can follow the feature requests in Kiro's official repository, but nothing has landed yet. * **Corporate intranet gateway scenarios**: even with an internal LLM proxy deployed, Kiro cannot be pointed at it — this too requires official support. Modifying hosts files, installing self-signed certificates, or patching the IDE are unofficial workarounds and are not recommended — they break Kiro's update mechanism and carry security and compliance risks. ## Test There is no custom endpoint to test. To verify aicentos connectivity, use any client that supports a custom Base URL, or call the API directly: ```bash curl https://aicentos.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -d '{"model":"gpt-5","messages":[{"role":"user","content":"hi"}],"stream":false}' ``` ## Notes * To reiterate: **the current version of Kiro does not support a custom Base URL and cannot connect to aicentos**. * This document will be updated as Kiro's official capabilities change. * Official documentation: [https://kiro.dev/docs](https://kiro.dev/docs) --- # LM Studio Source: https://docs.aicentos.com/en/clients/lm-studio Language: en > LM Studio is a local inference server rather than a client — its correct role and what to do instead LM Studio is often mistaken for yet another chat client, but the direction is the other way round: it is a **local model runner** that exposes an OpenAI-compatible endpoint (by default `http://localhost:1234/v1`) for others to connect to. It has no place to enter a remote Base URL, so it cannot be connected to aicentos as a client. ## Why it cannot connect directly * Its official positioning is `Serve local models on OpenAI-like endpoints`: a server role, not a consumer. * Neither the desktop app nor the `lms` CLI has an endpoint setting for third-party providers. * Its cloud features (LM Studio Secure Cloud, LM Link) are officially hosted compute channels and do not accept custom third-party endpoints. ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | API Key | The key created in the console | | Base URL | `https://aicentos.com/v1` | | Model | A model name from the Model Gallery in the console | The table above lists the generic aicentos-side parameters, for use with the alternatives below. ## Alternatives ### Alternative 1: Use it the other way round — let clients connect to LM Studio If you want to run local models, keep LM Studio as the server and set the Base URL in [Cherry Studio](https://docs.aicentos.com/en/clients/cherry-studio), [Chatbox](https://docs.aicentos.com/en/clients/chatbox), and [Cline](https://docs.aicentos.com/en/clients/cline) to `http://localhost:1234/v1`. This path has nothing to do with aicentos, but it is the correct way to use LM Studio. ### Alternative 2: Want aicentos models? Change the front end [Cherry Studio](https://docs.aicentos.com/en/clients/cherry-studio), [Chatbox](https://docs.aicentos.com/en/clients/chatbox), and [LobeChat](https://docs.aicentos.com/en/clients/lobechat) are all desktop chat clients that support several providers side by side: one entry for aicentos, one for the local LM Studio, switched in the same interface. ### Alternative 3: Mix local and cloud With a client such as Cherry Studio, mount both providers at once: send simple tasks to the local one and complex tasks to aicentos, switching as needed. ## Test When LM Studio is the server, first run `lms server start`, then use `curl http://localhost:1234/v1/models` to confirm the endpoint is alive, and then send one prompt in the client. ## Notes * Do not look for a Base URL input box in LM Studio; it only shows the address it listens on. * Local model context and speed are limited by the machine's VRAM; for long-context tasks, prefer aicentos. * Do not confuse the two directions: **the server fills in a port, the client fills in an endpoint**. ## Related links * [LM Studio OpenAI-compatible API](https://lmstudio.ai/docs/api/openai-api) * [lms CLI](https://github.com/lmstudio-ai/lms) --- # LobeChat Source: https://docs.aicentos.com/en/clients/lobechat Language: en > Use aicentos in LobeChat — connect through custom OpenAI-compatible settings LobeChat is an open-source AI chat platform that supports the OpenAI-compatible interface, so it can connect to this service straight from the settings panel. ## Open the settings Click the **Settings** icon in the lower-left corner and go to the **Language Model** page. ## Select the OpenAI provider Click **OpenAI** in the provider list to expand its configuration panel. ## Configuration to fill in Fill in the following in the configuration panel: * **API Key (apiKey)**: your `codex_...` or `sk-...` key * **API proxy address (baseURL)**: `https://aicentos.com/v1` ## Select a model and verify Pick `gpt-5-codex-mini` from the model dropdown, or type it manually. Start a conversation and confirm it returns normally. ## Notes * The API proxy address should be the service root path including `/v1`, i.e. `https://aicentos.com/v1` * LobeChat supports configuring multiple providers at once and switching per conversation * Self-hosted deployments can be configured through the `OPENAI_API_KEY` and `OPENAI_PROXY_URL` environment variables; see the official environment variable documentation ## Related links * Official documentation: [https://lobehub.com/docs/usage/providers/openai](https://lobehub.com/docs/usage/providers/openai) --- # MiMo Code Source: https://docs.aicentos.com/en/clients/mimo-code Language: en > Use aicentos in MiMo Code — reach an OpenAI-compatible endpoint through its compatibility layer MiMo Code supports specifying an OpenAI-compatible `base_url` in its configuration. Point it at aicentos and fill in the API Key, and MiMo Code runs on the models aicentos offers. ## Prerequisites First create a dedicated key for MiMo Code on the console's "API Keys" page (naming it `mimo-code` makes usage easier to track). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Wallet top-up: [https://aicentos.com/wallet](https://aicentos.com/wallet) * Docs site: [https://docs.aicentos.com](https://docs.aicentos.com) MiMo Code is a CLI tool, most commonly installed globally with npm; if the release package you got is a tarball, extract it and put the executable on your `PATH`. ```bash npm install -g mimo-code mimo --version ``` ## Configuration to fill in | Field | Value | | --------- | -------------------------------------------------- | | API Key | The key created in the console | | base\_url | `https://aicentos.com/v1` | | model | A model name from the Model Gallery in the console | ## Setup steps Environment variables are recommended for the best compatibility: ```bash export MIMO_BASE_URL="https://aicentos.com/v1" export MIMO_API_KEY="sk-your-Key" export AICENTOS_API_KEY="$MIMO_API_KEY" export MIMO_MODEL="gpt-4o" ``` To persist them, write the exports into `~/.zshrc` or `~/.bashrc`, then run `source ~/.zshrc`. If you prefer a configuration file, edit `~/.mimo/config.json`: ```json { "baseUrl": "https://aicentos.com/v1", "apiKey": "sk-your-Key", "model": "gpt-4o" } ``` Note that different versions may name the configuration keys differently (`base_url` / `baseUrl`) and use different environment variable prefixes (`MIMO_` / `MIMOCODE_`). If the variable names above have no effect, check `mimo --help` or the official documentation for the names your version actually reads instead of trial and error. ## Test After configuring, run `mimo` directly and send a simple prompt. On an authentication error, check first whether the environment variable names are recognized by your version, whether `base_url` stops at `/v1`, and whether the key has stray spaces. ## Notes * Some versions validate `base_url` against the built-in official endpoint at startup; if you notice the configuration being ignored, switching to environment variables usually works around it. * Enter the Base URL only up to `/v1`. * Before filling in a model name, verify it is visible with `curl https://aicentos.com/v1/models -H "Authorization: Bearer $AICENTOS_API_KEY"`. * When environment variables and the configuration file are both present, precedence differs across versions — keep only one configuration method. --- # MiniMax Code Source: https://docs.aicentos.com/en/clients/minimax-code Language: en > Connect aicentos in MiniMax Code (mcode) — add an OpenAI-compatible provider with provider add MiniMax Code is MiniMax's official coding CLI (command `mcode`), with a built-in TUI, headless execution, ACP, and a TypeScript SDK. It supports BYOK: `mcode provider add` can attach any OpenAI-compatible endpoint. ## Prerequisites First create a dedicated key for MiniMax Code in the console (naming it `minimax-code` is recommended), then install: ```bash curl -fsSL https://filecdn.minimax.chat/public/install.sh | bash ``` npm works too: ```bash npm install -g @minimax-ai/code@latest mcode --version ``` ## Configuration to fill in | Field | Value | | --------------- | -------------------------------------------------- | | provider name | Your choice, for example `aicentos` | | `--base-url` | `https://aicentos.com/v1` | | `--api-format` | `openai-completions` | | `--model` | A model name from the Model Gallery in the console | | `--api-key-env` | `MCODE_PROVIDER_API_KEY` | ## Setup steps One command registers the provider and switches over to it: ```bash export MCODE_PROVIDER_API_KEY="sk-your-API-Key" mcode provider add \ --name aicentos \ --base-url https://aicentos.com/v1 \ --api-format openai-completions \ --model your-model-name \ --api-key-env MCODE_PROVIDER_API_KEY \ --use ``` `--use` means switch to this provider right after registering it. It writes the configuration into the `custom_provider` section of the current profile's `config.yaml` (the default data directory is `~/.minimax`); the equivalent form: ```yaml custom_provider: aicentos: options: apiKey: sk-your-API-Key baseURL: https://aicentos.com/v1 models: your-model-name: {} ``` Note that the key here is `baseURL` (capital URL), not `base-url`. ## Test ```bash mcode exec "Introduce yourself in one sentence" ``` A response from headless means the configuration is in effect. Then run one real task in the TUI, and finally check usage back in the console. ## Notes * Custom models need the context and output limits given explicitly (`--context-limit`, `--output-limit`); otherwise it trims by the default values and long files are easily truncated. * The one-line install script does not support Alpine / musl; use npm in such environments. * When relaying through the Anthropic-compatible protocol, requests still carry `x-api-key`; if the upstream only accepts `Authorization`, you need to add a translation layer yourself. * Providers are stored **per profile**, so after switching profiles, re-confirm which one is in effect. ## Related links * [MiniMax Code quick start](https://agent.minimax.io/docs/cli/quick-start) * [minimax-code repository](https://github.com/MiniMax-AI/minimax-code) --- # Mux Source: https://docs.aicentos.com/en/clients/mux Language: en > Use aicentos in Mux — add a custom OpenAI-compatible provider Mux supports adding custom OpenAI-compatible providers. Point the Base URL at aicentos and the models aicentos offers become usable in Mux sessions. ## Prerequisites First create a dedicated key for Mux on the console's "API Keys" page (naming it `mux` makes usage easier to track). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Wallet top-up: [https://aicentos.com/wallet](https://aicentos.com/wallet) * Docs site: [https://docs.aicentos.com](https://docs.aicentos.com) ## Configuration to fill in | Field | Value | | ------------- | -------------------------------------------------- | | Provider type | OpenAI Compatible | | Base URL | `https://aicentos.com/v1` | | API Key | The key created in the console | | Model | A model name from the Model Gallery in the console | ## Setup steps * Open Mux's settings and go to the Providers / Models area. * Choose to add a custom provider, with the type set to **OpenAI Compatible**. * Enter the API Key. * For Base URL enter: `https://aicentos.com/v1` * For Model enter a model name from the Model Gallery in the console (see [Supported models](https://docs.aicentos.com/en/billing/models-list)). * Save it and set it as the provider for the current session. ## Test Start a new session and send a simple prompt. A normal response means the integration works. If the model list does not show the model you entered automatically, type the Model ID manually and try again. ## Notes * Enter the Base URL only up to `/v1`; do not extend it to the full `/v1/chat/completions` path. * Setting names may differ slightly between versions, but the OpenAI-compatible configuration always revolves around three fields: Base URL, API Key and Model. * A wrong Base URL, a key with stray spaces, or an insufficient balance usually shows up as 401 / 403 / 402 errors — check them one by one. * If your Mux version only offers a fixed set of company options and cannot take a custom Base URL, that version does not support third-party endpoints; switch to another client that supports a custom Base URL. --- # NativeTavern Source: https://docs.aicentos.com/en/clients/nativetavern Language: en > Connect NativeTavern to the aicentos OpenAI-compatible API with your Base URL and API Key # NativeTavern NativeTavern is the mobile native app version of SillyTavern for iOS and Android. It can connect to a custom API through an OpenAI-compatible interface. ## Install the app Download and install NativeTavern from the app store for your platform: * iOS: App Store * Android: Google Play ## Configure the API connection 1. Open the NativeTavern app 2. Go to **Settings** 3. Select **API Configuration** 4. Set the API type to **OpenAI** or **OpenAI Compatible** ## Configuration to fill in On the configuration page, fill in: * **API URL**: `https://aicentos.com/v1` * **API Key**: your API Key (e.g. `codex_...` or `sk-...`) * **Model**: select or enter a model ID (e.g. `gpt-6-astra`) ## Test the connection 1. Save the settings and return to the main screen 2. Create or select a character 3. Send a message to test whether the connection works ## Notes * The mobile app may require a stable network connection * The API URL only needs to go up to `/v1`; the full path is not required * Most SillyTavern features are supported ## Related links NativeTavern is part of the SillyTavern ecosystem; see the SillyTavern community for more information. --- # NextChat Source: https://docs.aicentos.com/en/clients/nextchat Language: en > Use aicentos in NextChat — connect through custom OpenAI-compatible settings NextChat is a widely used open-source ChatGPT web client that supports a custom OpenAI-compatible interface. ## UI configuration - Open the settings Click the **Settings** icon in the lower-left corner ## UI configuration - Enable the custom interface Find the **Custom interface** toggle in the settings panel; input boxes appear once it is on ## UI configuration - Fill in the connection details Fill in the following: | Field | Value | | -------------- | -------------------------------- | | OpenAI API Key | Your `codex_...` or `sk-...` key | | API proxy URL | `https://aicentos.com/v1` | ## UI configuration - Verify After saving, start a conversation and check that it returns normally ## Self-hosted deployment configuration For self-hosted instances, configure through environment variables: ```bash OPENAI_API_KEY=codex_your_api_key BASE_URL=https://aicentos.com/v1 ``` Restart the service after configuring for it to take effect. ## Custom models In the **Model** dropdown of the settings panel, you can type `gpt-5-codex-mini` or another available model name manually. Self-hosted deployments can also preset the model list through the `CUSTOM_MODELS` environment variable, for example: ```bash CUSTOM_MODELS=gpt-5-codex-mini ``` ## Notes * The API proxy URL should be the service root path including `/v1`, i.e. `https://aicentos.com/v1` * Available models are determined by the list returned by `GET /v1/models` ## Related links * GitHub: [https://github.com/ChatGPTNextWeb/NextChat](https://github.com/ChatGPTNextWeb/NextChat) --- # Oh My Pi Source: https://docs.aicentos.com/en/clients/oh-my-pi Language: en > Connect aicentos in Oh My Pi (omp) — add an openai-completions provider in models.yml Oh My Pi is a fork of Pi with the core rewritten in Rust, and its command is `omp`. It defines providers in `~/.omp/agent/models.yml`; with `baseUrl` / `api` / `apiKey` filled in clearly, it points at aicentos. ## Prerequisites First create a dedicated key for Oh My Pi in the console (naming it `oh-my-pi` is recommended). At runtime it needs bun 1.4.4 or later: ```bash curl -fsSL https://omp.sh/install | sh ``` Homebrew and npm distributions are also available: ```bash brew install can1357/tap/omp # or bun install -g @oh-my-pi/pi-coding-agent ``` ## Configuration to fill in | Field | Value | | ------------- | -------------------------------------------------- | | provider name | Your choice, for example `aicentos` | | `baseUrl` | `https://aicentos.com/v1` | | `api` | `openai-completions` | | `apiKey` | The key created in the console | | `models[].id` | A model name from the Model Gallery in the console | ## Setup steps Edit `~/.omp/agent/models.yml`: ```yaml providers: aicentos: baseUrl: https://aicentos.com/v1 api: openai-completions apiKey: sk-your-API-Key models: - id: your-model-name contextWindow: 128000 ``` Set it as the default in `~/.omp/agent/config.yml`: ```yaml modelRoles: default: aicentos/your-model-name ``` If you do not want the key in the file, replace `apiKey` with an environment variable reference and `export AICENTOS_API_KEY="sk-your-API-Key"` before starting. ## Test ```bash omp models aicentos ``` Being able to list the model you just configured means the provider is recognized. Then go into the TUI, send one line to confirm it returns, and finally check usage back in the console. ## Notes * `api` must be `openai-completions` (or another protocol name it knows); writing `openai` is treated as an unknown protocol. * It disables a large number of tools by default; when the connection succeeds but it can do nothing, check the tool switches first — this is not an endpoint problem. * Opening a repository loads project-level configuration and hooks, so confirm the repository is trustworthy before connecting. * Alpine environments need `libstdc++` and `libgcc` installed separately. ## Related links * [Oh My Pi provider docs](https://omp.sh/docs/providers) * [oh-my-pi repository](https://github.com/can1357/oh-my-pi) --- # OpenClaw Source: https://docs.aicentos.com/en/clients/openclaw Language: en > Use aicentos in OpenClaw — connect through a custom Provider OpenClaw is an AI coding assistant CLI that supports connecting to OpenAI-compatible API services through custom Providers. The official recommendation is to complete the configuration with the `openclaw onboard` wizard, but you can also write the configuration file by hand. ## Prerequisites Make sure your system meets the following requirements: * Node.js 22 or later * macOS / Linux / Windows * pnpm, if building from source ### Install Node.js **macOS (Homebrew):** ```bash brew install node ``` **Other systems:** Download the LTS version from the Node.js website: [https://nodejs.org/en/download](https://nodejs.org/en/download) ### Verify the installation ```bash node -v npm -v ``` **Note:** Windows users are advised to run OpenClaw inside WSL2. ## Install OpenClaw Use the official install script (recommended): ### macOS / Linux ```bash curl -fsSL https://openclaw.ai/install.sh | bash ``` ### Windows PowerShell ```powershell iwr -useb https://openclaw.ai/install.ps1 | iex ``` The install script automatically detects and installs missing dependencies. If you already manage your own Node environment, you can also install with `npm` or `pnpm` (see the official documentation for details). ## Run the onboarding wizard Run the wizard command: ```bash openclaw onboard ``` Fill in the following in the wizard: * **Provider type**: choose `Custom Provider` * **Compatibility**: choose `OpenAI-compatible` * **Base URL**: `https://aicentos.com/v1` * **API Key**: your API Key * **Model ID**: a model name from the Model Gallery in the console * **Endpoint ID**: `aicentos` is recommended **Note:** just enter the API Key in plain text — there is no need to convert it to the `OPENAI_API_KEY` environment variable. ## Set the default model After the wizard completes, set the default model to: ```text aicentos/gpt-4o ``` Subsequent usage will then automatically use the configured model. ## Manual configuration (optional) If you skip the wizard, you can write OpenClaw's provider configuration file directly: ```json { "models": { "providers": { "aicentos": { "baseUrl": "https://aicentos.com/v1", "apiKey": "your_api_key_here", "api": "openai-completions", "models": [ { "id": "gpt-4o", "name": "gpt-4o" } ] } } }, "agents": { "defaults": { "model": { "primary": "aicentos/gpt-4o" } } } } ``` The configuration accepts the API Key in plain text, or an environment variable reference if you prefer the SecretRef approach. ## Verify the configuration Check the model status to confirm the connection works: ```bash openclaw models list openclaw models status ``` If you can see `aicentos/gpt-4o` with a healthy status, the integration is configured successfully. ## Notes * OpenClaw officially supports custom Providers, with a choice of OpenAI-compatible or Anthropic-compatible modes * For this service, prefer the OpenAI-compatible mode * Entering the API Key directly is the default approach; environment variable references are just an alternative * If you want a tool to write the configuration for you, consider `cc-switch` * The official documentation covers other installation and configuration options — choose whatever fits your needs ## Related links * Official documentation: [https://docs.openclaw.ai/install/index](https://docs.openclaw.ai/install/index) --- # OpenCode Source: https://docs.aicentos.com/en/clients/opencode Language: en > Use aicentos in OpenCode — connect a custom provider through a configuration file OpenCode supports custom providers, so you can connect to the Codex Proxy service through a configuration file. ## Prerequisites The OpenCode website provides an official install script, along with npm, bun, brew and other installation methods. * If you use the official install script directly, you usually do not need to set up npm beforehand * If you plan to install via npm, install Node.js and npm first * If you plan to install via bun, install bun first ### Install Node.js (npm route) The official Node.js download page is: [https://nodejs.org/en/download](https://nodejs.org/en/download) * macOS / Windows: download and install the LTS version * Linux: install using the distro instructions on that page If you already have Homebrew on macOS, you can simply run: ```bash brew install node ``` This installs both Node.js and npm. After installing with your chosen method, confirm the corresponding commands work. For the npm route, check: ```bash node -v npm -v ``` **Note:** if you use a command-line environment on Windows, the official recommendation is currently to run OpenCode in WSL. ## Installation The recommended approach is the install command from the OpenCode website: ```bash curl -fsSL https://opencode.ai/install | bash ``` The OpenCode website also offers npm, bun, brew and other installation methods. ## Set the API Key Use OpenCode's own connection / authentication flow: ```bash opencode auth login ``` Alternatively, run /connect in the interactive UI and save this service as a custom provider. If you prefer environment variables, have opencode.json read the standard variable name, for example: ```bash export OPENAI_API_KEY="your_api_key_here" ``` ## Configure opencode.json Create opencode.json in the project root or your global configuration directory: ```json { "$schema": "https://opencode.ai/config.json", "provider": { "aicentos": { "npm": "@ai-sdk/openai", "name": "aicentos", "options": { "baseURL": "https://aicentos.com/v1", "apiKey": "{env:OPENAI_API_KEY}" }, "models": { "gpt-4o": { "name": "gpt-4o" } } } }, "model": "aicentos/gpt-4o" } ``` ## Test After starting OpenCode, run: ``` /models ``` You should see the models under aicentos. ## Notes * Recommended order: configure the file manually first (opencode.json), then environment variables, and only then the cc-switch tool ([https://github.com/farion1231/cc-switch/releases](https://github.com/farion1231/cc-switch/releases)) * If you go through /v1/responses, the official OpenCode documentation recommends @ai-sdk/openai * Only switch to @ai-sdk/openai-compatible if your endpoint only supports /v1/chat/completions * No need to define project-private variables such as CODEX\_PROXY\_API\_KEY ## Related links * Official website: [https://opencode.ai/](https://opencode.ai/) --- # OpenCodeReview Source: https://docs.aicentos.com/en/clients/opencodereview Language: en > Use aicentos in OpenCodeReview (OCR) — wire up code review through a custom provider OpenCodeReview (command name `ocr`) is Alibaba's open-source AI code review CLI: it reads the Git diff and calls a large model for review comments. It ships with an OpenAI-compatible provider and also supports custom OpenAI-compatible gateways, so requests can be routed to aicentos. ## Prerequisites Create a dedicated key in the aicentos console (naming it `ocr-ci` makes usage easier to track). OCR only supports the OpenAI and Anthropic protocols; this guide uses OpenAI's Chat Completions path. Code review depends on the model's **function calling** capability, so pick a model that supports tool calling. ## Configuration to fill in | Field | Value | | -------- | --------------------------------------------------------------------------------- | | provider | `openai` (built-in, override its URL) or a custom provider | | protocol | `openai` (Chat Completions) | | URL | `https://aicentos.com/v1` | | API Key | The key created in the console | | Model | A model name from the Model Gallery in the console; must support function calling | ## Setup steps * Install the CLI (Node.js required, or Homebrew on macOS): ```bash npm install -g open-code-review ``` * Write the configuration with the non-interactive commands; it ends up in `~/.opencodereview/config.json`: ```bash ocr config set provider openai ocr config set model claude-sonnet-5 ocr config set providers.openai.url https://aicentos.com/v1 ocr config set providers.openai.api_key your_api_key_here ``` * If you prefer a graphical walkthrough, run `ocr config provider` and `ocr config model` instead: pick the provider, enter the key and choose the model in the TUI, and a connectivity check runs automatically at the end. ## Test Verify the endpoint on its own first: ```bash ocr llm test ``` Once it passes, run a real review in any Git repository: ```bash ocr review ``` ## Notes * The URL only goes up to `/v1`; do not extend it to the full `/chat/completions`. * The configuration resolver needs all three of **URL, key and model**; merely `export`ing environment variables is not enough — anything missing must still be written into config.json, otherwise you get a 401. * Environment variables can also override the configuration temporarily and take the highest precedence: `OCR_LLM_URL` / `OCR_LLM_TOKEN` / `OCR_LLM_MODEL`. * For the built-in provider the field is `providers..url`; for custom providers it is `custom_providers..url`. Do not mix up the two maps. * An insufficient account balance shows up as 401 / 403; check the balance on the [wallet page](https://aicentos.com/wallet) first. * Official repository: `https://github.com/alibaba/open-code-review` --- # Orca Source: https://docs.aicentos.com/en/clients/orca Language: en > Use aicentos in Orca — add an OpenAI-compatible custom endpoint Orca supports configuring a custom OpenAI-compatible service. Point the Base URL at aicentos and fill in the API Key, and the models aicentos offers become available in Orca. ## Prerequisites First create a dedicated key for Orca on the console's "API Keys" page (naming it `orca` makes usage easier to track). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) * Docs site: [https://docs.aicentos.com](https://docs.aicentos.com) ## Configuration to fill in | Field | Value | | ------------- | -------------------------------------------------- | | Provider type | OpenAI Compatible | | Base URL | `https://aicentos.com/v1` | | API Key | The key created in the console | | Model | A model name from the Model Gallery in the console | ## Setup steps * Open Orca's settings page and go to the model / provider configuration area. * Add a new provider and choose the OpenAI-compatible type (OpenAI Compatible / Custom OpenAI). * Enter `https://aicentos.com/v1` as the Base URL. * Enter the key created in the console as the API Key. * Enter a model name from the Model Gallery in the console as the Model (see [Supported models](https://docs.aicentos.com/en/billing/models-list)). * Save and set it as the default model. ## Test Start a new conversation and send a simple prompt; confirm it returns normally. If the model dropdown is empty, type the Model ID manually instead. ## Notes * The Base URL only goes up to `/v1`; do not extend it to the full `/v1/chat/completions` path. * If the settings do not take effect right away after saving, restart Orca once. * If your Orca version only supports the built-in official providers and has no custom Base URL entry, that version cannot connect to third-party endpoints; switch to another client that supports a custom Base URL. * Common causes of connection failures: a wrong Base URL, leading/trailing spaces in the key, a nonexistent model name, or an insufficient account balance. --- # Paseo Source: https://docs.aicentos.com/en/clients/paseo Language: en > Connect aicentos in Paseo — it does not talk to models directly, so configure the underlying CLI or the provider env Paseo is an orchestration layer: the desktop app, mobile, web, and the `paseo` CLI all exist, but **it ships no agent of its own** and only runs coding CLIs you have already installed and signed in to (Claude Code, Codex, OpenCode, Pi, and so on). So connecting aicentos in Paseo really means making the hosted CLI go through aicentos. ## Prerequisites First install Paseo and have at least one underlying CLI ready: ```bash npm install -g @getpaseo/cli paseo ``` Download the desktop and mobile apps from the official site. Note that the Docker image contains no agent CLI, so a container deployment has to install them yourself. ## Configuration to fill in Paseo providers are defined under `agents.providers.` in `~/.paseo/config.json`, with the fields `extends`, `label`, `env`, and `models`. **What it supports is injecting environment variables into the underlying CLI**, and the official examples all use the Anthropic-compatible protocol: | Field | Value | | ------------------------ | -------------------------------------------------- | | `extends` | The underlying CLI, for example `claude` | | `env.ANTHROPIC_BASE_URL` | `https://aicentos.com` | | `env.ANTHROPIC_API_KEY` | The key created in the console | | `models` | A model name from the Model Gallery in the console | ## Setup steps Edit `~/.paseo/config.json`: ```json { "agents": { "providers": { "aicentos-claude": { "extends": "claude", "label": "aicentos", "env": { "ANTHROPIC_BASE_URL": "https://aicentos.com", "ANTHROPIC_API_KEY": "sk-your-API-Key" } } } } } ``` Reload after the change: ```bash paseo reload ``` Then set the session's provider to `aicentos` in Paseo. If you are hosting an OpenAI-protocol CLI (such as Codex), replace `env` with that CLI's own variables (`OPENAI_BASE_URL`, `OPENAI_API_KEY`) and use `https://aicentos.com/v1` as the Base URL. ## Test ```bash paseo run --provider aicentos-claude "Introduce yourself in one sentence" ``` A response means it works. You can also create a session directly in the desktop app and see whether the model label shows the provider you configured. ## Notes * **Paseo has no model configuration of its own**. It is normal that there is no Base URL input box; look in the underlying CLI or in `env` instead. * The official docs only give Anthropic-compatible field examples; there is no written rule for OpenAI-compatible endpoints, so follow the underlying CLI's variable names and trust what you measure. * `env` overrides the sign-in state already saved by the underlying CLI; a wrong value also breaks sessions that used to work, so prefer adding a new provider rather than editing the default one. * You must complete authentication in the underlying CLI first; Paseo does not sign in on your behalf. ## Related links * [Paseo custom provider docs](https://paseo.sh/docs/custom-providers) * [paseo repository](https://github.com/getpaseo/paseo) --- # Pi Source: https://docs.aicentos.com/en/clients/pi Language: en > Use aicentos in Pi — configure a custom OpenAI-compatible endpoint Pi supports specifying a custom OpenAI-compatible API address. Point the Base URL at aicentos and fill in the API Key, and the models aicentos offers become available in Pi. ## Prerequisites First create a dedicated key for Pi on the console's "API Keys" page (naming it `pi` makes usage easier to track). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Top up when the balance runs out: [https://aicentos.com/wallet](https://aicentos.com/wallet) * Docs site: [https://docs.aicentos.com](https://docs.aicentos.com) ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | Provider | OpenAI Compatible | | Base URL | `https://aicentos.com/v1` | | API Key | The key created in the console | | Model | A model name from the Model Gallery in the console | ## Setup steps * Open Pi's settings and find the API / model configuration area. * Choose the custom OpenAI-compatible provider. * Enter `https://aicentos.com/v1` as the Base URL. * Enter the key created in the console as the API Key. * Enter a model name from the Model Gallery in the console as the Model (see [Supported models](https://docs.aicentos.com/en/billing/models-list)). * Save and select that model in the session. ## Test Run one simple conversation round and confirm it returns normally. Use `/model` or the settings page to confirm the current model really comes from aicentos rather than the built-in default provider. ## Notes * The Base URL only goes up to `/v1`; do not write the full API path. * If Pi also keeps the built-in provider around, make sure you switch back to the one you created — otherwise requests will not go through aicentos. * If your Pi version offers no custom Base URL, third-party endpoints cannot be connected; switch to another client that supports a custom Base URL. * Creating a separate key for this client is recommended, so usage can be told apart per key in the console. --- # Prime Agent Source: https://docs.aicentos.com/en/clients/prime-agent Language: en > Connect aicentos in Prime Agent — currently only the API-key provider works, and the endpoint field is not publicly documented Prime Agent is Prime Intellect's open-source terminal coding agent (written in Rust, MIT licensed), positioned as a self-improving RLM harness. It supports connecting external models with an API Key, but **the field for a custom Base URL is not publicly documented**, so what follows is split into "confirmed to work" and "you need to verify it yourself". ## Prerequisites First create a dedicated key for Prime Agent in the console (naming it `prime-agent` is recommended). ```bash curl -fsSL https://app.primeintellect.ai/prime-agent/install.sh | sh ``` Windows: ```powershell irm https://app.primeintellect.ai/prime-agent/install.ps1 | iex ``` ## Configuration to fill in | Field | Value | | -------------- | ----------------------------------------------------- | | Authentication | `/login` on first launch, choose an API-key provider | | API Key | The key created in the console | | Base URL | `https://aicentos.com/v1` (field name to be verified) | | Model | A model name from the Model Gallery in the console | ## Setup steps On the first launch, run `/login` and choose to use an API Key rather than a subscription provider. This step is the path the official docs state explicitly. Its known configuration file is `models.json`, and officially only the model-override form is published: ```json { "providers": { "your-provider": { "modelOverrides": { "your-model-name": { "contextWindow": 128000 } } } } } ``` `modelOverrides` only changes model parameters; **it is not an endpoint definition**. To change the endpoint you need to find the endpoint field in the provider selected at `/login` — the official repository README does not give the field name, so look at which keys exist in the configuration file generated after startup and fill them in accordingly rather than guessing. ## Test ```bash prime-agent ``` Send one prompt in the session. An authentication error means the provider was not chosen correctly; a response with the wrong model name means the endpoint and the model are configured separately, so go back and check `models.json`. ## Notes * **It is not a security sandbox**: it executes model-generated Python and commands with your user privileges, so do not run unfamiliar tasks on a machine holding production credentials. * Telemetry is on by default; `PRIME_AGENT_TELEMETRY=0` turns it off. * Use `NODE_EXTRA_CA_CERTS` when a corporate network needs a custom CA. * The endpoint field is not publicly documented, so this is in a figure-it-out-yourself state. If you cannot get it working, switch to [Oh My Pi](https://docs.aicentos.com/en/clients/oh-my-pi) or [Gajae Code](https://docs.aicentos.com/en/clients/gajae-code), whose fields are explicit. ## Related links * [prime-agent repository](https://github.com/PrimeIntellect-ai/prime-agent) --- # Qwen Source: https://docs.aicentos.com/en/clients/qwen Language: en > Use aicentos in Qwen Code — configure an OpenAI-compatible provider through settings.json Qwen Code can register any OpenAI-compatible endpoint through `modelProviders` in `settings.json`. Point `baseUrl` at aicentos and the models aicentos offers become usable in Qwen Code. ## Prerequisites First create a dedicated key for Qwen Code on the console's "API Keys" page (naming it `qwen-code` makes usage easier to track). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Wallet top-up: [https://aicentos.com/wallet](https://aicentos.com/wallet) * Docs site: [https://docs.aicentos.com](https://docs.aicentos.com) Qwen Code requires Node.js 20+; install globally with npm: ```bash npm install -g @qwen-code/qwen-code qwen --version ``` ## Configuration to fill in | Field | Value | | --------- | --------------------------------------------------------------- | | auth type | `openai` (OpenAI-compatible protocol) | | baseUrl | `https://aicentos.com/v1` | | envKey | Name of the environment variable holding the key (customizable) | | Model id | A model name from the Model Gallery in the console | ## Setup steps Edit `~/.qwen/settings.json`: ```json { "env": { "AICENTOS_API_KEY": "sk-your-Key" }, "modelProviders": { "openai": [ { "id": "gpt-4o", "name": "GPT-4o", "baseUrl": "https://aicentos.com/v1", "envKey": "AICENTOS_API_KEY" } ] }, "security": { "auth": { "selectedType": "openai" } }, "model": { "name": "gpt-4o" } } ``` * `id` is the model ID actually sent to the server and must match the model name in the console. * Do not put a plain-text key in `modelProviders`; `envKey` is just a reference to which environment variable holds the key. * Key precedence: system environment variables > `.env` file (`~/.qwen/.env`) > the `env` block in `settings.json`. * If the aicentos side uses the Responses protocol, add `"wireApi": "responses"` to that model; when omitted it defaults to Chat Completions. Alternatively, skip the configuration file entirely and use environment variables: ```bash export OPENAI_BASE_URL="https://aicentos.com/v1" export OPENAI_API_KEY="sk-your-Key" export OPENAI_MODEL="gpt-4o" ``` ## Test Start `qwen`, use `/about` to confirm the current endpoint and model are correct, then send a simple prompt. With multiple provider entries configured, you can switch with `/model`. ## Notes * Global configuration lives in `~/.qwen/settings.json`; project-level configuration lives in `.qwen/settings.json` at the project root, which takes precedence. * `security.auth.selectedType` must be `openai`, otherwise the custom endpoint is not used. * Never commit a plain-text key to version control; prefer `~/.qwen/.env` or system environment variables. * `wireApi` is only local routing metadata and is not sent in the request body; before switching it to `responses`, confirm that the aicentos side supports `/v1/responses`. * Enter the Base URL only up to `/v1`; do not extend it to the full endpoint path. --- # Reasonix Source: https://docs.aicentos.com/en/clients/reasonix Language: en > Use aicentos in Reasonix — add a custom provider through config.toml Reasonix is a local coding agent (a CLI/TUI, desktop app, browser UI and an editor ACP entry point, all sharing the same engine). It has no built-in aicentos provider, but you can add an OpenAI-compatible `[[providers]]` entry to `~/.reasonix/config.toml` and route requests to aicentos. ## Prerequisites Create a dedicated key in the aicentos console (naming it `reasonix-cli` is recommended). Reasonix stores provider keys in its own global `.env` file and does not read shell environment variables. ## Configuration to fill in | Field | Value | | ------------- | -------------------------------------------------- | | name | `aicentos` (local provider ID) | | kind | `openai` (Chat Completions) | | base\_url | `https://aicentos.com/v1` | | api\_key\_env | `AICENTOS_API_KEY` | | models | A model name from the Model Gallery in the console | ## Setup steps * Install Reasonix (npm, or Homebrew on macOS): ```bash npm i -g reasonix ``` * Put the key into Reasonix's global `.env`: ```bash # macOS / Linux echo 'AICENTOS_API_KEY=your_api_key_here' >> ~/.reasonix/.env # Windows: %APPDATA%\reasonix\.env ``` * Edit `~/.reasonix/config.toml` and merge in the following (do not remove your other existing providers): ```toml default_model = "aicentos" [[providers]] name = "aicentos" kind = "openai" base_url = "https://aicentos.com/v1" models = ["claude-sonnet-5", "deepseek-v4-pro", "qwen3-coder-plus"] default = "claude-sonnet-5" api_key_env = "AICENTOS_API_KEY" context_window = 200000 ``` * Start it from a project directory: ```bash reasonix ``` You can also verify with a one-off task first: `reasonix run "Explain in one sentence what project the current directory is"`. On the desktop app, go through **Settings → Model → Access → Add model service → Custom provider** instead. ## Test After starting, send a simple prompt and confirm responses stream back normally. Use `/model` inside the session to switch models. ## Notes * `base_url` should only go up to `/v1`; Reasonix appends `/chat/completions` itself. * The key must be written to `~/.reasonix/.env`; `export`-ing it in the shell or putting it in a project `.env` will not be recognized as the provider key. * Choose `openai` for `kind`; the native `anthropic` type maps to the Anthropic Messages endpoint and does not fit here. * `default_model` takes the provider's `name` (`aicentos`), not a model name. * If the desktop app's custom provider form asks for the full address, enter `https://aicentos.com/v1/chat/completions`. * Project page: `https://github.com/esengine/DeepSeek-Reasonix` --- # Roo Code Source: https://docs.aicentos.com/en/clients/roo-code Language: en > Configure an OpenAI Compatible provider in Roo Code with the aicentos Base URL and API Key Roo Code officially supports the OpenAI Compatible provider, so it can connect to this service directly. ## Installation Official installation page: [https://roocode.com/extension](https://roocode.com/extension) If you use VS Code or a compatible fork, the most direct way to install is: ```bash code --install-extension RooVeterinaryInc.roo-cline ``` You can also search for `Roo Code` in the extension marketplace and install the official plugin. ## Open the provider configuration Open the settings page in the Roo Code panel and go to the model provider configuration. ## Configuration to fill in Set `API Provider` to `OpenAI Compatible`, then fill in: * Base URL: `https://aicentos.com/v1` * API Key: your `codex_...` or `sk-...` key * Model ID: `gpt-5-codex-mini` If the model is not listed in the dropdown, you can type the model name manually. ## Test After saving, start a new task and confirm Roo Code connects normally and starts replying. ## Notes * The official Roo Code documentation requires the `OpenAI Compatible` provider * Roo Code's OpenAI-compatible provider depends on the model supporting native tool calling * For this service, simply enter `https://aicentos.com/v1` as the Base URL * Reference documentation: [https://docs.roocode.com/providers/openai-compatible](https://docs.roocode.com/providers/openai-compatible) --- # Senpi (OmO Native) Source: https://docs.aicentos.com/en/clients/senpi Language: en > Connect aicentos in Senpi / OmO — where the config directory and the openai-compatible provider live Senpi is a fork of `pi-mono`, published on npm as `@code-yeongyu/senpi`, with the executable named `senpi`. It is also the runtime for oh-my-openagent (OmO for short), so OmO Native refers to the setup running on the senpi harness. ## Prerequisites ```bash curl -fsSL https://get.omo.dev/install.sh | bash omo ``` bun works too: ```bash bun add -g omo-ai ``` The project describes itself as experimental; the official wording is not to bet it on a production pipeline. ## Configuration to fill in The configuration directory is `~/.omo/agent/`, which `OMO_CODING_AGENT_DIR` can override; the old `SENPI_*` variables are still accepted. | File | Purpose | | --------------- | ----------------------------------------------------- | | `models.json` | provider definitions (endpoint, protocol, model list) | | `auth.json` | keys | | `settings.json` | preferences such as the default model | senpi itself has a separate set: `~/.senpi/agent/settings.json`, plus a project-level `.senpi/settings.json`. | Field | Value | | ----------------- | -------------------------------------------------- | | Provider protocol | `@ai-sdk/openai-compatible` | | Base URL | `https://aicentos.com/v1` | | API Key | The key created in the console | | Model | A model name from the Model Gallery in the console | ## Setup steps Add a provider in `~/.omo/agent/models.json` and choose the OpenAI-compatible protocol family (the mapping the docs give is `npm: @ai-sdk/openai-compatible`): ```json { "providers": { "aicentos": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "https://aicentos.com/v1", "apiKey": "sk-your-API-Key" }, "models": { "your-model-name": {} } } } } ``` The key can also live separately in `auth.json` instead of `models.json`. Then write the default model into `settings.json`. ## Test Start `omo` or `senpi`, confirm the models under `aicentos` appear in the model picker, and send one line to confirm it returns. ## Notes * Do not mix up the two configuration directories: the OmO side is `~/.omo/agent/` and the senpi side is `~/.senpi/agent/`; changes in the wrong place have no effect. * A project-level `.senpi/settings.json` overrides the global settings, so when troubleshooting, check the project directory first. * The official docs only give the migration mapping, not a complete literal configuration snippet; the structure above follows Pi-family conventions, so check the field names against the current version at `omo.dev/docs`. * It is an experimental project, so the configuration structure may change after an upgrade. ## Related links * [OmO docs](https://omo.dev/docs) * [senpi repository](https://github.com/code-yeongyu/senpi) * [oh-my-openagent repository](https://github.com/code-yeongyu/oh-my-openagent) --- # SillyTavern Source: https://docs.aicentos.com/en/clients/sillytavern Language: en > Add aicentos as an OpenAI-compatible backend in SillyTavern: enter the Base URL and API Key to use every available model # SillyTavern SillyTavern is a popular roleplay chat application that supports many AI model backends. By configuring an OpenAI-compatible API, it can connect to this service. ## Open the API connection settings 1. Start SillyTavern 2. Click the API connection icon at the top 3. Select **Chat Completion (OpenAI Compatible)** ## Configure the connection details In the API settings panel, fill in: * **API Type**: select `OpenAI` * **Chat Completion Source**: select `OpenAI` or `OpenAI Compatible` * **API URL**: `https://aicentos.com/v1` * **API Key**: your API Key (e.g. `codex_...` or `sk-...`) * **Model**: select or enter a model ID (e.g. `gpt-6-astra`) ## Test the connection 1. Click the **Connect** button 2. If the connection succeeds, the status indicator turns green 3. You can start chatting with your characters ## Notes * The API URL only needs to go up to `/v1`; the full `/v1/chat/completions` path is not required * Streaming responses are supported; enabling them in the advanced settings is recommended * You can type a model ID manually in the model dropdown ## Official documentation See the [SillyTavern official documentation](https://docs.sillytavern.app/) for more configuration options. --- # TavernAI Source: https://docs.aicentos.com/en/clients/tavernai Language: en > Point TavernAI at the aicentos OpenAI-compatible API: enter the Base URL and API Key to start chatting # TavernAI TavernAI is a roleplay chat application that supports connecting to a custom API service through an OpenAI-compatible interface. ## Open the settings 1. Start TavernAI 2. Click the settings icon in the upper-right corner 3. Find the **API Settings** or **AI Configuration** section ## Configure the API connection In the API settings, fill in: * **API Type**: select `OpenAI` * **API Endpoint**: `https://aicentos.com/v1` * **API Key**: your API Key (e.g. `codex_...` or `sk-...`) * **Model**: the model ID (e.g. `gpt-6-astra`) ## Save and test 1. Click **Save** to save the settings 2. Return to the chat screen 3. Send a message to test the connection ## Notes * TavernAI's interface may differ slightly between versions * Make sure the API Endpoint ends with `/v1` * If the connection fails, check that the API Key is correct ## Related links TavernAI is a community project; related documentation and support can be found on GitHub. --- # Trae Source: https://docs.aicentos.com/en/clients/trae Language: en > Add a custom OpenAI-compatible service in Trae settings, with the aicentos Base URL and your API Key This document explains how to connect to this service in Trae using a custom OpenAI-compatible configuration. The settings entry points vary between Trae versions, so instead of tying this guide to a single menu path, it describes the key settings you need to find. ## Open the AI / Model settings In Trae's settings, look for the configuration areas matching these keywords: * AI * Models * Provider * OpenAI * Custom If the current version supports custom OpenAI-compatible connections, it usually provides inputs for the model provider, API Key and Base URL. ## Configuration to fill in Fill in for this service: * Base URL: [https://aicentos.com/v1](https://aicentos.com/v1) * API Key: your codex\_... or sk-... key * Model ID: follow the results returned by GET /v1/models; if you only want a quick connectivity test, try gpt-6-astra first ## Test After saving, start a new conversation, editing task or agent task, and confirm Trae can send requests and return content normally. ## Notes * The value entered here is the OpenAI-compatible Base URL; do not extend it to the full /chat/completions or /responses path * If your current version only offers the built-in official models, or only accepts an official OpenAI key without letting you change the Base URL, it cannot connect to this gateway directly * The safest approach is to verify the visible models with GET /v1/models first, then enter the Model ID in Trae --- # Unsloth Source: https://docs.aicentos.com/en/clients/unsloth Language: en > Unsloth is a fine-tuning and local inference framework, not a chat client — why it cannot connect to aicentos Unsloth is an open-source framework for model fine-tuning and local inference, with a desktop app and Unsloth Studio (a browser interface). Its `Connections` panel looks like model provider settings, but **it only accepts local or self-hosted endpoints, and cloud providers are a fixed list** — there is no any OpenAI-compatible URL entry, so inference requests cannot be pointed at aicentos. ## Why it cannot connect directly * In Studio's `Settings → Connections → Add Provider`, the choices are **local or self-hosted services** such as llama.cpp, vLLM, and Ollama, and the Base URL you fill in looks like `http://localhost:8000/v1`. * The cloud side is a fixed list (OpenAI, Anthropic, OpenRouter, ChatGPT/Codex) plus an API Key, with no entry for a custom endpoint. * In the official docs, remote OpenAI-compatible endpoint means an inference service **you deploy yourself**, not a third-party aggregation gateway. * Its direction is also server-side: Unsloth exposes an OpenAI-compatible API of its own for others to connect to. ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | API Key | The key created in the console | | Base URL | `https://aicentos.com/v1` | | Model | A model name from the Model Gallery in the console | The table above lists the generic aicentos-side parameters, for use with the alternatives below. ## Alternatives ### Alternative 1: Training is training, chatting is chatting Use Unsloth for fine-tuning and local inference, and a client such as [Cherry Studio](https://docs.aicentos.com/en/clients/cherry-studio) or [Chatbox](https://docs.aicentos.com/en/clients/chatbox) to connect aicentos for everyday conversation. The two do not interfere with each other. ### Alternative 2: Serve locally, point the front end at it What Unsloth exposes is an OpenAI-compatible endpoint. Once the `unsloth` service is running locally, set the client's Base URL to its address (for example `http://localhost:8000/v1`) — the same set of steps as filling in aicentos. ### Alternative 3: To compare results, switch the front end To compare a locally fine-tuned model with a general model on aicentos, a client that supports several providers side by side is the least work, switching in the same interface. ## Test Once the local service is up, first `curl http://localhost:8000/v1/models` to confirm the endpoint is alive, then send one prompt in the client. ## Notes * Do not treat Studio's `Connections` as a BYOK panel; what it governs is the local runtime. * Local inference is hardware-hungry; for long-context and high-volume tasks, prefer aicentos. * The official docs describe no workflow for generating training data with a third-party API, so do not plan a pipeline around that idea. ## Related links * [Unsloth Connections docs](https://unsloth.ai/docs/integrations/connections) * [unsloth repository](https://github.com/unslothai/unsloth) --- # Warp Source: https://docs.aicentos.com/en/clients/warp Language: en > Use aicentos in Warp — drive the Warp Agent through a custom inference endpoint Warp is an agent development environment in the terminal. It supports **custom inference endpoints**: as long as the other side implements the OpenAI Chat Completions interface, Warp Agent's model calls can be routed there. Point the endpoint at aicentos and the models under your own account can drive Warp's Agent. ## Prerequisites * Update Warp to a version that includes custom inference endpoints (older versions only have BYOK and cannot change the Base URL). * Create a dedicated key in the aicentos console (naming it `warp-terminal` is a good idea). * Confirm the models you plan to use support **function calling**, which Warp Agent relies on to read and write files and run commands. ## Configuration to fill in | Field | Value | | ------------- | ------------------------------------------------------ | | Endpoint name | `aicentos` (custom; identifies it in the model picker) | | Endpoint URL | `https://aicentos.com/v1` | | API Key | The key created in the console | | Model name | A model ID from the Model Gallery in the console | | Model alias | Optional; the name shown in the model picker | ## Setup steps * Open Warp's settings, search for `inference endpoint`, or go to **Settings → AI**. * In the **Custom inference** area, click **Add custom model** / **Add destination**. * In the dialog, fill in the Endpoint name, Endpoint URL (`https://aicentos.com/v1`) and API Key. * Enter the model ID under **Model name** and click **Add model** to add more; an alias can be set for easier identification. * After saving, the custom models appear in Warp's model picker, labeled with your endpoint name. ## Test Select the newly added model in Warp and send a simple question (e.g. "List the files in the current directory and explain the project structure") to confirm it returns normally. Custom endpoint models show up in the agent mode, toolbar and ambient agent pickers. ## Notes * The Endpoint URL takes the OpenAI-compatible root path (from which `/v1/chat/completions` can be formed); do not write the full `/v1/chat/completions`. * The endpoint must be reachable from the **public internet**: Warp's requests are relayed through its servers, and `localhost` or intranet addresses are rejected. `aicentos.com` is a public HTTPS address and works as is. * The API Key and endpoint information are stored in the secure storage of the **local device**; Warp's servers only use them at request time and do not retain them. * Requests through a custom endpoint **do not consume Warp's AI credits**; costs are billed on the aicentos side by usage. However, under Business / Enterprise plans, running local agents still consumes platform credits. * If you get `400 invalid model format`, your gateway expects the `provider/model_id` form; follow the model ID given in the console and add the prefix in that format if necessary. * Custom endpoints cannot currently declare a context window separately, so very long sessions may be compacted early. * Official documentation: `https://docs.warp.dev/agent-platform/inference/custom-inference-endpoint/` --- # Windsurf Source: https://docs.aicentos.com/en/clients/windsurf Language: en > Enter the aicentos endpoint and API Key in Windsurf once your build supports a custom Base URL This document explains how to connect to this service in Windsurf using a custom OpenAI-compatible configuration. Windsurf's BYOK and custom model capabilities differ between versions, so two cases are covered here. ## First check whether your version supports a custom Base URL In Windsurf's model, subscription or AI settings, look for entries like these: * `Models` * `BYOK` * `OpenAI` * `Custom` * `Base URL` If you can only enter an official API Key and there is no editable Base URL, that version usually only supports the official BYOK mode and cannot be pointed at this gateway directly. ## Fill in the custom connection details If your version offers a custom OpenAI-compatible configuration, fill in: * Base URL: `https://aicentos.com/v1` * API Key: your `codex_...` or `sk-...` key * Model ID: follow the results returned by `GET /v1/models`; if you only want a quick connectivity test, try `gpt-6-astra` first ## Test After saving the settings, start a new Cascade conversation or coding task and confirm results come back normally. ## Notes * The Base URL should be `https://aicentos.com/v1` * Do not write the full `/v1/chat/completions` or `/v1/responses` path * If the current version only offers official BYOK with no custom Base URL, it cannot connect to this gateway directly * Windsurf's official models page: `https://docs.windsurf.com/windsurf/models` --- # WorkBuddy Source: https://docs.aicentos.com/en/clients/workbuddy Language: en > Use aicentos in WorkBuddy — connect through a custom OpenAI-compatible configuration WorkBuddy supports configuring custom OpenAI-compatible models. Point the Base URL at aicentos and fill in the API Key, and WorkBuddy runs on the models aicentos offers. ## Prerequisites Create a dedicated key in the aicentos console (naming it `workbuddy` makes usage easier to track). ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | Provider | `OpenAI Compatible` | | API Key | The key created in the console | | Base URL | `https://aicentos.com/v1` | | Model ID | A model name from the Model Gallery in the console | ## Setup steps * Open WorkBuddy's model / AI settings. * Set the Provider to **OpenAI Compatible** (or "Custom"). * Enter the API Key you created in the aicentos console. * Set the Base URL to: `https://aicentos.com/v1` * Enter the model ID (see [Supported models](https://docs.aicentos.com/en/billing/models-list)); type it manually if necessary. * Save the settings. ## Test After saving, start a new conversation and send a simple prompt to confirm it connects and returns content normally. ## Notes * Enter the Base URL only up to `/v1`; do not append the full `/chat/completions` path. * If the current version has no editable Base URL and only accepts official keys, it cannot connect to this gateway directly; switch to a client that supports custom endpoints. * Verify the visible models with `GET /v1/models` first, then enter the Model ID in WorkBuddy. * Requests fail when the account balance is insufficient; check the balance on the [wallet page](https://aicentos.com/wallet) first. --- # ZCode Source: https://docs.aicentos.com/en/clients/zcode Language: en > Use aicentos in ZCode — connect through custom OpenAI-compatible settings ZCode supports custom OpenAI-compatible model configurations. Point the Base URL at aicentos and fill in the API Key, and the models aicentos offers become available in ZCode's chats and coding tasks. ## Prerequisites Create a dedicated key in the aicentos console (naming it `zcode` makes usage easier to track). ## Configuration to fill in | Field | Value | | -------- | -------------------------------------------------- | | Provider | `OpenAI Compatible` | | API Key | The key created in the console | | Base URL | `https://aicentos.com/v1` | | Model ID | A model name from the Model Gallery in the console | ## Setup steps * Open ZCode's settings and go to the model / AI configuration area. * Find the provider options and choose **OpenAI Compatible** (or "Custom OpenAI"). * Enter the API Key you created in the aicentos console. * Set the Base URL to: `https://aicentos.com/v1` * Enter the model ID (see [Supported models](https://docs.aicentos.com/en/billing/models-list)); if the dropdown does not include the target model, type it in manually. * Save the settings; if a **Verify** button is offered, click it once. ## Test Start a new conversation or coding task and send a simple prompt; confirm content comes back normally. ## Notes * The Base URL only goes up to `/v1`; do not extend it to the full `/chat/completions` or `/v1/responses` path. * If the current version only offers the official built-in models with no editable Base URL, it cannot connect to this gateway directly and you must switch to a client that supports custom endpoints. * It is a good idea to confirm the visible models with `GET /v1/models` first, then fill in the Model ID in ZCode. * Requests fail when the account balance runs out; check the balance on the [wallet page](https://aicentos.com/wallet) first. --- # Zed Agent Source: https://docs.aicentos.com/en/clients/zed-agent Language: en > Connect aicentos in Zed's Agent Panel through an OpenAI-compatible provider Zed ships with a built-in OpenAI-compatible provider type. Declare the endpoint, models and context lengths in `settings.json` and the Agent Panel can use the models aicentos offers. ## Prerequisites First create a dedicated key for Zed on the console's "API Keys" page (naming it `zed-agent` is recommended). * Console: [https://aicentos.com](https://aicentos.com) * Create a key: [https://aicentos.com/keys](https://aicentos.com/keys) * Wallet top-up: [https://aicentos.com/wallet](https://aicentos.com/wallet) Zed does not read the API Key from `settings.json`; it reads an environment variable derived from the provider ID: the ID is converted to upper snake case with an `_API_KEY` suffix. So with the provider ID set to `aicentos`, the environment variable name is `AICENTOS_API_KEY`. ## Configuration to fill in | Field | Value | | ------------------------------- | -------------------------------------------------- | | Provider ID | Custom, e.g. `aicentos` | | `api_url` | `https://aicentos.com/v1` | | `available_models[].name` | A model name from the Model Gallery in the console | | `available_models[].max_tokens` | The model's context window | | API Key | Environment variable `AICENTOS_API_KEY` | ## Setup steps * Open Zed's `settings.json` (run `zed: open settings` from the command palette). * Add the `language_models.openai_compatible` configuration: ```json { "language_models": { "openai_compatible": { "aicentos": { "api_url": "https://aicentos.com/v1", "available_models": [ { "name": "gpt-5", "display_name": "GPT-5 (aicentos)", "max_tokens": 128000, "max_output_tokens": 16384, "capabilities": { "tools": true, "images": false, "chat_completions": true } } ] } } } } ``` * Export the environment variable (add it to `~/.zshrc` and reload the shell): ```bash export AICENTOS_API_KEY="sk-your-aicentos-key" ``` * Open the Agent Panel and pick a model under that provider in the model dropdown. You can also click **Add Provider** in the Agent settings and fill in the provider name, API URL, model ID and context window through the graphical interface. ## Test Once configured, start a new conversation in the Agent Panel and try a lightweight test with a simple prompt first; only rely on tool calls once responses come back normally. ## Notes * `api_url` should only go up to `https://aicentos.com/v1`; do not append the full `/chat/completions` path — Zed assembles it itself. * The API Key must not be written directly into `settings.json`; use an environment variable (or store it in the system keychain via the provider settings UI). A non-empty environment variable takes precedence over the keychain. * `max_tokens` is the context window; set it to the model's actual value. Leaving it out breaks context management. * Tool calling is enabled by default (`capabilities.tools`); image input and parallel tool calls are off by default — enable them manually if needed. * Official documentation: [https://zed.dev/docs/ai/llm-providers](https://zed.dev/docs/ai/llm-providers) * See the docs site for more details: [https://docs.aicentos.com](https://docs.aicentos.com) --- # Introduction to aicentos Source: https://docs.aicentos.com/en/introduction Language: en > One API for every LLM — aggregation of OpenAI, Anthropic, Google, xAI and other major vendors **aicentos** is an AI API aggregation platform for developers. One API Key to call LLMs from OpenAI, Anthropic, Google, xAI, DeepSeek and other major vendors. aicentos website ## What problem we solve What makes LLM integration painful? Separate sign-ups, separate keys, separate billing, separate SDKs. aicentos flattens all of that. | Pain point | Traditional approach | aicentos | | -------------------- | ---------------------------------- | -------------------------------------- | | Switching models | Change SDK, URL and key | **Change one `model` parameter** | | Overseas accounts | Foreign credit card / phone number | **¥1 free on sign-up, Alipay top-up** | | API specs | One per vendor | **Unified OpenAI-compatible protocol** | | Billing transparency | Separate dashboards | **Unified billing and usage logs** | | Key governance | No fine-grained permissions | **Quotas, model allowlists, IP rules** | The console puts keys, balance, usage and logs in one place: Console overview ## Core features ### Multi-vendor model access OpenAI, Anthropic, Google, xAI, Alibaba Qwen, DeepSeek, Zhipu, Moonshot, MiniMax — **all behind one endpoint**, covering chat, reasoning, code, image, video and embeddings. New models are adapted as they launch; your existing SDK calls stay the same. See [Supported models](https://docs.aicentos.com/en/billing/models-list) for the full list. ### Checkable availability Every model has its own health checks. On the [model status monitor](https://docs.aicentos.com/status) you can see 1-hour / 24-hour / 7-day availability, response latency and endpoint PING — confirm a model's current state before you integrate. ### Secure by design API keys support **quota limits, model allowlists, IP rules and expiry times**, issued per project or member for cost tracking and permission revocation. ### Developer friendly Fully **OpenAI-compatible**. Existing OpenAI / Codex projects run after swapping `base_url` to `https://aicentos.com/v1`; Claude / Anthropic and other protocols use the root address `https://aicentos.com` — **zero lines of code to migrate**. ## Who it is for * Developers who want **Claude / GPT / Gemini** without the overseas account and credit card hassle * Researchers / agent developers **switching between multiple LLMs** for comparison * Teams that need **unified billing / quota control / usage audit** * Engineers suffering **high latency / unstable routes** to overseas APIs from mainland China ## Platform numbers | Metric | Value | | -------------- | ------------: | | Sign-up bonus | **¥1 credit** | | Balance expiry | **Never** | ## Next steps * [Quickstart](https://docs.aicentos.com/en/quickstart) — three steps to your first request * [Supported models](https://docs.aicentos.com/en/billing/models-list) — the full model list * [Model status monitor](https://docs.aicentos.com/status) — live availability per model * [Billing](https://docs.aicentos.com/en/billing/pricing) — top-ups and pay-as-you-go --- # Nano Banana 2 Image Generation Source: https://docs.aicentos.com/en/nano-banana2 Language: en > Generate images with gemini-3.1-flash-image-preview (Nano Banana 2) via aicentos — examples for the Gemini native format and the OpenAI-compatible format This page shows request examples for generating images with **Nano Banana 2** (`gemini-3.1-flash-image-preview`) through aicentos. Both the **Gemini native format** and the **OpenAI-compatible format** are supported. Through `imageConfig` you can specify the aspect ratio (`aspectRatio`) and resolution (`imageSize`, e.g. `2K`, `4K`). ## Gemini native format Generate a 1:1 4K image: ```bash export AICENTOS_API_KEY="sk-your-API-Key" curl --location --request POST 'https://aicentos.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent' \ --header "x-goog-api-key: $AICENTOS_API_KEY" \ --header 'content-type: application/json' \ --header 'Accept: */*' \ --data-raw '{ "contents": [ { "parts": [ { "text": "Retro promotional poster style, highlighting Chinese text, with a red and yellow radial burst background. At the center, a beautiful young woman drawn in a refined vintage style, smiling, elegant and approachable. The theme is an ad promotion for the latest AI painting service, 4K resolution\n" } ] } ], "generationConfig": { "responseModalities": [ "image" ], "imageConfig": { "aspectRatio": "1:1", "imageSize": "4K" } } }' ``` ## OpenAI-compatible format Generate a 9:16 2K image: ```bash export AICENTOS_API_KEY="sk-your-API-Key" curl --location --request POST 'https://aicentos.com/v1/chat/completions' \ --header "Authorization: Bearer $AICENTOS_API_KEY" \ --header 'Content-Type: application/json' \ --header 'Accept: */*' \ --data-raw '{ "model": "gemini-3.1-flash-image-preview", "extra_body": { "imageConfig": { "aspectRatio": "9:16", "imageSize": "2K" } }, "messages": [ { "role": "system", "content": "{\"imageConfig\": {\"aspectRatio\": \"9:16\", \"imageSize\": \"2K\"}}" }, { "role": "user", "content": [ { "type": "text", "text": "Draw an auspicious Year of the Horse" } ] } ], "max_tokens": 4096, "temperature": 0.8 }' ``` ## Parameters * `aspectRatio`: aspect ratio, e.g. `1:1`, `9:16`, `16:9`. * `imageSize`: resolution, e.g. `2K`, `4K`. * The Gemini native format authenticates with `x-goog-api-key`; the OpenAI-compatible format authenticates with `Authorization: Bearer`. * In the OpenAI-compatible format, `imageConfig` can go either in `extra_body` or in the JSON of the `system` message. * Replace `sk-your-API-Key` in the examples with the API Key you created in the aicentos console. --- # Quickstart Source: https://docs.aicentos.com/en/quickstart Language: en > Get connected in three steps: register an account → create an API key → enter the Base URL and key in your client Get connected in three steps: **register an account → create an API key → enter the Base URL and key in your client**. ## Step 1: Register an account Open [aicentos.com](https://aicentos.com/) and click **Get Started** in the top-right corner to go to the sign-up page: Sign-up page Fill in a **username** and **password**, agree to the terms of service, then click **Create Account**. Every new account comes with **¥1** in free credit — start calling the API without topping up first. ## Step 2: Create an API key After signing in, open the console, click **API Keys** in the left sidebar, then click **Create API Key** in the top-right corner: API keys page Fill in the settings in the dialog and click **Save Changes**: Create API key | Field | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------- | | Name | A custom name to tell projects apart. Create one per use case for easier cost tracking and permission revocation | | Group | Choose which upstream group to route through; leave empty for the default | | Expiry | "Never expires" or a fixed 1 hour / 1 day / 1 month | | Quantity | Create multiple keys at once; a random suffix is appended to each name | | Unlimited quota | Turn off to set a quota cap for this key | Once created, the key appears in the list as `sk-xxxxxxxxxxxx`, masked by default: Key created The key list supports search by name and key, and shows the group, quota, allowed models, IP restrictions and more. Keys can be edited or deleted at any time: Key list > **The key is shown in full only once, at creation.** Copy and store it right away. Never hard-code it into frontend code or commit it to a public repository. ## Step 3: Enter the Base URL and key in your client ### Pick the right Base URL first This is the step where mistakes happen most — **different protocols use different addresses**: | Use case | Base URL | | ------------------------------------------------- | ------------------------- | | Codex / OpenAI-compatible format | `https://aicentos.com/v1` | | Claude Code / Anthropic format, and other clients | `https://aicentos.com` | > **For the Anthropic protocol, enter the root address only.** Do not append `/v1/messages` manually — the client adds it automatically. You can also look up and copy addresses from the **API Address** dropdown at the top right of the console's **API Keys** page: API address ### Verify connectivity Run a minimal request with curl to confirm the key and network work: ```bash export AICENTOS_API_KEY="sk-your-API-Key" curl https://aicentos.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -d '{ "model": "gemini-3.8-flash", "messages": [ {"role": "user", "content": "Introduce yourself in one sentence"} ] }' ``` You can also request the model list first. If it returns JSON, both the key and the Base URL are working: ```bash export AICENTOS_API_KEY="sk-your-API-Key" curl https://aicentos.com/v1/models \ -H "Authorization: Bearer $AICENTOS_API_KEY" ``` ### Python (OpenAI SDK) ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ["AICENTOS_API_KEY"], base_url="https://aicentos.com/v1", ) resp = client.chat.completions.create( model="gemini-3.8-flash", messages=[{"role": "user", "content": "Introduce yourself in one sentence"}], ) print(resp.choices[0].message.content) ``` ### Node.js (OpenAI SDK) The example uses ESM syntax, so the file needs a `.mjs` extension, or add `"type": "module"` to `package.json`: ```js import OpenAI from 'openai'; const client = new OpenAI({ apiKey: process.env.AICENTOS_API_KEY, baseURL: 'https://aicentos.com/v1', }); const resp = await client.chat.completions.create({ model: 'gemini-3.8-flash', messages: [{ role: 'user', content: 'Introduce yourself in one sentence' }], }); console.log(resp.choices[0].message.content); ``` ### Popular clients * [Claude Code setup](https://docs.aicentos.com/en/claude-code) — one-click import with CC Switch or manual configuration * [Codex setup](https://docs.aicentos.com/en/codex) — graphical configuration or hand-written config.toml * [Cursor setup](https://docs.aicentos.com/en/cursor) — custom OpenAI-compatible settings * [Cherry Studio setup](https://docs.aicentos.com/en/cherry-studio) — add an OpenAI-compatible provider ## Top-up When the sign-up credit runs out, go to **Wallet** in the left sidebar of the console to top up: Wallet Top-up tiers and discounts (**discounts start at ¥100 — you pay less than the top-up amount**): | Top-up amount | Discount | You pay | | -------------------- | -------- | ---------- | | ¥1 / ¥10 / ¥20 / ¥50 | None | Full price | | ¥100 | 1% OFF | ¥99 | | ¥500 | 2% OFF | ¥490 | | ¥1,000 | 3% OFF | ¥970 | | ¥10,000 | 5% OFF | ¥9,500 | You can also enter a custom amount or redeem a code for credit. Payment methods * **Payment methods**: Alipay, WeChat Pay, bank transfer * **Credit never expires**; you are billed for actual token consumption * Referral rewards: when someone signs up through your invite link, both of you earn rewards that can be transferred to your balance at any time ## View usage Open **Dashboard** in the left sidebar of the console to see consumption details: Console overview You can see the current balance, total usage, API request count, and per-model call trends: Dashboard ## Try it without writing code The **Chat** tab at the top of the console has a built-in playground — pick a model, send messages, and refine your prompt as you chat: Playground ## Next steps * Test models in your browser with the [Playground](https://aicentos.com/playground) — no code needed * Browse [supported models](https://docs.aicentos.com/en/billing/models-list) — see which LLMs are available * Read [error handling](https://docs.aicentos.com/en/billing/errors) — troubleshoot 401s, insufficient balance and more * Learn about [billing](https://docs.aicentos.com/en/billing/pricing) — pay-as-you-go billing and balance alerts --- # Model status monitor Source: https://docs.aicentos.com/en/status Language: en > Check availability, latency and endpoint PING for every model in real time The live monitor panel is currently available on the [Chinese status page](https://docs.aicentos.com/status) only. --- # Veo Video Generation Source: https://docs.aicentos.com/en/veo-video Language: en > Call Google Veo video generation models via aicentos — text-to-video, image-to-video, first/last frames, reference images This guide is for developers: how to call Google Veo video generation models through aicentos. The API follows the OpenAI Videos API compatible format — use the `openai` channel type when integrating downstream. ## Model capabilities Billing is based on video generation duration in seconds. See the aicentos console for exact unit prices; the final charge is based on the system's actual billing records. ### Official capabilities vs. what aicentos exposes | Model | Supported durations | Supported resolutions | Aspect ratios | Audio | Notes | | ------------------------------- | ------------------- | --------------------- | ------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | `veo-3.1-generate-preview` | 4, 6, 8 | 720p, 1080p, 4k | 16:9, 9:16 | Native audio | 1080p and 4k support 8 seconds only; 8 seconds is recommended when using image features such as reference images or first/last frames. | | `veo-3.1-fast-generate-preview` | 4, 6, 8 | 720p, 1080p, 4k | 16:9, 9:16 | Native audio | 1080p and 4k support 8 seconds only; 8 seconds is recommended when using image features such as reference images or first/last frames. | Reference docs: * [Google Gemini API Veo video generation](https://ai.google.dev/gemini-api/video) * [Veo reference images](https://ai.google.dev/gemini-api/video#reference_images) * [Veo first and last frames](https://ai.google.dev/gemini-api/video#first_and_last_frame) * [Veo aspect ratio](https://ai.google.dev/gemini-api/video#aspect_ratio) ### Aspect ratio | Model | 16:9 landscape | 9:16 portrait | Default | Recommendations | | ------------------------------- | -------------- | ------------- | ------- | ------------------------------------------------------------ | | `veo-3.1-generate-preview` | Supported | Supported | 16:9 | 4K requires 8 seconds; video extension is not yet available. | | `veo-3.1-fast-generate-preview` | Supported | Supported | 16:9 | 4K requires 8 seconds; video extension is not yet available. | Set the aspect ratio via `metadata.aspectRatio` in JSON or the `aspectRatio` form field: ```bash { "metadata": { "aspectRatio": "9:16" } } ``` If `aspectRatio` is not passed explicitly, the system derives it from `size` first — for example, `1280x720` maps to 16:9 and `720x1280` to 9:16. If `size` is missing too, the upstream defaults to 16:9. ### Audio | Model | Official audio capability | generateAudio support | Recommendation | | ------------------------------- | ------------------------- | --------------------- | ---------------------------------------------------------------------- | | `veo-3.1-generate-preview` | Native audio | Not supported | Do not pass `generateAudio`; describe any sound effects in the prompt. | | `veo-3.1-fast-generate-preview` | Native audio | Not supported | Do not pass `generateAudio`; describe any sound effects in the prompt. | The Veo 3.1 series generates audio natively, but the current Gemini API Veo parameter list does not expose `generateAudio` as a controllable parameter. Passing it may cause the upstream to return `INVALID_ARGUMENT`. To control the audio, describe the dialogue, ambient sound, sound effects or music style in the prompt, for example: ```bash A lighthouse by the sea at dusk, waves gently lapping the rocks, low wind and distant seabirds, cinematic lighting, stable camera movement ``` ## Image input capabilities | Capability | Official Google Veo | aicentos API support | Notes | | -------------------------------------- | ----------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Single initial image to video | Supported | Supported | Upload 1 image via `input_reference` as the video's starting frame. | | First/last frame / frame interpolation | Veo 3.1 series supports image + lastFrame | Supported | First frame via `input_reference`, last frame via `last_frame` or `lastFrame`. Veo 3.1 series and 8 seconds recommended. | | Multiple reference images | Veo 3.1 series supports up to 3 referenceImages | Supported | Upload via `reference_image`, `reference_images` or `referenceImages`; `referenceType` only supports `asset`. 8 seconds recommended. | | Video extension | Veo 3.1 / Fast can extend existing Veo videos | Not yet supported | The current aicentos API does not expose official video input. | * Image MIME types supported: `image/jpeg`, `image/png`, `image/webp`. Send a file or Base64; remote image URLs are not recommended. * Reference-image note: the upstream does not support `negativePrompt` in the reference-image scenario and may return `Negative prompt is not supported in your use case`. Do not pass `negativePrompt` with reference-image requests. * Implementation note: the Gemini API Veo `predictLongRunning` image input uses `bytesBase64Encoded` + `mimeType`, not the `inlineData` used by plain `generateContent`. aicentos converts multipart-uploaded images into the format the upstream expects. ## Billing rules * Billed by video generation duration in seconds. Use one of the durations each model supports (see the table above); arbitrary values are not recommended. * If the request does not specify a duration, billing defaults to 8 seconds. * Duration resolution order: `metadata.durationSeconds` > `duration` > `seconds` > default 8 seconds. * Resolution detection order: `metadata.resolution` > `size` > default 720p. * 720p / 1080p / 4K are billed under the same rules; there is no separate resolution surcharge. * `aspectRatio` only controls landscape vs. portrait; it does not change the price. * 4K supports 8 seconds only. * See the aicentos console for exact unit prices. ## API endpoints These 3 endpoints are recommended: | Purpose | Method | Path | | --------------- | ------ | ------------------------------ | | Create task | POST | `/v1/videos` | | Check status | GET | `/v1/videos/{task_id}` | | Download result | GET | `/v1/videos/{task_id}/content` | To get the result URL directly from the status query, you can also use: | Purpose | Method | Path | | ------------------------------- | ------ | --------------------------------- | | Check status and get result URL | GET | `/v1/video/generations/{task_id}` | ### Authentication ```bash export BASE_URL="https://aicentos.com" export AICENTOS_API_KEY="sk-xxxxxx" ``` All requests include: ```bash -H "Authorization: Bearer $AICENTOS_API_KEY" ``` ### Create a text-to-video task ```bash curl -X POST "$BASE_URL/v1/videos" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "veo-3.1-generate-preview", "prompt": "A lighthouse by the sea at dusk, slow push-in shot, waves gently lapping the rocks, cinematic lighting, stable camera movement", "seconds": "8", "size": "1280x720", "metadata": { "negativePrompt": "blurry, watermark, distorted, low quality", "resolution": "720p", "aspectRatio": "16:9", "seed": 20260401 } }' ``` Typical response: ```bash { "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "object": "video", "model": "veo-3.1-generate-preview", "status": "queued", "progress": 0, "created_at": 1775025000 } ``` ### Create an image-to-video task (first frame) For image-to-video, `multipart/form-data` is recommended, and the first-frame image field must be named `input_reference`. ```bash curl -X POST "$BASE_URL/v1/videos" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -H "Accept: application/json" \ -F "model=veo-3.1-generate-preview" \ -F "prompt=The girl in the frame turns her head toward the camera, a light breeze moves her hair, city lights in the background softly blurred, smooth steady push-in" \ -F "input_reference=@./first-frame.png;type=image/png" \ -F "seconds=8" \ -F "size=1280x720" \ -F "resolution=720p" \ -F "aspectRatio=16:9" \ -F "negativePrompt=blurry, watermark, deformed hands" \ -F "seed=20260401" ``` ### Create a first/last frame task First/last frame tasks require both frames: first frame via `input_reference`, last frame via `last_frame` or `lastFrame`. ```bash curl -X POST "$BASE_URL/v1/videos" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -H "Accept: application/json" \ -F "model=veo-3.1-generate-preview" \ -F "prompt=Transition naturally from the first frame with a girl to the last frame with a boy, smooth steady push-in, blurred city lights, hair and clothes moving slightly in the breeze, a natural and realistic transition" \ -F "input_reference=@./first-frame.png;type=image/png" \ -F "last_frame=@./last-frame.png;type=image/png" \ -F "seconds=8" \ -F "size=1280x720" \ -F "resolution=720p" \ -F "aspectRatio=16:9" \ -F "negativePrompt=blurry, watermark, distorted face, deformed hands" \ -F "seed=20260402" ``` ### Create a reference-image task Reference-image tasks are supported on the Veo 3.1 series only, up to 3 images, with `referenceType` limited to `asset`. Field names: `reference_image`, `reference_images` or `referenceImages`. Do not pass `negativePrompt` on reference-image tasks. ```bash curl -X POST "$BASE_URL/v1/videos" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -H "Accept: application/json" \ -F "model=veo-3.1-generate-preview" \ -F "prompt=Follow the characters' appearance from the two images and the night-city atmosphere to generate a cinematic two-person street shot, smooth steady push-in, background lights softly blurred, the characters looking naturally at the camera" \ -F "reference_image=@./ref-1.png;type=image/png" \ -F "reference_image=@./ref-2.png;type=image/png" \ -F "reference_type=asset" \ -F "seconds=8" \ -F "size=1280x720" \ -F "resolution=720p" \ -F "aspectRatio=16:9" \ -F "seed=20260403" ``` JSON / Base64 is also supported: ```bash { "model": "veo-3.1-generate-preview", "prompt": "Generate an ad shot using the product appearance from the reference images", "duration": 8, "metadata": { "resolution": "720p", "aspectRatio": "16:9", "referenceImages": [ { "image": { "bytesBase64Encoded": "BASE64_IMAGE", "mimeType": "image/png" }, "referenceType": "asset" } ] } } ``` ### Check task status First save the `id` or `task_id` returned by the create endpoint: ```bash export TASK_ID="task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ``` Then check the status: ```bash curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \ -H "Authorization: Bearer $AICENTOS_API_KEY" ``` While in progress, a typical response: ```bash { "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "object": "video", "model": "veo-3.1-generate-preview", "status": "in_progress", "progress": 50, "created_at": 1775025000 } ``` When complete, a typical response: ```bash { "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "object": "video", "model": "veo-3.1-generate-preview", "status": "completed", "progress": 100, "created_at": 1775025000, "completed_at": 1775025068 } ``` ### Check task status and get the result URL To get a downloadable URL directly from the status query, call: ```bash curl -X GET "$BASE_URL/v1/video/generations/$TASK_ID" \ -H "Authorization: Bearer $AICENTOS_API_KEY" ``` Typical response: ```bash { "code": "success", "message": "", "data": { "error": null, "format": "mp4", "metadata": null, "status": "succeeded", "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "url": "https://aicentos.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content" } } ``` ### Download the video Once the task completes, download directly: ```bash curl -L "$BASE_URL/v1/videos/$TASK_ID/content" \ -H "Authorization: Bearer $AICENTOS_API_KEY" \ -o veo-result.mp4 ``` ## Status values `GET /v1/videos/{task_id}` mainly returns these statuses: | Status | Meaning | | ------------- | ---------- | | `queued` | Queued | | `in_progress` | Generating | | `completed` | Completed | | `failed` | Failed | `GET /v1/video/generations/{task_id}` mainly returns these statuses: | Status | Meaning | | ------------ | ---------- | | `queued` | Queued | | `processing` | Generating | | `succeeded` | Succeeded | | `failed` | Failed | ## Integration notes * `prompt` is required. * For image-to-video, the image field must be named `input_reference`. * First/last frame tasks require both frames: first frame via `input_reference`, last frame via `last_frame` or `lastFrame`. * Reference-image tasks are supported on the Veo 3.1 series only, up to 3 images, and must use 8 seconds. * Do not pass `negativePrompt` on reference-image tasks. * For Gemini image-to-video, remote image URLs are not recommended; send a file or Base64. * Poll `GET /v1/videos/{task_id}` and download only after `status=completed`. * The Veo 3.1 series accepts 4, 6 or 8 seconds; 1080p and 4k require 8 seconds. Use `aspectRatio=16:9` for landscape and `aspectRatio=9:16` for portrait; if omitted, 16:9 is assumed. * Do not pass `generateAudio`. The Veo 3.1 series generates audio natively, but the current Gemini API does not support toggling audio via `generateAudio`; passing it may cause the upstream to return `INVALID_ARGUMENT`. * To control the audio, describe the dialogue, ambient sound, sound effects or music style in the prompt. * Official Veo 3.1 supports video extension, but the current aicentos API does not yet expose official video input.