openai-python 3.40/3.41 and openai-node 7.45.1: breakpoint TTL semantics, tool_usage, and Realtime item references

openai-python v3.40.0 and v3.41.0, together with openai-node v7.45.1, shipped across 2026-10-27 and 10-28: the Python side settles the prompt-cache breakpoint TTL inheritance wording and lands four new surfaces — hosted-tool usage on the Responses object, typed item references for Realtime inputs, metadata filtering for agent session lists, and binary-frame preservation in the WebSocket reconnect queue; the Node side mirrors the TTL wording and widens the vertex provider's google-auth-library range. Every parameter name and enum value in this article comes from the two repositories' tag sources (verified 2026-10-31), not from release-notes titles.

1. Versions and registry status

openai-python v3.40.0 and openai-node v7.45.1 released in the same minute (the two repos run synchronized CI); what you can install from PyPI today is v3.41.0. On the Node side this line has a single point release — the v7.45.0 (10-26) feature surface (scheduled automations, gpt-6.1-terra, and siblings) already appears in the 2026-10-26 entry of OpenAI Models Release Notes (2026, Living Document) and is not repeated here.

2. Breakpoint TTL: the field on 10-26, the semantics on 10-27

This story has two steps, and either release notes page alone reads it wrong:

Step one (the field): the breakpoint-level ttl field first appeared in python v3.38.0 (2026-10-26) — PromptCacheBreakpoint gained ttl: Literal["30m", "12h"]; the same file in the immediately preceding v3.37.0 has no such field.

Step two (the semantics): #4188 in v3.40.0 carries the title add prompt cache breakpoint TTL options, but its only type-layer change is documentation wording: the breakpoint inherits the request TTL became when ttl is omitted, the breakpoint inherits the request's prompt_cache_options.ttl — inheritance happens only when the breakpoint does not set its own ttl. On the Node side, #3057 in v7.45.1 applied the same wording across four resource files: responses, beta responses, chat completions, and conversations.

The breakpoint parameter definition on the v3.41.0 tag (from src/openai/types/responses/response_input_text_param.py, quoted verbatim):

class PromptCacheBreakpoint(TypedDict, total=False):
    """Marks the exact end of a reusable prompt prefix.

    When `ttl` is omitted, the breakpoint inherits the request's
    `prompt_cache_options.ttl`; the boundary is not rounded to a token block.
    """

    mode: Required[Literal["explicit"]]
    """The breakpoint mode. Always `explicit`."""

    ttl: Literal["30m", "12h"]
    """The minimum lifetime of this cache breakpoint. Defaults to the request TTL."""

Note that the request level did not widen: PromptCacheOptions.ttl on the v3.41.0 tag is still Literal["30m"], docstring verbatim — the ttl defaults to 30m, which is currently the only supported value. In other words, 12h exists only as a breakpoint-level override: keep the request at 30m and write ttl: "12h" on individual critical breakpoints — that is the combination the current type layer allows.

3. Response.tool_usage: hosted-tool usage, accounted separately

#4201 in v3.41.0 adds tool_usage: Optional[ToolUsage] to the Responses response object (beta variant included). The docstring positions it precisely: usage reported by hosted tools, separate from base model usage — sitting next to, and not inside, the base model usage; the whole field is omitted when unavailable, and tool families with no recorded usage report zero.

The two tool-family structures (assembled from the tag type files):

{
  "tool_usage": {
    "image_gen": {
      "input_tokens": 0,
      "output_tokens": 0,
      "total_tokens": 0,
      "cached_tokens": null,
      "input_tokens_details": { "image_tokens": 0, "text_tokens": 0 },
      "output_tokens_details": { "image_tokens": 0, "text_tokens": 0 },
      "cached_tokens_details": { "cached_image_tokens": 0, "cached_text_tokens": 0 }
    },
    "web_search": { "num_requests": 0 }
  }
}

Three semantic boundaries deserve quoting verbatim: image_gen sums available token counts across image generation calls, calls with missing or incomplete usage records may be skipped, and output details plus cached counts can be omitted — an omitted cache count means cache usage is unknown; web_search.num_requests counts billable searches — discounted searches and actions such as opening a page are excluded; and the closing sentence: use billing records to reconcile final charges.

For cost observation, this lets you read hosted-tool usage aggregates from a single response object instead of summing per-call records yourself — but the aggregation-gaps boundary means it fits observation, not billing, at least until reconciled against invoices.

4. Realtime: referencing existing session items with item_reference

#4189 adds typed references to Realtime response.create inputs. The new ResponseItemReferenceParam has exactly two fields: type: Literal["item_reference"] and id: Required[str] (the ID of an existing item in the same Realtime session). The type file's restriction is worth quoting verbatim: item references are only accepted in the response input array, not as new conversation items.

The WithReferences variant types input as Iterable[Union[ConversationItemParam, ResponseItemReferenceParam]] — regular items and references can interleave (example assembled from the tag type files):

event = {
    "type": "response.create",
    "response": {
        "input": [
            {"type": "item_reference", "id": "item_123"},
        ]
    },
}
connection.send(event)  # send() unions now accept the WithReferences variant (sync and async)

Accordingly, the send() method unions on both the sync and async WebSocket connections now also accept ResponseCreateEventWithReferencesParam — without that, reference-carrying events fail type checking.

5. Agent session lists: exact metadata filtering

#4200 adds a metadata filter to client.beta.agents.sessions.list (SessionListParams.metadata: Dict[str, str]). The docstring constraints, one by one: matching is exact string equality supplied as metadata[key]=value; all supplied pairs must match; up to 16 pairs; keys 1-64 characters and values up to 512 characters; new sessions and metadata updates may take time to appear in filtered results.

page = client.beta.agents.sessions.list(
    metadata={"team": "platform"},
    limit=50,
)  # SyncCursorPage[AgentSession]; agent_id filter and after cursor also available

This is a filter, not a search: exact matching, all-pairs-must-match, no fuzzy queries — treating metadata as a full-text index will not produce the expected results. The eventual-consistency sentence also rules it out for create-then-immediately-query strong-consistency flows.

6. The WebSocket reconnect queue: binary frames no longer decoded

#4191 reworks how the reconnect send queue treats frame types. Before, outbound frames during a reconnection window were queued uniformly as strings — binary frames were force-decoded to UTF-8; now SendQueue keeps str | bytes as-is, so binary frames are enqueued verbatim and replayed verbatim after reconnection.

When the connection still ends up closed, the raised WebSocketConnectionClosedError has three behaviors worth knowing:

• A new unsent_frames property preserves text and binary frames in their original order;
• The existing unsent_messages property stays a text compatibility view: UTF-8-decodable binary becomes text, while undecodable opaque binary lives only in unsent_frames;
• Ordinary exception-attribute snapshots are redacted — the recovery data object's __repr__ prints <redacted WebSocket recovery data>, keeping binary content out of logs by default.

Real-time audio or binary-protocol bridge applications that previously rolled their own convert-bytes-to-strings-before-reconnect fallback can hand that job to the SDK's queue after this batch.

7. Deprecation annotations: the translations endpoint, model rows, and image docs

#4199, titled document upcoming model shutdowns, writes a set of existing shutdown facts into the SDK layer — one of them is a new endpoint-level deprecation:

The /v1/audio/translations endpoint is marked deprecated. The audio.translations.create method and its overloads in python v3.41.0 now carry typing_extensions.deprecated (the SDK's own tests were updated to expect DeprecationWarning). The docstring verbatim: this endpoint supports only whisper-1, the endpoint and model are deprecated and scheduled to shut down on February 26, 2027, and the migration target is /v1/realtime/translations, which requires a separate integration — the same day the transcription quartet shuts down, and OpenAI says outright that the Realtime-side integration is a separate project.

The ChatModel 2027-04-01 deprecation row grew to four values: the previous two (gpt-5.4-nano, gpt-5.1) are joined by the dated snapshots gpt-5.4-nano-2026-03-17 and gpt-5.1-2025-11-13; gpt-5.3-codex still does not appear in this annotation row — the deprecation page, verified 2026-10-31, still lists it in the 2027-04-01 section (replaced by gpt-6-sol), and the mismatch between the SDK annotation and the page is the current state.

Image-model docstrings refreshed (#4198): gpt-image-1 is removed from the GPT image models input-constraints list (consistent with its 2026-10-23 shutdown), chatgpt-image-latest moves to its own sentence — follows the same input constraints as GPT image models — and the quality parameter's low-only wording now names gpt-image-1.5 only.

The Node side's one other change is #3046: the vertex provider's google-auth-library peer range widened from >=9.15.1 <11 to >=9.15.1 <12 (verified by comparing v7.45.0 and v7.45.1 package.json) — projects on Google's auth library v11 are no longer blocked by the peer dependency.

8. Upgrade notes and common traps

• From v3.39.x to v3.41.0 is purely additive: all four features in this batch are new surfaces, and the only changes to existing signatures are additive union widenings (such as #4189's send() accepting the new variant); v3.40.0's type-layer change is documentation wording only.
• Do not write articles from release-notes titles: the actual diff behind add prompt cache breakpoint TTL options is a wording refresh — the two-step timeline in section 2 (field on 10-26, semantics on 10-27) follows the tag-source comparison.
• tool_usage gaps are normal: the aggregate may skip calls with incomplete usage records and cache counts can be omitted — fine for observation; for billing, follow the official line and reconcile against billing records.
• The translations migration has integration cost: the docstring says requires a separate integration — it is not an endpoint-string swap; schedule it as a new integration.
• Node users: if you need only the TTL wording and google-auth-library v11 compatibility, v7.45.1 suffices; the rest of this batch (tool_usage, item_reference, session metadata filters, the binary-frame queue) does not appear in node release notes as of v7.45.1.

9. Next steps

• For the previous SDK surface (prompt-created voices, Live audio fixtures, Decisions with prompt caching), see openai-python 3.32.0 and openai-node 7.35.0: prompt-created voices, Live audio fixtures, and Decisions in Live.
• For cache prewarming and explicit-breakpoint basics, see openai-python 3.15/3.16 and openai-node 7.18/7.19: Cache Prewarming, Webhook Management, connector_id Deprecation.
• For background on the agent session system this batch's filters live in, see Hosted agent environments surface in the OpenAI SDKs: prewarmed creation, idle suspension, expiration.
• For the vertex provider and google-auth-library integration details, see OpenAI models land on Google Cloud: the Responses API on Vertex AI and the SDK vertex() provider.