OpenAI-compatible API

Current Status

Supported API Shapes

Usage history API and request labels

Open Dashboard → Usage & billing to create the account's one active read-only Usage API key. Complete key values and copy-ready commands are shown once and stored only as a hash. Up to 10,000 rows can be returned per page, with next_cursor for continuation. JSON and CSV requests share a per-key limit of 3 requests per 60 seconds.

curl -sS -H "Authorization: Bearer <USAGE_API_KEY>" \
  "https://codex.photonmark.com/api/v1/usage/charges.csv?from=2026-08-01T00%3A00%3A00Z&to=2026-08-02T00%3A00%3A00Z&limit=10000" \
  -o photonmark-usage.csv

For per-agent cost and cache analysis, attach strings under metadata.photonmark_agent, metadata.photonmark_agent_version, and metadata.photonmark_session_id. The pm_* aliases are also accepted. These opt-in labels appear in the Dashboard CSV and Usage API alongside input, uncached input, cached input, cache-write, output, cost, latency, and status fields. Dashboard provides a complete copy-ready model request with the active Pay API key filled in.

Use opaque labels without prompts, personal information, credentials, or other secrets. The labels remain with the billing record.

Image API permissions, parameters, and limits

No separate activation is required. Every active Pay proxy token can call both image endpoints and uses the same Pay balance as text requests. There is no separate image permission application or image-only top-up.

Use gpt-image-2. The table below describes the parameters currently passed through by PhotonMark. For predictable billing, specify quality and size explicitly.

Concurrency and timeouts: PhotonMark does not publish a fixed per-key QPS or concurrency guarantee for Image API traffic. Start with concurrency 1, increase gradually, and retry transient HTTP 429/5xx responses with exponential backoff and jitter. Complex image requests can take up to about two minutes; use a client timeout of at least 180 seconds, while allowing for earlier CDN or network interruptions.

See the exact per-image Pay deductions and the official OpenAI image-generation guide.

What else may connect besides Codex

Any app that allows a custom OpenAI-compatible base_url and API key may be able to connect to this interface. For high concurrency, team sharing, or important production paths, contact us first to confirm rate limits, models, and expected usage.

OpenCode Configuration

When OpenCode uses the Responses API, the provider's npm should be @ai-sdk/openai. baseURL should use PhotonMark's standard API endpoint, and apiKey should use your Pay proxy token.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "photonmark": {
      "npm": "@ai-sdk/openai",
      "name": "PhotonMark",
      "options": {
        "baseURL": "https://codex.photonmark.com/openai/v1",
        "apiKey": "{env:PHOTONMARK_PAY_TOKEN}"
      },
      "models": {
        "gpt-5.5": {
          "name": "gpt-5.5",
          "limit": {
            "context": 262144,
            "output": 32768
          }
        }
      }
    }
  }
}

strip-max-tokens.ts was previously used to remove max_output_tokens; it is no longer needed. Users who installed it can remove it and restart OpenCode; leaving it in place temporarily will not affect usage.

Compatibility boundary: PhotonMark accepts max_output_tokens sent by OpenCode / AI SDK and removes it before forwarding to Codex upstream. Therefore, this parameter is not enforced as a hard upstream output limit; actual output is determined by the model and upstream service.

For more provider field details, see the official OpenCode provider documentation.

OpenCodex Configuration

When using tool calls in OpenCodex, select the openai-responses adapter; do not use the openai-chat adapter. The latter sends tool definitions in the Chat Completions shape, which may be incompatible with the Responses API.

{
  "providers": {
    "PhotonMark": {
      "adapter": "openai-responses",
      "baseUrl": "https://codex.photonmark.com/openai/v1",
      "authMode": "key",
      "apiKey": "${PHOTONMARK_PAY_TOKEN}",
      "defaultModel": "gpt-5.6-sol"
    }
  }
}

If PhotonMark is already configured as a provider, change only openai-chat to openai-responses, keep the existing Pay API Key, model, and other routing fields; then run ocx restart and start a new session.

Troubleshooting:If you see Missing required parameter: 'tools[0].name', the request is usually still being sent by the openai-chat adapter. Switching to openai-responses requires no PhotonMark server-side changes.

For more adapter field details, see the official OpenCodex adapter documentation.

Call Example

After buying Codex Pay, copy your Pay proxy token from the dashboard. Examples put the token in PHOTONMARK_PAY_TOKEN environment variable to avoid putting it in code.

Python SDK: Text

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PHOTONMARK_PAY_TOKEN"],
    base_url="https://codex.photonmark.com/openai/v1",
)

resp = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "Reply with OK only."}],
)

print(resp.choices[0].message.content)

Python SDK: Image Generation

This uses your PhotonMark Pay proxy token and does not require an official OpenAI Platform API key. Image usage is recorded against Pay by model, quality, size, and quantity; see thepricing page.

import base64
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PHOTONMARK_PAY_TOKEN"],
    base_url="https://codex.photonmark.com/openai/v1",
)

resp = client.images.generate(
    model="gpt-image-2",
    prompt="Draw a simple cute cat.",
    quality="low",
    size="1024x1024",
)

image_base64 = resp.data[0].b64_json
if not image_base64:
    raise RuntimeError("Image API returned no image data")

output = Path("photonmark-cat.png")
output.write_bytes(base64.b64decode(image_base64))
print(f"Saved to: {output.resolve()}")

Python SDK: Image Editing (Multiple Reference Images)

Put the main image first, followed by optional style or palette references. Up to 16 reference images are currently supported. The optional mask applies only to the first image.gpt-image-2 uses high input fidelity by default, so you do not need to set input_fidelity.

from pathlib import Path

with open("main.png", "rb") as main_image, open("style.png", "rb") as style_image:
    resp = client.images.edit(
        model="gpt-image-2",
        image=[main_image, style_image],
        prompt="Keep the main object's geometry and apply the reference palette.",
        quality="high",
        size="1536x1024",
    )

image_base64 = resp.data[0].b64_json
if not image_base64:
    raise RuntimeError("Image Edit API returned no image data")

output = Path("photonmark-edited.png")
output.write_bytes(base64.b64decode(image_base64))
print(f"Saved to: {output.resolve()}")

curl: Chat Completions

export PHOTONMARK_PAY_TOKEN="your PhotonMark Pay proxy token"

curl https://codex.photonmark.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $PHOTONMARK_PAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "user", "content": "Reply with OK only."}
    ]
  }'

curl: Image Generation

curl https://codex.photonmark.com/openai/v1/images/generations \
  -H "Authorization: Bearer $PHOTONMARK_PAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Draw a simple cute cat.",
    "quality": "low",
    "size": "1024x1024"
  }' | jq -r '.data[0].b64_json' | base64 --decode > photonmark-cat.png

curl: Models Endpoint Check

curl https://codex.photonmark.com/openai/v1/models \
  -H "Authorization: Bearer $PHOTONMARK_PAY_TOKEN"

Node.js SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PHOTONMARK_PAY_TOKEN,
  baseURL: "https://codex.photonmark.com/openai/v1",
});

const resp = await client.chat.completions.create({
  model: "gpt-5.4-mini",
  messages: [{ role: "user", content: "Reply with OK only." }],
});

console.log(resp.choices[0].message.content);

Current Boundaries

• The Image API endpoint POST /images/generations and POST /images/editsare supported. Image variations and other Image API endpoints are not currently available.
• Direct Image API calls and Codex's native image_gen tool are separate capabilities. This API does not inject a missing native tool into a Codex session, but scripts, CLIs, MCP servers, and plugins can call it.
• Except for the explicitly published Codex Realtime voice beta, we do not yet promise full compatibility with all other OpenAI Platform parameters, tools, files, batch processing, or realtime audio APIs.
• Chat Completions streaming is currently available as an experimental capability; for important production workloads, contact us first to confirm client compatibility and expected usage.
• For high concurrency, team sharing, or important production workloads, contact us first to confirm rate limits, model allowlists, error format, and usage estimates.
• Link / Boost are not used as standard model APIs; they remain access services for the official Codex client.

If you need to migrate an existing OpenAI SDK app to the PhotonMark Codex API, contact us first with use case, model, concurrency, expected token volume, and whether web search / image generation is needed. We evaluate account by account.