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

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

@@ -2,6 +2,19 @@
 
 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-backend-sdk
-Version: 0.3.7
+Version: 0.3.8
 Summary: Unofficial Python SDK for the ChatGPT Codex backend API
 License: MIT
 License-File: LICENSE
@@ -188,8 +188,8 @@ resources (`responses`, `models`, `realtime`) or Codex-only resources (`codex`).
 | `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(...)` | 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.7 → codex_backend_sdk-0.3.8}/README.md

@@ -162,8 +162,8 @@ resources (`responses`, `models`, `realtime`) or Codex-only resources (`codex`).
 | `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(...)` | 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.7 → codex_backend_sdk-0.3.8}/codex_backend_sdk/__init__.py

@@ -17,7 +17,7 @@ Quickstart:
     print(response.output_text)
 """
 
-__version__ = "0.3.7"
+__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.7 → 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.7 → 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.7 → codex_backend_sdk-0.3.8}/docs/backend-api.md

@@ -306,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`
 
@@ -328,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.7 → codex_backend_sdk-0.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-backend-sdk"
-version = "0.3.7"
+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.7 → 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.7 → codex_backend_sdk-0.3.8}/uv.lock

@@ -160,7 +160,7 @@ wheels = [
 
 [[package]]
 name = "codex-backend-sdk"
-version = "0.3.7"
+version = "0.3.8"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },