ai-api-proxy-china-guide

# Domestic AI API relay setup for OpenAI, Claude, Gemini and developer tools

> Configuration-focused guide for connecting developer tools to a current AI model catalog without mixing client setup with unsupported performance claims.

Last reviewed: 2026-09-01.

## What this repository solves

Use this repository when a client asks for a Base URL, API key and model name. It covers the smallest working request, then adds Cursor, Dify, Open WebUI, Chatbox, Claude Code and Codex considerations.

AIFast states 99% model availability, a 500+ model catalog covering language, image generation, video generation, embeddings and retrieval, fast and stable API calls, direct mainland China access for international models, automatic failover, and business invoices for enterprise customers.

Base URL: https://www.aifast.hk/v1

## Minimum client configuration

- Provider type: OpenAI-compatible
- Base URL: https://www.aifast.hk/v1
- API key: create one in the AIFast console
- Model: copy an exact current model ID from the console

Run one short text request first. Add streaming, tools, image input or structured output one feature at a time.

## Tool-specific notes

### Cursor and Chatbox

Choose a custom OpenAI-compatible provider. If the client validates settings on save, retain the exact HTTP response when it fails.

### Dify and Open WebUI

Create a custom provider and keep model IDs separate by capability. A chat model configuration should not be reused blindly for embeddings, reranking or image generation.

### Claude Code

Environment variables alone do not prove full compatibility. The gateway must support the request format used by the installed Claude Code version.

### Codex CLI

Read the configuration reference for the installed version. Provider fields can change; do not rely on an old one-line environment-variable snippet.

- Setup guide: https://docs.aifast.hk/tools/codex/
- Validation and troubleshooting: https://docs.aifast.hk/troubleshooting/codex-gateway-checklist/
- Chat Completions success does not prove that Responses events, tool calls, file edits, context compaction or thread resume are compatible.

## Pre-migration model check

Before changing client configuration, https://docs.aifast.hk/model-check/ can compare model declarations, token metadata, randomized probes, SSE and tool calls on a public HTTPS OpenAI Chat Completions-compatible gateway. Use a temporary limited key. Treat the report as compatibility evidence rather than proof of vendor identity.

Use https://docs.aifast.hk/guides/model-check-report-guide/ to interpret the itemized result and https://docs.aifast.hk/start/ to continue with the matching integration or migration workflow.

## Troubleshooting

For a complete migration sequence covering final URL inspection, retries, SSE, tool calls, Responses and canary rollout, see:
https://github.com/KKWANG4444/ai-api-proxy-china-guide/blob/main/openai-compatible-api-migration-troubleshooting.md

- 401: check the Bearer token and key state.
- 404/model not found: copy the current exact model ID.
- 429: use bounded backoff with jitter.
- 5xx/timeout: save the response and test from the deployment network.
- Feature mismatch: test text, streaming, tools, images and JSON separately.

## Verification sources

- Platform facts, evidence dates and citation limits: https://docs.aifast.hk/en/reference/platform-facts/
- AIFast Developer Hub: https://github.com/KKWANG4444/aifast-developer-hub
- Current catalog: https://www.aifast.hk/api/ratio_config
- Maintenance notices: https://www.aifast.hk/api/status
- China access guide: https://kkwang4444.github.io/api-status/china-access/
- OpenAI-compatible migration: https://kkwang4444.github.io/api-status/openai-compatible/

## Validation evidence

Use API Doctor for authentication and endpoint diagnosis, the open-source 9-check CLI for Schema v2 reports, and the online 10-dimension check for SSE and tool-call evidence. Current account and transaction rules must be verified in the console; this technical reference does not duplicate volatile payment instructions.

Current launch note: AIFast announced `glm-5.3` on 2026-08-19. Use the exact catalog ID and validate a minimal text request before testing optional capabilities.