1. What “OpenAI-compatible” does and does not mean
Compatibility gives applications a common starting shape: a bearer key, a base URL and familiar request objects. It does not make GPT, Claude, Gemini, Grok or Chinese models interchangeable. Each family can differ in context, reasoning controls, tool schemas, image inputs, streaming events, output fields and rate limits.
Keep the common transport layer small and put model-specific behavior in a capability table. This makes a provider change measurable instead of turning every error into a network mystery. The Chinese OpenAI-compatible API guide contains a shorter onboarding path; this English page focuses on production boundaries and relay selection.
2. Setup in five steps
- Register or sign in and create an API key for the project.
- Set the base URL to
https://www.codex789.com/v1. - Send the key as
Authorization: Bearer ...; never commit it to a repository. - Copy the exact model ID from the current catalog or control panel.
- Run a short request, save the raw response and record the billing event.
Do not append a provider-native path to the compatible base URL unless the current access instructions explicitly require it. A double /v1 or a guessed model alias is one of the most common causes of false “relay down” reports.
3. Chat completion smoke test
curl https://www.codex789.com/v1/chat/completions \
-H "Authorization: Bearer $CODEX789_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-sol",
"messages": [{"role": "user", "content": "Return a JSON object with status=ok."}],
"temperature": 0.2
}'Replace the example with a model ID enabled for your key. Once this passes, test streaming, tools, image content and long context as separate cases. A successful text request does not prove that a media endpoint or native provider parameter is available.
4. Model-family boundaries
| Family | Useful entry point | Verify separately |
|---|---|---|
| GPT | Text, code and image workflows | Image fields, response shape and tool support |
| Claude | Long-form reasoning and code | Message format, thinking blocks and cache behavior |
| Gemini | Multimodal and long-context tasks | Image format, context limits and 429 windows |
| Grok | Text, reasoning and enabled media channels | Exact model ID, tools, SSE and media permissions |
| Chinese models | DeepSeek, Qwen, GLM, Kimi and MiniMax | Model alias, Chinese output, fallback and quota |
Use the dedicated Grok relay guide, Gemini relay guide and Chinese LLM relay guide when a task depends on a family-specific field.
5. Error matrix
| Signal | Check first | Safe next step |
|---|---|---|
| 401 | Key, host and Authorization header | Replay with a newly verified key and no optional fields |
| 403 | Model or feature permission | Check account group and exact model ID |
| 404 | Path, version or model alias | Compare the base URL and catalog entry character by character |
| 400 | Payload shape or unsupported parameter | Remove optional fields and add them back one at a time |
| 429 | Request, token or concurrency window | Use bounded backoff and lower concurrency |
| 5xx / timeout | Relay or upstream capacity | Persist request evidence and reconcile before retrying |
A client should report the status code, request ID and model ID without leaking the API key. For model-specific cases, use the GPT API guide, Gemini guide or Grok guide.
6. Price and usage ledger
A compatible interface does not imply a common price unit. Text models usually separate input and output tokens; image models may charge per image; video models may charge by time or successful task. Use the unit shown for the selected model and do not multiply an unrelated provider's price.
Track model ID, input/output size, cache state when exposed, retries, status code and accepted-output decision. The public pricing page is a reference; final availability and charge are read from the logged-in control panel. Compare cost per accepted task rather than cost per HTTP 200.
7. Production checklist
- Give each environment its own key, spend limit and alert.
- Pin a primary model and a tested fallback per task contract.
- Keep a capability matrix for tools, images, streaming and context.
- Use idempotency keys for uncertain create operations.
- Separate generation failure, download failure and content-review rejection.
- Log requested and actual model IDs, latency, status class and retry reason.
- Never use an LLM to choose a route that ordinary configuration already determines.
When a fallback lacks a required capability, fail loudly with an actionable message. Silent degradation produces the most expensive kind of “successful” response: one that cannot be used.
8. Frequently asked questions
Can I switch models by changing only the model field?
Sometimes, for a compatible text request. You still need to test the new model's fields, limits, output shape and billing before production.
Is the relay an official provider endpoint?
No. It is the island AI Coding access and billing layer. Model availability and permissions come from the current control panel.
Can one API key call every model?
Do not assume so. Key groups, model permissions and media access can differ. Verify the model list available to the key.
Where should I start?
Start with this smoke test, then choose a family-specific guide: Grok, Gemini or Chinese LLMs. For Seedance video, use its separate sub-site guide.
Reviewed September 27, 2026. Supported models, fields, prices and limits remain subject to the current control panel.