OpenAI-Compatible SDKs

Codex Pooler provides narrow OpenAI-compatible /v1 support for selected SDK routes. It translates supported requests into Codex-compatible work, then sends them through the same Pool routing, limit checks, account selection, and accounting path used by Codex backend clients.

It doesn’t provide full OpenAI API parity.

For a short citable summary, see OpenAI-compatible Codex gateway.

What OpenAI-Compatible Means Here

OpenAI-compatible means selected SDK request shapes can use a /v1 base URL and a Pool API key. Codex Pooler still routes the request through Codex account Pools, not through a separate OpenAI engine. Unsupported OpenAI API areas remain unsupported, including embeddings, batches, fine-tuning, moderation, response retrieve/cancel/delete, image variations, OpenAI Responses remote MCP tool definitions, and OpenAI Realtime SDK routes.

Base URL and authentication

Use the /v1 base URL and a Pool API key:

Base URL:
https://codex-pooler.example.com/v1

Authorization:
Bearer <pool-api-key>

For local setup, use http://localhost:4000/v1.

Tool-specific setup pages

Use the dedicated setup pages when configuring an agent or editor that has its own provider shape:

Python SDK

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CODEX_POOLER_API_KEY"],
    base_url="https://codex-pooler.example.com/v1",
)

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Write a short setup confirmation.",
)

print(response.output_text)

Node SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CODEX_POOLER_API_KEY,
  baseURL: "https://codex-pooler.example.com/v1",
});

const response = await client.responses.create({
  model: "gpt-5.6-terra",
  input: "Write a short setup confirmation.",
});

console.log(response.output_text);

Vercel AI SDK

import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const pooler = createOpenAI({
  apiKey: process.env.CODEX_POOLER_API_KEY,
  baseURL: "https://codex-pooler.example.com/v1",
});

const { text } = await generateText({
  model: pooler.responses("gpt-5.6-terra"),
  providerOptions: {
    openai: {
      promptCacheOptions: { mode: "explicit", ttl: "30m" },
    },
  },
  messages: [
    {
      role: "system",
      content: "Keep setup guidance concise.",
      providerOptions: {
        openai: { promptCacheBreakpoint: { mode: "explicit" } },
      },
    },
    { role: "user", content: "Write a short setup confirmation." },
  ],
});

console.log(text);

Codex Pooler validates and forwards these OpenAI cache controls independently from Pool routing affinity. GPT-5.6 model ids are passed through to the Pool catalog and assignment policy; naming one here does not guarantee that every Pool has an eligible account for that model.

GET /v1/models may include context_length for clients that probe OpenAI-compatible model lists, such as Hermes. The official OpenAI SDK request APIs and Vercel AI SDK generation APIs do not expose Codex model-catalog context controls. Use their output-budget fields only when your application needs one: max_output_tokens in OpenAI Responses, max_completion_tokens in Chat Completions, and maxOutputTokens at the Vercel AI SDK layer. Codex Pooler’s public /v1/responses currently rejects context_management, and public /v1/responses/compact is routed but unsupported, so do not document SDK-side compaction as a Codex Pooler feature.

Supported or translated route support

The OpenAI-compatible /v1 surface supports or translates selected routes only:

GET /v1/models
POST /v1/responses
GET /v1/responses, narrow Responses websocket compatibility only
POST /v1/chat/completions
GET /v1/usage
GET /v1/files
POST /v1/files
GET /v1/files/:file_id
POST /v1/audio/transcriptions
POST /v1/images/generations
POST /v1/images/edits

The /v1 surface is compatibility over Codex routing, not a separate OpenAI engine. Supported requests still require a Pool API key and a Pool with eligible upstream capacity for the requested model.

POST /v1/responses lifts system and developer input-message text into top-level instructions before dispatching to Codex-compatible work. Streaming /v1/responses and /v1/chat/completions return early upstream terminal errors as the first public SSE event or data chunk, without synthetic assistant/success prefixes. Non-streaming failures remain OpenAI-shaped JSON errors.

Ordinary OpenAI Responses incomplete terminals are preserved. If an upstream returns response.incomplete with status: "incomplete" for output limits or content filtering and no embedded error, /v1/responses streaming and websocket clients receive that incomplete terminal instead of a synthetic failure. Error-coded incomplete terminals, such as context overflow or stale continuation anchors, are still returned through the sanitized failure path.

Accepted POST /v1/responses tool definitions are narrow. OpenAI Responses remote MCP tool definitions are rejected before dispatch.

Request compression behavior

Per-Pool request compression can apply to POST /v1/responses, POST /v1/chat/completions, and narrow Responses websocket response.create traffic. It is transparent to SDK clients and does not require a client flag. Operators enable it with the Pool setting request_compression_enabled.

The feature is request-side only. Codex Pooler may compress upstream-bound Responses tool-output payloads before dispatch, but it does not store raw outputs, does not store upstream response bodies, and does not implement CCR/retrieval. Public /v1/responses/compact remains unsupported.

If compression is enabled but savings do not appear, check the request log’s payload_compression status and reason. The UI prefers saved token count and token savings percent when local token counts are available, then falls back to saved bytes and byte savings percent.

Routed but unsupported boundaries

These /v1 routes are unsupported and may return deterministic OpenAI-shaped unsupported endpoint errors when explicitly routed:

POST /v1/responses/compact
GET /v1/files/:file_id/content, after ownership checks
DELETE /v1/files/:file_id, after ownership checks
POST /v1/images/variations
POST /v1/embeddings
POST /v1/batches
POST /v1/moderations
POST /v1/fine_tuning/jobs
GET /v1/responses/:response_id
POST /v1/responses/:response_id/cancel
DELETE /v1/responses/:response_id
/v1/realtime and OpenAI Realtime SDK websocket or session routes

GET /v1/responses is narrow Responses websocket compatibility, not /v1/realtime support. OpenAI Realtime SDK websocket and session routes are not supported.

Within POST /v1/responses, OpenAI Responses remote MCP tool definitions are unsupported. A top-level tools entry with type: "mcp", or an input item with type: "additional_tools" whose tools list contains type: "mcp", is rejected before upstream dispatch with an OpenAI-shaped invalid_request error.

MCP stays separate

The operator MCP endpoint is rooted at /mcp, not under /v1. It uses operator-owned MCP bearer tokens and returns metadata only.

The root /mcp endpoint is not a /v1/responses remote MCP bridge and is not invoked by Responses tools[type=mcp] definitions.

MCP URL:
https://codex-pooler.example.com/mcp

Authorization:
Bearer <operator-mcp-token>

Don’t use Pool API keys, browser sessions, cookies, query tokens, invite tokens, upstream tokens, or custom headers as MCP authentication.

Frequently Asked Questions

Can I use the official OpenAI SDK with Codex Pooler?

Yes, for selected SDK routes. Set the SDK base_url or baseURL to https://codex-pooler.example.com/v1, use a Pool API key as the bearer credential, and keep requests on supported route shapes such as responses, chat completions, models, usage, files, audio transcription, and image generation or edits.

Should Codex backend clients use `/v1`?

No. Codex backend-compatible clients should use /backend-api/codex. The /v1 surface is for selected OpenAI SDK-compatible clients and translates supported requests into Codex-compatible work.

Does `/v1` support OpenAI Realtime?

No. /v1/realtime and OpenAI Realtime SDK websocket or session routes are unsupported. GET /v1/responses is narrow Responses websocket compatibility only, not OpenAI Realtime support.

Does `/v1/responses/compact` work?

No. POST /v1/responses/compact is routed only so clients receive a deterministic OpenAI-shaped unsupported_endpoint error. Codex backend-compatible compact requests should use POST /backend-api/codex/responses/compact.

Codex backend clients that send a terminal compaction_trigger to POST /backend-api/codex/responses or /backend-api/codex/v1/responses are bridged through the backend compact route and receive backend Responses SSE compaction output.

Can I use the same key for `/v1` and `/mcp`?

No. /v1 uses Pool API keys for runtime work. /mcp uses operator-owned MCP bearer tokens for metadata-only lookup. Keep those credentials separate in client configuration and storage.