DeepSeek V4 + Codex CLI: Fix API Integration Errors

Abstract

Codex CLI natively works with OpenAI‑style /v1/responses protocol, while most third‑party LLM platforms expose standard /v1/chat/completions endpoints. This protocol mismatch causes 404 errors if developers attempt direct integration with DeepSeek V4. Historical tutorials recommending wire_api = "chat" no longer function in current Codex releases. A translation bridge layer is mandatory to convert between Responses and Chat Completions schemas. This article walks through a complete six‑step deployment workflow built around LiteLLM, preserves official benchmark parameters and pricing data for DeepSeek V4, and explains configuration pitfalls. When working with multi‑model heterogeneous endpoints, developers may leverage an API gateway to unify request routing and protocol adaptation. 4sapi provides endpoint management capabilities that simplify multi‑provider testing in local development environments. Every command snippet, model specification and cost metric comes from real‑world validation.

1. Core Protocol Gap Between Codex CLI and Third‑Party LLM Platforms

The root obstacle stems from incompatible API schemas. Looking at codex‑rs/core/config‑schema.json within the open‑source Codex repository, the definition for wire_api accepts only one valid enum value: `responses`. This parameter tells Codex CLI which wire protocol the upstream provider implements. In older versions wire_api = "chat" was supported for Chat Compatibility mode, yet this branch has been fully removed from modern releases. Any guide referencing wire_api = "chat" is obsolete and will not work.

Codex CLI always sends requests toward /v1/responses. Most third‑party platforms including DeepSeek V4 implement the widely‑adopted /v1/chat/completions. No native /v1/responses endpoint exists on these services. Sending POST requests to /v1/responses returns 404 Not Found.

The table below demonstrates endpoint behaviour against 4sapi as the target upstream platform.

Directly assigning third‑party base URL into Codex CLI base_url field triggers automatic requests to the non‑existent /v1/responses route, resulting in guaranteed failure. A translation bridge is required to accept Codex‑formatted Responses traffic and translate payloads to Chat Completions for upstream inference.

2. DeepSeek V4 Model Variants, Specifications and Pricing

DeepSeek V4 provides three production‑ready model variants, documented within official API references. Key technical parameters are summarised below.

Pricing differentiates off‑peak and peak hours. Peak window is defined as UTC 01:00‑04:00 and 06:00‑10:00. Flash and vision‑exp share identical price tables. Pro variant costs approximately three times higher. All models support one‑million‑token context and 384 000 maximum output length. Flash delivers high concurrency at lower cost and suits most engineering tasks. Pro is reserved for large‑scale code refactoring and complex multi‑layer architecture work.

>
> Important naming note: Platform‑returned model identifiers carry deepseek/ prefix. When configuring local clients, developers must match exact IDs returned by the model‑list API; manual name editing causes runtime failures.

3. Six‑Step End‑to‑End Integration Workflow

The complete request flow runs: Codex CLI → LiteLLM translation bridge layer → 4sapi upstream model platform.

Step 1: Retrieve API Key and set environment variable

Fetch your API access key from platform console. Store credentials within environment variables instead of hard‑coding inside configuration files. LiteLLM supports reading secrets via OS environment.

export API_KEY="your‑platform‑api‑key‑here"

Step 2: Validate upstream endpoints and model identifiers

Verify available model list over HTTP request. Confirm that /v1/responses returns 404 to confirm bridge requirement.

# List DeepSeek‑related model IDs
curl -s "https://4sapi.com/v1/models" \
-H "Authorization: Bearer $API_KEY" | \
python3 -c "import sys,json;[print(m['id']) for m in json.load(sys.stdin)['data'] if 'deepseek' in m['id']]"

# Confirm /v1/responses returns 404
curl -s -o /dev/null -w "%{http_code}" -X POST "https://4sapi.com/v1/responses" \
-H "Authorization: Bearer $API_KEY" \
-H "Content‑Type: application/json" \
-d '{"model":"deepseek/deepseek‑v4‑flash","input":"hi"}'

Receiving 404 confirms you cannot skip the translation bridge.

Step 3: Configure LiteLLM bridge with protocol translation

The critical toggle is use_chat_completions_api: true. When enabled, LiteLLM converts incoming /responses format into standard /chat/completions requests toward upstream providers. Create litellm.yaml.

model_list:
  - model_name: deepseek‑v4‑flash
    model_params:
      model: openai/deepseek/deepseek‑v4‑flash
      api_base: https://4sapi.com/v1
      api_key: os.environ/API_KEY
      use_chat_completions_api: true

  - model_name: deepseek‑v4‑pro
    model_params:
      model: openai/deepseek/deepseek‑v4‑pro
      api_base: https://4sapi.com/v1
      api_key: os.environ/API_KEY
      use_chat_completions_api: true

Start LiteLLM local service instance:

litellm --config litellm.yaml --port 4000

Observe log message Uvicorn running on http://0.0.0.0:4000 to confirm successful startup.

Step 4: Validate bridge layer independently

Test bridge endpoint before touching Codex CLI configuration. Isolating validation helps separate bridge‑side bugs from Codex misconfiguration.

curl -s -X POST "http://127.0.0.1:4000/v1/responses" \
-H "Authorization: Bearer sk‑1234" \
-H "Content‑Type: application/json" \
-d '{"model":"deepseek‑v4‑flash","input":"Explain binary search in one sentence."}' | python3 -m json.tool

A healthy response returns HTTP 200, conforms to Responses schema: {"object":"response","status":"completed"}. The JSON payload includes usage block containing reasoning_tokens. DeepSeek V4 outputs reasoning tokens for internal thought steps, these tokens are also billed as output tokens during cost calculation.

Step 5: Configure Codex CLI config.toml

Edit ~/.codex/config.toml. Remember wire_api must equal `"responses"`. Setting wire_api = "chat" causes failure.

model = "deepseek‑v4‑flash"
model_provider = "litellm‑bridge"

[model_providers.litellm‑bridge]
name = "DeepSeek V4 via LiteLLM bridge"
base_url = "http://127.0.0.1:4000/v1"
env_key = "LITELLM_API_KEY"
wire_api = "responses"

Export environment variable matching env_key entry in config:

export LITELLM_API_KEY="sk‑1234"

Key configuration notes:

1. base_url must terminate with /v1. Codex appends /responses suffix automatically.
2. Credentials are injected via environment variables; never hard‑write secrets inside TOML files.
3. wire_api="responses" is the single permitted value for modern Codex CLI.

Step 6: Manage multiple‑model setups with profiles

Use Codex profile feature to maintain separate configurations for Flash and Pro without manual file edits.

[profiles.ds‑flash]
model = "deepseek‑v4‑flash"
model_provider = "litellm‑bridge"

[profiles.ds‑pro]
model = "deepseek‑v4‑pro"
model_provider = "litellm‑bridge"

Invoke target profile at runtime:

# Interactive chat mode
codex -p ds‑flash

# Non‑interactive one‑shot task
codex exec -p ds‑pro "Refactor this module and write unit tests"

For safe testing without polluting local home‑directory config, set temporary $CODEX_HOME:

CODEX_HOME=/tmp/codex‑test codex -p ds‑flash

4. Configuration‑layer caveats

Codex CLI treats model_providers as user‑scope configuration. These settings belong inside ~/.codex/config.toml. Avoid committing this file into shared source repositories. Secrets and provider endpoints are environment‑specific and must not be version‑controlled. Profiles can also reside in standalone files under $CODEX_HOME/<profile‑name>.config.toml.

5. Comparison of three integration approaches

>
> Note: The built‑in codex‑responses‑api‑proxy component inside Codex source repository strictly forwards POST /v1/responses traffic only toward official OpenAI endpoints. It cannot be repurposed for generic third‑party model services.

6. Cost‑optimisation advice after successful integration

Three actionable practices reduce inference spend with DeepSeek V4 on this stack.

1. Prioritise deepseek‑v4‑flash for most daily tasks. Flash provides identical context window and maximum output length versus Pro, delivers 2500‑way concurrency, while costing around one‑third of Pro pricing. Reserve Pro for heavy refactoring and architecture‑level design assignments.
2. Leverage cached‑input pricing. Cache‑hit input token cost is far cheaper than cache‑miss cost. Group related work into single continuous sessions to maximise cache reuse. Avoid spawning frequent short‑lived independent sessions.
3. Schedule large batch jobs to off‑peak hours. Official peak window maps roughly to morning and afternoon Beijing local hours. Schedule non‑urgent heavy workloads outside peak UTC windows to take advantage of discounted off‑peak rates.

Always include reasoning_tokens in cost estimation. DeepSeek V4 deducts reasoning tokens against output‑token quota. Ignoring reasoning token consumption will lead to significant underestimation of real‑world billing.

7. Frequently encountered issues

Q: Tutorials online recommend `wire_api = "chat"`, why does Codex report errors?
A: The "chat" enum value has been removed in current Codex CLI releases. Only wire_api = "responses" remains valid. Those articles reference deprecated old releases and are no longer applicable.

Q: Is LiteLLM the only viable bridge solution?
A: Any custom translation service can fill this protocol‑translation role. Developers may write custom middleware converting Responses request/response schema to Chat Completions format. Custom implementations must handle streaming chunks, tool invocation, and reasoning‑token metadata parsing, increasing engineering overhead. LiteLLM delivers these capabilities out‑of‑the‑box.

Q: Does bridge middleware add substantial latency?
A: Local LiteLLM forwarding overhead is minimal. Most latency originates on model inference side. Validate streaming behaviour end‑to‑end; confirm incremental chunk output instead of monolithic final‑response returns.

Q: Model cannot be found error after configuration.
A: Two common causes: missing openai/ prefix inside LiteLLM config, or mismatched model identifier. Copy exact model ID returned by upstream /v1/models endpoint. Local aliases defined under model_name in LiteLLM config are independent of upstream real identifiers.

Q: Binary installation errors for Codex CLI?
A: spawn ENOENT errors relate to npm binary package installation corruption. Re‑install @openai/codex. This is unrelated to bridge‑layer or upstream‑model configuration.

8. Conclusion

The fundamental integration challenge between Codex CLI and DeepSeek V4 boils down to protocol incompatibility. Codex CLI exclusively consumes the Responses API schema, whereas DeepSeek V4 exposes Chat Completions. A translating bridge component sits in‑between to translate request‑response payloads. The six‑step workflow described achieves stable operation, retains full model capabilities including reasoning‑token metadata and high‑concurrency Flash‑variant throughput.

Before opening production workloads, validate endpoints, model identifiers and token‑usage metrics with curl‑based manual testing. Always treat secrets as environment variables rather than static configuration entries.

International access: https://4sapi.com
Domestic access: https://4sapi.cn