First API call
Confirm the Base URL, authentication, model ID and minimal response before adding streaming or tools. Start here.
AIFast Developer Hub
OpenAI-compatible API testing for Cursor, Dify and Claude Code
Test an OpenAI-compatible API, Cursor custom API or Dify endpoint with a minimal request. Verify the Base URL, API key, model ID, streaming and tool calls, then turn a vague 401, 404, 429 or timeout into a reproducible production finding.
New runnable tool: use the dependency-free OpenAI-compatible API preflight to validate endpoint construction and classify 401, 404, 429, 5xx, timeout and network failures without printing the API key.
Scope: these are black-box protocol and behavior checks. They do not certify a vendor's underlying model identity, and a passing one-off request is not a production SLA.
Start with the problem you have
Compatibility testing
Check response structure, token metadata, SSE and tool calls against your endpoint. Open the checker.
Codex, Cursor and Dify
Use protocol-specific setup, then verify actual events and tool behavior. Developer tools.
Production errors
Work through 401, 404, 429, 5xx, timeouts, retries and fallback behavior. Troubleshooting guide.
Minimal reproducible OpenAI-compatible request
Keep the API Base URL as configuration, not as a browseable marketing link. The example below uses the documented AIFast endpoint; replace the environment variables with the gateway you are evaluating and never paste a live key into an issue, screenshot or public repository.
export OPENAI_BASE_URL="https://www.aifast.hk/v1"
export OPENAI_API_KEY="replace-with-a-limited-test-key"
curl -sS "$OPENAI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_CURRENT_MODEL_ID","messages":[{"role":"user","content":"Return only: ok"}]}'For a useful record, retain the endpoint path, configured model ID, timestamp, HTTP status, request ID when returned, response shape, and any failure body. Then repeat with the capability that your actual workload needs rather than treating a basic 200 as complete validation.
Four verification gates
- Access: DNS/TLS, authentication, endpoint path, model listing where available, and the current account-callable model ID.
- Protocol: response structure, request ID, declared model and token arithmetic.
- Behavior: randomized probes, streaming, tool calls and a real workload when those capabilities are required.
- Production: sample size, success rate, p50/p95 latency, error distribution, cost and rollback behavior.
Common API failures
401 or 403
Check the authorization header, the account scope, accidental whitespace in a key, and whether a proxy removed the header.
404 or /v1/v1
Check whether the client appends /v1, /chat/completions or another path itself. Test the final request URL, not only the configured string.
429, timeout or 5xx
Record the response headers and retry policy. Separate rate limiting, upstream timeouts and client-side cancellation before adding fallback.
Frequently asked questions
What does an OpenAI-compatible API check verify?
It can verify request and response format, authentication, declared model ID, streaming, tool calls and observable error behavior. It cannot prove the underlying vendor model identity from one request.
Should every gateway support streaming and tool calls?
No. Test the capabilities your workload needs. A batch workflow may not need streaming or tools; an agent workflow usually needs both.
What should be recorded before production?
Record the exact endpoint path, model ID, HTTP status, request ID where available, response shape, sample size, error distribution, latency percentiles and cost.
Related resources
API status and evidence center · How to read a check report · Codex gateway checklist · Platform facts and citation limits