codex-backend-sdk 0.3.6__tar.gz → 0.3.8__tar.gz

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.8}/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.8] - 2026-07-17
+
+### Changed
+- Routed `client.audio.transcriptions.create(...)` through the ChatGPT-native `/backend-api/transcribe` endpoint instead of the billable Platform `/v1/audio/transcriptions` endpoint.
+- Preserved the OpenAI-shaped `json` and `text` response behavior used by Codex Agent while rejecting unsupported streaming, timestamp, speaker, chunking, SRT, and VTT options explicitly.
+- Added a reusable raw ChatGPT multipart request helper to the client transport.
+
+### Documentation
+- Clarified that embeddings still use the OpenAI Platform endpoint and its developer-account quota, while batch transcription now uses the authenticated ChatGPT backend.
+
+### Tests
+- Added coverage for ChatGPT transcription routing, account authentication headers, text responses, and unsupported parameters.
+
+## [0.3.7] - 2026-07-17
+
+### Added
+- Added typed Realtime call results through `RealtimeCallResponse.answer_sdp` and `RealtimeCallResponse.call_id`.
+- Added Codex AVAS session payload support, including automatic removal of the server-generated session `id` and the required `quicksilver` query parameters.
+
+### Documentation
+- Documented that the ChatGPT-authenticated Codex WebRTC route is experimental and rollout-dependent, while the public Realtime WebSocket route still requires a developer API key.
+
+### Tests
+- Added coverage for SDP response parsing, call ID validation, AVAS payload construction, and invalid session payloads.
+
 ## [0.3.6] - 2026-07-11
 
 ### Added

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-backend-sdk
-Version: 0.3.6
+Version: 0.3.8
 Summary: Unofficial Python SDK for the ChatGPT Codex backend API
 License: MIT
 License-File: LICENSE
@@ -186,10 +186,10 @@ resources (`responses`, `models`, `realtime`) or Codex-only resources (`codex`).
 | `POST /backend-api/codex/responses/compact` | `client.responses.compact(...)` | Codex-specific helper for encrypted context compaction. |
 | `POST /backend-api/codex/memories/trace_summarize` | `client.codex.memories.trace_summarize(...)` | Raw Codex memory trace summarization helper. |
 | `GET /backend-api/codex/models` | `client.models.list()` / `client.models.retrieve(...)` | OpenAI-shaped model objects with Codex metadata preserved as extra fields. |
-| `POST /backend-api/codex/realtime/calls` | `client.realtime.calls.create(...)` | OpenAI-shaped SDP call creation for realtime sessions. |
+| `POST /backend-api/codex/realtime/calls` | `client.realtime.calls.create(...)` | Experimental SDP call creation. The protocol is implemented by Codex, but ChatGPT routing is rollout-dependent and may return `404 Not Found`. |
 | `wss://api.openai.com/v1/realtime?model=...` | `client.realtime_websocket_url(...)` / `client.realtime.websocket_headers(...)` | Voice v2 helpers; requires a Realtime API key obtained during OAuth or supplied by the auth store. |
-| `POST /v1/embeddings` | `client.embeddings.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; verified with `text-embedding-3-small`. |
-| `POST /v1/audio/transcriptions` | `client.audio.transcriptions.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; verified with `gpt-4o-mini-transcribe`. |
+| `POST /v1/embeddings` | `client.embeddings.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; usage is charged to the associated OpenAI Platform organization. |
+| `POST /backend-api/transcribe` | `client.audio.transcriptions.create(...)` | Uses the authenticated ChatGPT backend for non-streaming batch transcription; no developer API key is required. |
 | `GET /backend-api/wham/usage` | `client.codex.usage()` | Codex/ChatGPT quota and rate-limit status. |
 | `GET /backend-api/wham/config/requirements` | `client.codex.config.requirements()` | Raw managed requirements/config payload for the authenticated account. |
 | `GET /backend-api/wham/tasks/list` | `client.codex.tasks.list(...)` | Raw Codex cloud task listing. |

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.8}/README.md

@@ -160,10 +160,10 @@ resources (`responses`, `models`, `realtime`) or Codex-only resources (`codex`).
 | `POST /backend-api/codex/responses/compact` | `client.responses.compact(...)` | Codex-specific helper for encrypted context compaction. |
 | `POST /backend-api/codex/memories/trace_summarize` | `client.codex.memories.trace_summarize(...)` | Raw Codex memory trace summarization helper. |
 | `GET /backend-api/codex/models` | `client.models.list()` / `client.models.retrieve(...)` | OpenAI-shaped model objects with Codex metadata preserved as extra fields. |
-| `POST /backend-api/codex/realtime/calls` | `client.realtime.calls.create(...)` | OpenAI-shaped SDP call creation for realtime sessions. |
+| `POST /backend-api/codex/realtime/calls` | `client.realtime.calls.create(...)` | Experimental SDP call creation. The protocol is implemented by Codex, but ChatGPT routing is rollout-dependent and may return `404 Not Found`. |
 | `wss://api.openai.com/v1/realtime?model=...` | `client.realtime_websocket_url(...)` / `client.realtime.websocket_headers(...)` | Voice v2 helpers; requires a Realtime API key obtained during OAuth or supplied by the auth store. |
-| `POST /v1/embeddings` | `client.embeddings.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; verified with `text-embedding-3-small`. |
-| `POST /v1/audio/transcriptions` | `client.audio.transcriptions.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; verified with `gpt-4o-mini-transcribe`. |
+| `POST /v1/embeddings` | `client.embeddings.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; usage is charged to the associated OpenAI Platform organization. |
+| `POST /backend-api/transcribe` | `client.audio.transcriptions.create(...)` | Uses the authenticated ChatGPT backend for non-streaming batch transcription; no developer API key is required. |
 | `GET /backend-api/wham/usage` | `client.codex.usage()` | Codex/ChatGPT quota and rate-limit status. |
 | `GET /backend-api/wham/config/requirements` | `client.codex.config.requirements()` | Raw managed requirements/config payload for the authenticated account. |
 | `GET /backend-api/wham/tasks/list` | `client.codex.tasks.list(...)` | Raw Codex cloud task listing. |

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.8}/codex_backend_sdk/__init__.py

@@ -17,7 +17,7 @@ Quickstart:
     print(response.output_text)
 """
 
-__version__ = "0.3.6"
+__version__ = "0.3.8"
 
 from .oauth import run_oauth_flow, refresh_access_token
 from .storage import load_tokens, save_tokens, TokenStore

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.8}/codex_backend_sdk/_client.py

@@ -295,14 +295,33 @@ class CodexClient:
         body: dict[str, Any],
         timeout: Any = _UNSET,
     ) -> dict[str, Any]:
+        response = self._post_chatgpt_raw(path, body=body, timeout=timeout)
+        return response.json()
+
+    def _post_chatgpt_raw(
+        self,
+        path: str,
+        *,
+        body: Optional[dict[str, Any]] = None,
+        files: Any = None,
+        data: Any = None,
+        headers: Optional[dict[str, str]] = None,
+        params: Optional[dict[str, Any]] = None,
+        timeout: Any = _UNSET,
+    ) -> requests.Response:
         self._ensure_auth()
         response = self._request_with_retries(
             "POST",
             f"{CHATGPT_BASE_URL}{path}",
-            json=body,
+            json=body if files is None and data is None else None,
+            files=files,
+            data=data,
+            headers=headers,
+            params=params,
             timeout=self._timeout if not _is_given(timeout) else timeout,
         )
-        return response.json()
+        response.raise_for_status()
+        return response
 
     def _request_with_retries(self, method: str, url: str, **kwargs: Any) -> requests.Response:
         use_session = kwargs.pop("_use_session", True)

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.8}/codex_backend_sdk/_models.py

@@ -304,4 +304,30 @@ class BinaryResponseContent:
 
 
 class RealtimeCallResponse(BinaryResponseContent):
-    """Binary SDP response returned by ``client.realtime.calls.create``."""
+    """SDP answer and call identifier returned by Realtime call creation."""
+
+    @property
+    def answer_sdp(self) -> str:
+        return self.text
+
+    @property
+    def call_id(self) -> str:
+        location = self.response.headers.get("Location")
+        if not location:
+            raise RuntimeError("Realtime call response is missing the Location header.")
+        path = location.split("?", 1)[0].rstrip("/")
+        call_id = path.rsplit("/", 1)[-1]
+        if call_id.startswith("rtc_") or _is_uuid(call_id):
+            return call_id
+        raise RuntimeError(
+            f"Realtime call Location does not contain a valid call id: {location}"
+        )
+
+
+def _is_uuid(value: str) -> bool:
+    if len(value) != 36:
+        return False
+    return all(
+        char == "-" if index in {8, 13, 18, 23} else char in "0123456789abcdefABCDEF"
+        for index, char in enumerate(value)
+    )

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.8}/codex_backend_sdk/resources/openai_oauth.py

@@ -1,15 +1,19 @@
-"""OpenAI v1 resources that accept the Codex OAuth access token."""
+"""OpenAI-shaped resources authenticated through the Codex ChatGPT session."""
 
 from __future__ import annotations
 
-from collections.abc import Iterator
 from typing import Any, Optional, TYPE_CHECKING
 
-import requests
-
-from .._models import CreateEmbeddingResponse, ResponseStreamEvent, Transcription
-from .._streaming import stream_response_events
-from .._utils import _UNSET, _add_given, _coerce_file, _form_value, _is_given, _jsonable
+from .._models import CreateEmbeddingResponse, Transcription
+from .._utils import (
+    _UNSET,
+    CodexBackendUnsupportedParameterError,
+    _add_given,
+    _coerce_file,
+    _form_value,
+    _is_given,
+    _jsonable,
+)
 
 if TYPE_CHECKING:
     from .._client import CodexClient
@@ -85,42 +89,50 @@ class AudioTranscriptions:
         extra_query: Optional[dict[str, Any]] = None,
         extra_body: Any = None,
         timeout: Any = _UNSET,
-    ) -> str | Transcription | Iterator[ResponseStreamEvent]:
+    ) -> str | Transcription:
         if not model:
             raise ValueError(f"Expected a non-empty value for `model` but received {model!r}")
 
+        if _is_given(response_format) and response_format not in {None, "json", "text"}:
+            raise CodexBackendUnsupportedParameterError(
+                "The ChatGPT transcription backend supports only `json` and `text` response formats."
+            )
+
+        unsupported = {
+            "chunking_strategy": chunking_strategy,
+            "include": include,
+            "known_speaker_names": known_speaker_names,
+            "known_speaker_references": known_speaker_references,
+            "stream": stream,
+            "timestamp_granularities": timestamp_granularities,
+        }
+        given_unsupported = [
+            name for name, value in unsupported.items()
+            if _is_given(value) and value not in {None, False}
+        ]
+        if given_unsupported:
+            raise CodexBackendUnsupportedParameterError(
+                "The ChatGPT transcription backend does not support: "
+                + ", ".join(sorted(given_unsupported))
+            )
+
         data = {"model": model}
-        _add_given(data, "chunking_strategy", chunking_strategy)
-        _add_given(data, "include", include)
-        _add_given(data, "known_speaker_names", known_speaker_names)
-        _add_given(data, "known_speaker_references", known_speaker_references)
         _add_given(data, "language", language)
         _add_given(data, "prompt", prompt)
         _add_given(data, "response_format", response_format)
-        _add_given(data, "stream", stream)
         _add_given(data, "temperature", temperature)
-        _add_given(data, "timestamp_granularities", timestamp_granularities)
         if extra_body:
             data.update(_jsonable(extra_body))
 
-        stream_enabled = bool(stream) if _is_given(stream) else False
-        response = self._client._post_openai_raw(
-            "/audio/transcriptions",
+        response = self._client._post_chatgpt_raw(
+            "/transcribe",
             files={"file": _coerce_file(file)},
             data={key: _form_value(value) for key, value in data.items()},
             headers=extra_headers,
             params=extra_query,
             timeout=timeout,
-            stream=stream_enabled,
         )
-        if stream_enabled:
-            return stream_response_events(response)
-        if _wants_text_response(response_format, response):
-            return response.text
-        return Transcription.model_validate(response.json())
-
-
-def _wants_text_response(response_format: Any, response: requests.Response) -> bool:
-    if _is_given(response_format) and response_format in {"text", "srt", "vtt"}:
-        return True
-    return "json" not in response.headers.get("content-type", "")
+        transcription = Transcription.model_validate(response.json())
+        if _is_given(response_format) and response_format == "text":
+            return transcription.text
+        return transcription

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.8}/codex_backend_sdk/resources/realtime.py

@@ -35,6 +35,12 @@ class Realtime:
 
 
 class RealtimeCalls:
+    """Experimental Codex WebRTC call creation.
+
+    Availability depends on the Realtime call route enabled for the authenticated
+    ChatGPT account. A correctly authenticated request may still return 404 while
+    the backend is not rolled out.
+    """
     def __init__(self, client: CodexClient) -> None:
         self._client = client
 
@@ -65,15 +71,23 @@ class RealtimeCalls:
             )
             return RealtimeCallResponse(response)
 
+        session_payload = _jsonable(session)
+        if not isinstance(session_payload, dict):
+            raise TypeError("Expected `session` to serialize to a JSON object.")
+        session_payload.pop("id", None)
+        body = {
+            "sdp": sdp,
+            "session": session_payload,
+            **(_jsonable(extra_body) if extra_body else {}),
+        }
+        query = {"intent": "quicksilver", "architecture": "avas"}
+        if extra_query:
+            query.update(extra_query)
         response = self._client._post_raw(
             "/realtime/calls",
-            body={
-                "sdp": sdp,
-                "session": _jsonable(session),
-                **(_jsonable(extra_body) if extra_body else {}),
-            },
+            body=body,
             headers={"Accept": "application/sdp", **(extra_headers or {})},
-            params=extra_query,
+            params=query,
             timeout=timeout,
         )
         return RealtimeCallResponse(response)

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.8}/docs/backend-api.md

@@ -264,14 +264,21 @@ Realtime audio/video call initiation.
 
 **SDK method**: `client.realtime.calls.create(...)`
 
-**Status**: Supported. The SDK follows the official OpenAI SDK shape:
+**Status**: Experimental and rollout-dependent. The SDK follows the Codex
+client protocol:
 
 - plain SDP offer: `client.realtime.calls.create(sdp=offer_sdp)`
-- SDP offer plus session payload:
+- AVAS SDP offer plus session payload:
   `client.realtime.calls.create(sdp=offer_sdp, session={...})`
 
-The response is returned as binary SDP content with `.content`, `.text`,
-`.read()`, `.iter_bytes()`, and `.write_to_file(...)` helpers.
+The OAuth-authenticated ChatGPT route is not enabled for every account and may
+return `404 Not Found` until Codex supplies an experimental WebRTC call base URL.
+This is distinct from the public Realtime WebSocket route, which currently
+requires a developer API key.
+
+The response exposes `.answer_sdp` and `.call_id`, while preserving the binary
+helpers `.content`, `.text`, `.read()`, `.iter_bytes()`, and
+`.write_to_file(...)`.
 
 ---
 
@@ -299,11 +306,12 @@ continues to work but Voice v2 requires a separately provisioned API key.
 
 ---
 
-## OpenAI API Endpoints With Codex OAuth
+## Embeddings and Transcription
 
-These endpoints live under `https://api.openai.com/v1`, not the ChatGPT backend,
-but they work with the same Codex OAuth access token stored in
-`~/.codex/auth.json`.
+These OpenAI-shaped resources deliberately use different upstreams. Embeddings
+remain an OpenAI Platform call and consume the associated developer-account
+quota. Batch transcription uses the authenticated ChatGPT backend and does not
+require a developer API key.
 
 ### `POST /v1/embeddings`
 
@@ -321,13 +329,20 @@ but they work with the same Codex OAuth access token stored in
 
 The response matches the official embeddings shape:
 `{ "object": "list", "data": [{ "object": "embedding", ... }], "usage": ... }`.
+The request is accounted against the OpenAI Platform organization returned by
+the API; ChatGPT OAuth authenticates it but does not include it in a ChatGPT
+subscription.
 
-### `POST /v1/audio/transcriptions`
+### `POST /backend-api/transcribe`
 
 **SDK method**: `client.audio.transcriptions.create(...)`
 
-**Status**: Supported for non-streaming calls. Verified with multipart upload
-using `gpt-4o-mini-transcribe`.
+**Status**: Supported for non-streaming ChatGPT batch transcription. The SDK
+uploads multipart audio with the OAuth bearer and `ChatGPT-Account-ID`, and
+supports the `model`, `language`, `prompt`, `temperature`, and `json`/`text`
+response options used by Codex Agent. Streaming, timestamps, speaker references,
+chunking, SRT, and VTT are rejected locally rather than falling back to a
+billable Platform endpoint.
 
 ### `POST /v1/audio/speech`
 

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-backend-sdk"
-version = "0.3.6"
+version = "0.3.8"
 description = "Unofficial Python SDK for the ChatGPT Codex backend API"
 readme = "README.md"
 license = { text = "MIT" }

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.8}/tests/test_openai_oauth_resources.py

@@ -1,4 +1,7 @@
+import pytest
+
 from codex_backend_sdk import CreateEmbeddingResponse, OpenAI, Transcription
+from codex_backend_sdk._utils import CodexBackendUnsupportedParameterError
 from codex_backend_sdk.storage import TokenStore
 
 
@@ -20,7 +23,7 @@ class FakeOpenAIClient(OpenAI):
     def __init__(self):
         super().__init__(model="gpt-test")
         self.openai_posts = []
-        self.openai_raw_posts = []
+        self.chatgpt_raw_posts = []
         self._set_store(TokenStore(
             access_token="chatgpt-token",
             refresh_token="refresh-token",
@@ -37,8 +40,8 @@ class FakeOpenAIClient(OpenAI):
             "usage": {"prompt_tokens": 1, "total_tokens": 1},
         }
 
-    def _post_openai_raw(self, path, **kwargs):
-        self.openai_raw_posts.append((path, kwargs, self._openai_headers()))
+    def _post_chatgpt_raw(self, path, **kwargs):
+        self.chatgpt_raw_posts.append((path, kwargs, self._auth_headers()))
         return FakeJSONResponse()
 
 
@@ -65,7 +68,7 @@ def test_embeddings_create_posts_to_openai_with_codex_oauth_token():
     assert headers["Authorization"] == "Bearer chatgpt-token"
 
 
-def test_audio_transcriptions_create_posts_multipart_like_official_sdk():
+def test_audio_transcriptions_create_posts_to_chatgpt_backend():
     client = FakeOpenAIClient()
 
     response = client.audio.transcriptions.create(
@@ -77,8 +80,8 @@ def test_audio_transcriptions_create_posts_multipart_like_official_sdk():
 
     assert isinstance(response, Transcription)
     assert response.text == "hello"
-    path, kwargs, headers = client.openai_raw_posts[0]
-    assert path == "/audio/transcriptions"
+    path, kwargs, headers = client.chatgpt_raw_posts[0]
+    assert path == "/transcribe"
     assert kwargs["files"]["file"] == ("clip.wav", b"wav", "audio/wav")
     assert kwargs["data"] == {
         "model": "gpt-4o-mini-transcribe",
@@ -86,3 +89,34 @@ def test_audio_transcriptions_create_posts_multipart_like_official_sdk():
         "response_format": "json",
     }
     assert headers["Authorization"] == "Bearer chatgpt-token"
+    assert headers["ChatGPT-Account-ID"] == "account-id"
+
+
+def test_audio_transcriptions_text_format_returns_string():
+    client = FakeOpenAIClient()
+
+    response = client.audio.transcriptions.create(
+        model="gpt-4o-mini-transcribe",
+        file=("clip.wav", b"wav", "audio/wav"),
+        response_format="text",
+    )
+
+    assert response == "hello"
+
+
+def test_audio_transcriptions_rejects_unsupported_options():
+    client = FakeOpenAIClient()
+
+    with pytest.raises(CodexBackendUnsupportedParameterError, match="stream"):
+        client.audio.transcriptions.create(
+            model="gpt-4o-mini-transcribe",
+            file=("clip.wav", b"wav", "audio/wav"),
+            stream=True,
+        )
+
+    with pytest.raises(CodexBackendUnsupportedParameterError, match="json.*text"):
+        client.audio.transcriptions.create(
+            model="gpt-4o-mini-transcribe",
+            file=("clip.wav", b"wav", "audio/wav"),
+            response_format="srt",
+        )

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.8}/tests/test_realtime_resource.py

@@ -6,6 +6,7 @@ class FakeResponse:
     content = b"answer-sdp"
     text = "answer-sdp"
     encoding = "utf-8"
+    headers = {"Location": "/v1/realtime/calls/calls/rtc_test"}
 
     def json(self, **kwargs):
         return {"ok": True}
@@ -43,6 +44,8 @@ def test_realtime_calls_create_posts_plain_sdp_like_official_sdk():
 
     assert isinstance(response, RealtimeCallResponse)
     assert response.read() == b"answer-sdp"
+    assert response.answer_sdp == "answer-sdp"
+    assert response.call_id == "rtc_test"
     path, kwargs = client.raw_posts[0]
     assert path == "/realtime/calls"
     assert kwargs["content"] == b"offer-sdp"
@@ -55,7 +58,7 @@ def test_realtime_calls_create_posts_session_as_backend_json():
 
     client.realtime.calls.create(
         sdp="offer-sdp",
-        session={"type": "realtime", "model": "gpt-realtime-1.5"},
+        session={"id": "session-id", "type": "realtime", "model": "gpt-realtime-1.5"},
     )
 
     path, kwargs = client.raw_posts[0]
@@ -64,9 +67,33 @@ def test_realtime_calls_create_posts_session_as_backend_json():
         "sdp": "offer-sdp",
         "session": {"type": "realtime", "model": "gpt-realtime-1.5"},
     }
+    assert kwargs["params"] == {"intent": "quicksilver", "architecture": "avas"}
     assert kwargs["headers"]["Accept"] == "application/sdp"
 
 
+def test_realtime_calls_create_rejects_non_object_session():
+    client = FakeRealtimeClient()
+
+    try:
+        client.realtime.calls.create(sdp="offer-sdp", session=["invalid"])
+    except TypeError as exc:
+        assert str(exc) == "Expected `session` to serialize to a JSON object."
+    else:
+        raise AssertionError("Expected non-object session to fail")
+
+
+def test_realtime_call_response_requires_valid_location():
+    response = FakeResponse()
+    response.headers = {"Location": "/v1/realtime/calls/not-a-call"}
+
+    try:
+        RealtimeCallResponse(response).call_id
+    except RuntimeError as exc:
+        assert "does not contain a valid call id" in str(exc)
+    else:
+        raise AssertionError("Expected invalid Location to fail")
+
+
 def test_realtime_websocket_uses_api_key_exchanged_during_oauth():
     client = FakeRealtimeClient()