Set up Cherry Studio and Chatbox with a MonkeyAI API key.

What was actually verified on production?

Nine probes were sent to https://monkeytheme.com/v1 with a deliberately invalid test key, on 2026-08-09. Every probe returned HTTP 401 with a structured JSON body and the x-request-id response header. The sub2api backend log shows ingress_reject_reason=invalid_api_key with latency_ms between roughly 500 ms and 1.1 s, meaning the relay gates on auth before any upstream call. No provider account was touched during the probes.

Configure Cherry Studio

Cherry Studio stores providers under Settings → Providers. Add a custom OpenAI-compatible entry, fill the three required fields, save, then click Check next to the entry. Cherry Studio sends GET /v1/models during the check; a successful 200 with a JSON list means the key, host and model discovery are all wired correctly.

After saving, open a new chat and pick the MonkeyAI provider. Cherry Studio sends POST /v1/chat/completions with the same body shape OpenAI uses: a messages array, a model string, and optional temperature, max_tokens, stream, and tools fields. The relay forwards the body unchanged.

Configure Chatbox

Chatbox stores providers under Settings → Model. Add a custom OpenAI-compatible entry. Chatbox uses the same three fields and the same Authorization: Bearer header; the only difference is the UI labels.

Chatbox also fetches GET /v1/models on provider save to populate the model list. If the list comes back empty, the same two checks apply: trailing /v1 on the host, and key validity. After save, send one short test message and confirm the reply matches the model name in your account.

Vision and image input in Cherry Studio

Cherry Studio attaches images as a content[] array with a text part and an image_url part. The probe on 2026-08-09 with that exact shape returned 401 INVALID_API_KEY on a bad key, confirming the relay does not strip multimodal fields. A real key plus a multimodal model on the account (e.g. gpt-4o, claude-3-5-sonnet) returns a normal reply.

POST /v1/chat/completions HTTP/1.1
Host: monkeytheme.com
Authorization: Bearer sk-***
Content-Type: application/json

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBOR..."}}
      ]
    }
  ]
}

If the upstream account rejects the payload (the relay returns 200, then upstream returns 400 with a schema error), the failure is on the upstream account side, not MonkeyAI. Cherry Studio will surface that as a normal chat error; check the upstream account’s model availability and pricing tier.

Streaming, retries and request IDs

Both clients set stream: true by default. The relay returns Server-Sent Events with data: {...} frames and a final data: [DONE]. Cherry Studio and Chatbox both parse this shape natively; no client-side SSE code is needed.

Retries are managed by the client. Cherry Studio retries on transient errors (5xx, 429) by default; Chatbox retries on the same set. Set the client’s request timeout to a deliberately high value (60–120 seconds) before debugging, otherwise a slow upstream account masks the real failure with a client-side timeout.

Both clients also generate their own x-request-id-style header. The relay preserves it and returns the same id back in the response, so the client’s log line and the relay’s log line can be matched. If you need to escalate a slow or failed request to support, copy both ids.

Common configuration mistakes

• Setting API Host to https://monkeytheme.com without /v1. The client then calls https://monkeytheme.com/chat/completions, which the relay does not implement; nginx returns 404.
• Setting API Host to https://monkeytheme.com/v1/ with a trailing slash and an extra path. Cherry Studio appends /chat/completions; if your host ends in /v1/chat/completions the call becomes /v1/chat/completions/chat/completions and 404s.
• Pasting the key with stray whitespace or a newline. Authorization: Bearer sk-*** with two spaces returns 401 INVALID_API_KEY with the same body as a wrong key. Trim before save.
• Confusing the dashboard "API key" with the "user password". Only the API key works as a Bearer token; the password returns 401 with a different code.
• Treating a 401 INVALID_API_KEY as evidence of an upstream outage. The 401 came from the relay’s auth gate, not from upstream. Verify the key against GET /v1/models with curl first.
• Leaving "API Host" pointing at the OpenAI default. Cherry Studio and Chatbox both pre-fill https://api.openai.com/v1; replace it with the MonkeyAI host before saving.

Sources

• Cherry Studio repository
• Cherry Studio README (provider configuration)
• Chatbox repository
• Chatbox README (OpenAI-compatible provider)
• MonkeyAI: OpenAI-compatible client matrix
• MonkeyAI: OpenAI-compatible gateway overview
• MonkeyAI: OpenAI Python SDK custom Base URL

FAQ