Welcome to BeeHears Integration Docs
This page provides installation and usage tutorials for mainstream AI programming tools to help you quickly get started with various AI-assisted development tools. All tutorials support Windows, macOS, and Linux platforms.
Claude Code
Anthropic
Official AI coding assistant from Anthropic, supporting terminal interaction, code analysis, Git workflows, and more powerful features.
Codex CLI & App
OpenAI
Coding agent tool from OpenAI that can read, modify, and run code, supporting multiple model choices.
Gemini CLI
Official Gemini command-line tool from Google, supporting code assistance, file operations, and multiple installation methods.
Opencode
Open Source Community
Open-source AI coding agent, supporting terminal interface, desktop application, and IDE extension usage modes.
OpenClaw
Open Source Community
Powerful AI automation agent platform, supporting multi-channel message integration and rich tool extensions.
Hermes Agent
Nous Research
AI agent with learning capabilities, able to accumulate skills from execution experience and autonomously optimize its abilities.
AionUi
Open Source
Free open-source desktop Cowork client with multi-model agents, file management, and live preview.
AQBot
Open Source
Local-first desktop AI workstation with multi-provider chat, ACP Agent, and one-click aqbot:// import.
CC Switch
Open Source
Unified AI CLI manager with one-click fill for Claude / Codex / Gemini providers and models.
Cherry Studio
Cherry AI
Powerful desktop AI client with 30+ built-in assistants and multi-model conversations.
DeepChat
Open Source
Full-featured open-source AI Agent client with MCP, Skills, ACP, and remote control.
Memoh
Open Source
Containerized AI agent platform with long-term memory and multi-channel bots.
Fluent Read
Open Source
AI-powered smart reading and translation browser extension.
LangBot
Open Source
IM chatbot platform with multi-channel bots, knowledge base, Agent, and MCP.
Luna Translator
Open Source
Open-source real-time translator for games and documents.
AstrBot
Open Source
One-stop open-source Agent chatbot platform for QQ, Feishu, DingTalk, WeCom, and more.
Factory Droid CLI
Factory AI
CLI AI software-engineering agent for building, debugging, and refactoring code.
Image API (gpt-image-2)
Sync Image Generation · Stable
Synchronous text-to-image /v1/images/generations and image-to-image /v1/images/edits guide, covering gpt-image-2, response handling (b64_json / URL), output formats and pitfalls.
BytePlus Seedance 2.0
ByteDance · Video Generation (Stable)
Integration guide for BytePlus Dreamina Seedance 2.0 / 2.0 Fast video generation, covering OpenAI-style /v1/videos and VolcArk native task APIs, asset references, billing and FAQs.
📌 Usage Tips
When using these AI programming tools, you need an API key to access the corresponding model services. BeeHears provides a unified API access service supporting all the tools above. You can:
- Get your API key from the BeeHears console
- Configure the API Base URL to the address provided by BeeHears
- Enjoy unified billing and multi-model switching capabilities
🔍 Connectivity Self-check
When you encounter "no response / errors / hanging", please run the following checks before submitting a ticket. These three steps locate 90% of the issues.
Step 1: Verify endpoint matches the model
Different model families use different endpoints. A mismatch produces the misleading symptom of HTTP 200 with an empty response body (this is not a service outage—it's the wrong endpoint).
| Model Family | Correct Endpoint | Typical Models |
|---|---|---|
| Claude family | /v1/messages |
claude-opus-5-5, claude-fable-5-1, claude-sonnet-5, claude-haiku-4-5-20251001 |
| Codex / Reasoning | /v1/responses |
gpt-6-astra, gpt-6-sol, gpt-5.6-sol, gpt-5.3-codex and other reasoning models |
| General GPT | /v1/chat/completions |
gpt-5.5, gpt-5.4-mini, gpt-5.4-nano and other general-purpose gpt-5.x |
| List available models | /v1/models |
Doesn't consume tokens. Call this first to verify your key and network. |
Codex / reasoning models must use /v1/responses. Calling them via /v1/messages returns HTTP 200 with an empty SSE stream—the client appears to "hang with no reply". This is not a service bug; just switch to the correct endpoint.
Step 2: Test connectivity with a minimal request
Replace YOUR_KEY in the examples with your API key (starts with sk-).
① Verify key + network (no quota usage)
curl -sS -i https://ai.beehears.com/v1/models \
-H "Authorization: Bearer YOUR_KEY" | head -20Seeing HTTP/2 200 + JSON model list → connectivity is OK.
② Test Claude (/v1/messages)
curl -sS https://ai.beehears.com/v1/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-haiku-4-5-20251001",
"max_tokens": 32,
"messages": [{"role":"user","content":"Reply only: ok"}]
}'③ Test Codex / reasoning (/v1/responses)
curl -sS https://ai.beehears.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_KEY" \
-d '{"model":"gpt-6-sol","input":"Reply only: ok"}'④ Test general GPT (/v1/chat/completions)
curl -sS https://ai.beehears.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_KEY" \
-d '{
"model": "gpt-5.5",
"max_tokens": 512,
"messages": [{"role":"user","content":"Reply only: ok"}]
}'⑤ Capture request-id (required for tickets)
curl -sS -i https://ai.beehears.com/v1/models \
-H "Authorization: Bearer YOUR_KEY" | grep -i "x-oneapi-request-id\|HTTP/"The x-oneapi-request-id response header is the unique key for log lookup. Always include it when submitting a support ticket.
In Windows PowerShell, curl is an alias of Invoke-WebRequest with completely different parameters. You must write curl.exe (with the suffix) to invoke the real curl. Storing the request body in a file avoids quoting/escaping headaches entirely.
① Verify key (no quota usage)
curl.exe -sS -i https://ai.beehears.com/v1/models -H "Authorization: Bearer YOUR_KEY"② Prepare request body file body.json
{
"model": "gpt-5.5",
"max_tokens": 512,
"messages": [{"role":"user","content":"Reply only: ok"}]
}③ Send the test request
curl.exe -sS -i https://ai.beehears.com/v1/chat/completions ^
-H "Authorization: Bearer YOUR_KEY" ^
-H "Content-Type: application/json" ^
-d "@body.json"For Claude, change the URL to /v1/messages and add -H "anthropic-version: 2023-06-01". For Codex, change the URL to /v1/responses and use a body like {"model":"gpt-6-sol","input":"ok"}.
The continuation character is backtick ` in PowerShell and ^ in CMD. If the command fits on one line, just write it on one line—no continuation needed.
Use the native PowerShell cmdlets Invoke-RestMethod / Invoke-WebRequest to avoid JSON quote escaping.
① Verify key (no quota usage)
$headers = @{
"Authorization" = "Bearer YOUR_KEY"
"Content-Type" = "application/json"
}
Invoke-RestMethod -Uri "https://ai.beehears.com/v1/models" -Headers $headers | Select-Object -First 5② Test Claude
$h = @{
"Authorization" = "Bearer YOUR_KEY"
"Content-Type" = "application/json"
"anthropic-version" = "2023-06-01"
}
$body = @{
model = "claude-haiku-4-5-20251001"
max_tokens = 32
messages = @(@{ role = "user"; content = "Reply only: ok" })
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Uri "https://ai.beehears.com/v1/messages" `
-Method POST -Headers $h -Body $body③ Test Codex
$body = @{ model = "gpt-6-sol"; input = "Reply only: ok" } | ConvertTo-Json
Invoke-RestMethod -Uri "https://ai.beehears.com/v1/responses" `
-Method POST -Headers $headers -Body $body④ Capture request-id
$resp = Invoke-WebRequest -Uri "https://ai.beehears.com/v1/models" -Headers $headers
$resp.StatusCode
$resp.Headers["x-oneapi-request-id"]In PowerShell, curl is an alias of Invoke-WebRequest with a completely different parameter syntax than Linux's curl. To use Linux-style commands, explicitly invoke curl.exe.
📋 Error Code Reference
The HTTP status code returned by the API quickly attributes the problem (client / gateway / upstream).
| Status | Meaning | Common Causes | Suggested Action |
|---|---|---|---|
| 200 | Success | Normal response; if body is empty / SSE has no data → wrong endpoint | Check the endpoint that matches your model (see table above) |
| 400 | Bad request | Invalid JSON, missing required fields, misspelled model name, parameter out of range (e.g. max_tokens too large) | Re-check the request body; validate with Postman or an online JSON linter |
| 401 | Unauthorized | API key missing / mistyped / disabled; missing space between Bearer and the key |
Check the Authorization: Bearer sk-xxx format; verify the key status in the console |
| 403 | Forbidden | Key has no access to this model / group; the model is not enabled in your subscription | Check group permissions in the console; contact support to enable the model |
| 404 | Path or model not found | URL typo (e.g. /v1/message missing the s); model not in your available list |
Call /v1/models first to see available models; double-check the URL spelling |
| 413 | Request body too large | prompt or input exceeds the model's context window | Shorten the input; chunk the work; switch to a larger-context model |
| 429 | Rate limited / quota exhausted | QPS exceeded; account balance / subscription quota used up | Reduce concurrency and retry; check quota in the console; contact support if it persists |
| 500 | Upstream internal error | Upstream model service issue (OpenAI / Anthropic etc.) | Wait 30s and retry; if it keeps failing, submit a ticket with the request-id |
| 502 | Bad gateway | Gateway-to-upstream link issue; upstream temporarily unreachable | Wait 1 minute and retry; submit a ticket with the request-id if it persists |
| 503 | Service unavailable | Upstream overloaded / under maintenance; gateway being upgraded | Wait 1–5 minutes and retry; check the BeeHears status announcements |
| 504 | Gateway timeout | Upstream is slow and exceeds the gateway timeout; long prompt causes high time-to-first-byte | Shorten the input; enable streaming (stream: true); use off-peak hours |
| No response / hangs | Connection / DNS / TLS issue | Local network problem; DNS pollution; CDN link instability; system clock skew breaking TLS | ping ai.beehears.com; switch network; sync your system clock |
4xx (400/401/403/404/413/429) is usually a client-side issue you can fix by reviewing the request. 5xx (500/502/503/504) is usually an upstream or gateway issue—submit a ticket with the request-id.
📨 Issue Report Template
When submitting a ticket, please provide the information below. Including x-oneapi-request-id reduces the lookup time from minutes to seconds.
Site: https://ai.beehears.com
Time (UTC+8): 2026-05-04 21:49:54
Model: <gpt-6-sol>
Endpoint: </v1/messages>
HTTP status: <200>
Symptom: <empty body / verbatim error message>
x-oneapi-request-id: <202605041349543194049748268d9d6eNttclRU>
Full command (mask the key as sk-***):
<paste your curl / PowerShell command>Option 1: Add -i to curl to print all response headers.
Option 2: In PowerShell with Invoke-WebRequest, read $resp.Headers["x-oneapi-request-id"].
Option 3: Browser / Postman — find it in the Headers tab of the response panel.
Support has to dig through large volumes of logs using only the timestamp and user ID, which can take 10–30 minutes and may miss the exact entry. With a request-id, lookup is near-instant.