openai-python 3.9/3.10 and openai-node 7.11/7.12: Prompt Cache Diagnostics, API Key Expiry, GPT Image 2.5

Across 2026-09-08 and 09-09, OpenAI's two official SDKs shipped four releases in quick succession (plus one Node patch), on the evening of 09-09 added a pair of key-governance releases (v3.11.0 / v7.13.0), and on the evening of 09-10 added two more pairs — the Live API (v3.12.0 / v7.14.0) and the Agents API (v3.13.0 / v7.15.0), the only two brand-new resource surfaces in this wave. The most valuable item in the earlier releases is prompt cache diagnostics — when a cache miss happens, you finally get a structured "why". The rest: Service Account API key expiry fields and their follow-up policy governance upgrade, GPT Image 2.5 model types, and a batch of documented 429/503 responses. Every fact below was checked against same-day, re-fetchable GitHub release notes and SDK source (reference list at the end); the OpenAI docs domains return 403 to this site (last known accessible on 2026-09-01; re-checked and still inaccessible on 2026-09-11), so nothing is asserted beyond what these sources show.

1. Release overview

Note that the two packages' version numbers do not map one to one: the key expiry fields landed in v3.10.0 on the Python side but v7.11.0 on the Node side, and the key governance upgrade landed in v3.11.0 on the Python side but v7.13.0 on the Node side. The two pairs from the evening of 09-10, by contrast, are aligned releases: the Live API in python v3.12.0 / node v7.14.0 (one minute apart) and the Agents API in python v3.13.0 / node v7.15.0 (the same minute). Node also shipped a v7.12.1 patch on 09-09 (2026-09-09 01:15 UTC, republishing v7.12.0's GPT Image 2.5 support, which had missed npm) plus CI fixes; its contents are not covered further here.

2. Prompt cache diagnostics: finally a "why" for misses

2.1 How it works

From v3.9.0, responses.create accepts comparison_response_id inside prompt_cache_options (a string holding a previous response ID). Per the SDK text: supplying this field requests prompt cache diagnostics when the feature is enabled. The result lands in the response object's prompt_cache_diagnostics field, a discriminated union:

• cache_hit: the reusable prefix matched;
• cache_miss: no match, with three pieces of information — reason (nine enum values), cache_missed_tokens (estimated input tokens affected after the first detected divergence), and an optional comparison_reusable_tokens (raw token count of the reusable prefix in the compared response);
• comparison_response_not_found: the given response ID does not exist;
• unavailable: diagnostics could not run.

The nine miss reasons deserve the full table — they cover practically every "why did the cache miss this time" scenario:

The accompanying type documentation also pins down the key prompt caching numbers: prompt_cache_options supports gpt-5.6 and later models; mode defaults to implicit (one implicit breakpoint written automatically, plus up to the latest three explicit breakpoints), and explicit writes no implicit breakpoint and up to four explicit ones; cache matching considers up to the latest 80 breakpoints in the conversation; ttl currently has the single supported value 30m. A prompt_cache_key_changed client event joins the event enum, sharing its name with the miss reason.

2.2 Code

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-5.6-terra",
    input="Summarize the three key conclusions from this deploy retro",
    prompt_cache_key="deploy-notes-2026-09",          # existing: stable cache key
    prompt_cache_options={
        "comparison_response_id": "resp_abc123",      # new in v3.9.0: previous response ID
    },
)

diag = resp.prompt_cache_diagnostics                  # Optional[PromptCacheDiagnostics]
if diag is not None and diag.type == "cache_miss":
    print(diag.reason, diag.cache_missed_tokens)

This sample is SDK-source-verified (field-checked against the v3.9.0 parameter types), not live-fire tested.

3. Service Account API key expiry fields

On the Python side, v3.10.0 gives Service Account API keys under the admin surface an expiry semantic:

• Request: api_keys.create accepts an optional expires_in_seconds (seconds);
• Response: the returned object adds expires_in_seconds ("Number of seconds until the API key expires") and expires_at (a Unix timestamp, null if it does not expire).

key = client.admin.organization.projects.service_accounts.api_keys.create(
    service_account_id="sa_xxx",      # placeholder
    project_id="prj_xxx",             # placeholder
    name="ci-runner-key",
    expires_in_seconds=60 * 60 * 24 * 90,   # 90 days
)
print(key.expires_at, key.expires_in_seconds)

For CI and automation this is a real win: service account keys previously lived until rotated, so the blast radius of a leak depended on rotation discipline; now the expiry belongs in the create call itself. Note the fields appear on Service Account keys only — the SDK types show no corresponding change for user API keys, so do not extrapolate.

Hours later, those fields went through a qualitative change in v3.11.0 / v7.13.0 (both packages published around 15:30 UTC on 2026-09-09): expires_in_seconds gained a hard 1..31536000-second (365-day) range, and the semantics graduated from "an optional field" to "policy governance" — organization or project expiration policies can force keys to expire and cap the maximum lifetime (making the value mandatory and bounded), and the field conflicts with create_service_account_only: true. The full read lives in our OpenAI API Key Expiration: expires_in_seconds, Org Policies, and Safe Automation.

4. GPT Image 2.5 types land

v3.10.0 (Python) and v7.12.0 (Node) write the two GPT Image 2.5 models (gpt-image-2.5-sunburst / gpt-image-2.5-flare, each with a -2026-09-08 snapshot) into the model enums and adjust the image options: quality gains xhigh / max, transparent background no longer carries the preview note on 2.5, and the arbitrary resolution rules ride along in the parameter docs. The full read lives in our GPT Image 2.5 Explained: sunburst and flare, xhigh/max Quality, Arbitrary Resolutions; no repetition here.

5. Added on 09-10: the Live API and the Agents API

On the final evening of the three-day batch, each package shipped two releases carrying two brand-new API resource surfaces, each with a dedicated article:

• Live API (python v3.12.0 / node v7.14.0, 17:28 / 17:29 UTC): a client.live namespace where POST /live/sessions submits a WebRTC SDP offer to start a live session and connect() opens a WebSocket; the sessions subresource carries the four SIP call-control endpoints (accept's SDK docstring reads "Accept an incoming SIP call") plus fork and download_recording, and sideband attaches to an existing session. The session-config model field gains the literal gpt-live-1 — which never enters the ChatModel enum and is not an announced model. Full read: The Live API lands in the OpenAI SDK: gpt-live-1, dual WebRTC/WebSocket channels, and SIP call control.
• Agents API (python v3.13.0 / node v7.15.0, 19:37 UTC, same minute): the beta namespace client.beta.agents, with top-level HTTP endpoints /agents and /vaults. Four resource surfaces: CRUD for reusable Agents (a five-value service_tier enum), Managed Agents sessions (status machine idle / in_progress / requires_action / failed), execution environments (templates / files / skills / plugins), and credential vaults. Full read: The Agents API appears in the OpenAI SDK (beta): /agents CRUD, environments, sessions, and vaults.

Neither surface has an availability or pricing announcement as of 2026-09-11 (the docs domains return 403 to us); production systems should watch rather than adopt.

6. The remaining fixes and documentation

• Function argument completion event fields corrected (openapi-545): v3.9.0 fixes the field definitions of function argument completion events. The release note stops at that sentence; downstream code that parses streaming function call progress by event fields should re-run its event parsing tests after upgrading.
• Incomplete web search call statuses accepted: the web search call status enum expands to express an in-between "not finished" state. If your code switches exhaustively over statuses, add a fallback for the new value.
• Refuse overflowing server retry delays: when the server returns an absurdly large retry-after, the SDK no longer waits it out (no more hanging a retry overnight) and raises instead.
• 429 / 503 response documentation: SDK-235 writes the rate-limit (429, including TooManyRequests / InferenceRateLimited shapes) and overload (503, InferenceServiceUnavailable) responses into the API spec descriptions — error handling branches finally have a citable source.
• Node-side fixes (v7.11.0): retaining terminal message snapshots in assistants, audio recording process signaling, and more — SDK quality fixes with no API semantics attached.

7. Upgrade guidance

• Production services using prompt caching: upgrade to Python at least v3.9.0 / Node at least v7.11.0 and add comparison_response_id diagnostics to your main path. When the hit rate dips, the nine reasons tell you which configuration drifted — much faster than staring at a dashboard.
• Teams with Service Account keys: upgrade to Python at least v3.11.0 / Node at least v7.13.0 (basic fields plus the policy governance semantics), put expires_in_seconds on every new key, re-issue legacy keys on your rotation schedule, and inventory legacy keys whose expires_at is null. Make sure callers with organization / projects admin scopes upgrade in lockstep.
• Image generation pipelines: upgrade to Python at least v3.10.0 / Node at least v7.12.0 only when you want to try 2.5; otherwise stay put (gpt-image-2 is not deprecated).
• Everyone: walk the error-handling branches in CI — with 429/503 shapes now written into the spec, this is the moment to tighten retry and backoff policies.

For the full prompt caching mechanics and cost math, see Responses API advanced: structured outputs, streaming SSE, Batch API, prompt caching; for the timeline view of model and API changes, see OpenAI Models Release Notes (2026, Living Document).

8. Next steps

• The Responses API Compaction Progress Event: response.compaction.compacting and compaction_trigger — a deep read of the compaction progress event from node v7.17.0 (09-16).
• openai-python 3.14.x and openai-node 7.16/7.17: Stream Error Normalization, WebSocket Backpressure, and SSE Fixes — the next installment of this series, 09-14 through 09-16.
• The Live API lands in the OpenAI SDK: gpt-live-1, dual WebRTC/WebSocket channels, and SIP call control — the brand-new real-time session surface from 09-10.
• GPT Image 2.5 Explained: sunburst and flare, xhigh/max Quality, Arbitrary Resolutions — the full read on this batch's image side.
• OpenAI API Key Expiration: expires_in_seconds, Org Policies, and Safe Automation — the full read and ops checklist for the key governance upgrade (v3.11.0 / v7.13.0).
• gpt-6-astra appears in the OpenAI SDK: the new ChatModel ID and the Safety Alerts API — the other major type-layer shift one week earlier (09-03).
• Responses API advanced: structured outputs, streaming SSE, Batch API, prompt caching — prompt caching mechanics and billing impact.
• OpenAI Models Release Notes (2026, Living Document) — every release on one timeline.
• OpenAI API Error Handling and Retry: 401/429/5xx Patterns — putting retry and backoff policies for 429/503 into practice.