OpenAI Python

https://github.com/openai/openai-python
Admin
The OpenAI Python library provides convenient access to the OpenAI REST API from any Python 3.8+...
Tokens:641,866
Snippets:3,281
Trust Score:9.4
License:Apache-2.0
Update:5 days ago
Show doc for...
Tokens:
Raw
### Install browser example dependencies

Source: https://github.com/openai/openai-python/blob/main/examples/browser/README_read_only.md

Set up a virtual environment and install the SDK with Playwright and Chromium. Run from the Python SDK checkout or source archive root.

```sh
python3 -m venv .venv-browser
.venv-browser/bin/python -m pip install -e . playwright==1.63.0
.venv-browser/bin/python -m playwright install chromium
```

--------------------------------

### Ask a question using the read-only browser example

Source: https://github.com/openai/openai-python/blob/main/examples/browser/README_read_only.md

Set OPENAI_API_KEY and OPENAI_MODEL in your shell, then run the example with a question. The answer should cite local guide pages and cannot make reservations.

```sh
.venv-browser/bin/python examples/browser/read_only.py "Can a group of 14 visit on Monday? Which entrance is accessible?"
```

--------------------------------

### Set OPENAI_EXAMPLE_BROWSER_CHANNEL to chrome

Source: https://github.com/openai/openai-python/blob/main/docs/browser.md

On Linux, if bundled Chromium cannot start with its sandbox enabled, set this environment variable to use a locally installed Chrome before running the quickstart. Leave unset to use Playwright's bundled Chromium.

```sh
export OPENAI_EXAMPLE_BROWSER_CHANNEL=chrome
```

--------------------------------

### Run live example with API key

Source: https://github.com/openai/openai-python/blob/main/examples/computer-desktop/README.md

Run the live example after setting OPENAI_API_KEY and OPENAI_MODEL on the host.

```sh
python examples/computer-desktop/run.py --live --runtime-dir "/tmp/desktop-$(id -u)"
```

--------------------------------

### Run no-key exercise

Source: https://github.com/openai/openai-python/blob/main/examples/computer-desktop/guest/README.md

After setup, run this exercise to verify the runtime. It requires a Python environment with openai and Pillow==12.3.0 installed.

```sh
python examples/computer-desktop/exercise.py --runtime-dir /private/tmp/desktop-$UID
```

--------------------------------

### Install OpenAI SDK and Playwright

Source: https://github.com/openai/openai-python/blob/main/docs/browser.md

Set up a Python virtual environment and install the OpenAI SDK and Playwright 1.63.0, then install the Chromium browser for Playwright.

```sh
python3 -m venv .venv
.venv/bin/python -m pip install openai playwright==1.63.0
.venv/bin/python -m playwright install chromium
```

--------------------------------

### Install Python SDK and Pillow

Source: https://github.com/openai/openai-python/blob/main/examples/computer-desktop/README.md

Install the Python SDK and Pillow from the source checkout or archive root.

```sh
python3 -m venv .venv-desktop
. .venv-desktop/bin/activate
python -m pip install -e . Pillow==12.3.0
```

--------------------------------

### Make executable and run an example script

Source: https://github.com/openai/openai-python/blob/main/CONTRIBUTING.md

Make the example script executable and run it against the target API.

```sh
$ chmod +x examples/<your-example>.py
# run the example against your api
$ ./examples/<your-example>.py
```

--------------------------------

### Install httpx-aiohttp using uv

Source: https://github.com/openai/openai-python/blob/main/src/openai/_vendor/httpx_aiohttp/README.md

Install the standard httpx-aiohttp package using uv pip.

```shell
uv pip install httpx-aiohttp
```

--------------------------------

### Install RESPX using pip

Source: https://github.com/openai/openai-python/blob/main/tests/respx2/README.md

Installs the RESPX package into your environment using pip.

```console
$ pip install respx
```

--------------------------------

### Install httpx-aiohttp with httpx2 extra using uv

Source: https://github.com/openai/openai-python/blob/main/src/openai/_vendor/httpx_aiohttp/README.md

Install with the httpx2 extra for httpx2 support, enabling httpx_aiohttp.httpx2.Httpx2AiohttpClient and httpx_aiohttp.httpx2.AiohttpTransport.

```shell
uv pip install httpx-aiohttp[httpx2]
```

--------------------------------

### Check the read-only browser example without an API key

Source: https://github.com/openai/openai-python/blob/main/examples/browser/README_read_only.md

Run the exercise script to test the driver with controlled local API replies. It uses real Chromium and the installed SDK, checks page content changes, refuses outside navigation, and rejects a disabled click.

```sh
.venv-browser/bin/python examples/browser/exercise_read_only.py
```

--------------------------------

### Build and install package from source

Source: https://github.com/openai/openai-python/blob/main/CONTRIBUTING.md

Run ./scripts/build to export dependencies from uv.lock and create wheel and sdist files in dist/, then install the generated .whl with pip.

```sh
$ ./scripts/build
```

```sh
$ pip install ./path-to-wheel-file.whl
```

--------------------------------

### Create an example script in examples/

Source: https://github.com/openai/openai-python/blob/main/CONTRIBUTING.md

Add new examples to the examples/ directory using uv as the python script runner. Files in this directory are not overwritten by code generators.

```py
# add an example to examples/<your-example>.py

#!/usr/bin/env -S uv run python
…
```

--------------------------------

### Install OpenAI Python library from PyPI

Source: https://github.com/openai/openai-python/blob/main/README.md

Install the OpenAI Python library using pip from PyPI.

```sh
# install from PyPI
pip install openai
```

--------------------------------

### Install repository via git

Source: https://github.com/openai/openai-python/blob/main/CONTRIBUTING.md

Install the package directly from the GitHub repository using pip over SSH.

```sh
$ pip install git+ssh://git@github.com/openai/openai-python.git
```

--------------------------------

### Start mock server manually

Source: https://github.com/openai/openai-python/blob/main/CONTRIBUTING.md

Start the Steady mock server manually against the OpenAPI spec if needed before running tests.

```sh
$ ./scripts/mock
```

--------------------------------

### Install aiohttp extra for OpenAI Python SDK

Source: https://github.com/openai/openai-python/blob/main/README.md

Install the aiohttp extra to enable aiohttp as the HTTP transport for the async client, which can improve concurrency performance.

```sh
# install from PyPI
pip install openai[aiohttp]
```

--------------------------------

### Install legacy HTTPX for OpenAI

Source: https://github.com/openai/openai-python/blob/main/httpx2.md

Installs legacy HTTPX alongside the OpenAI SDK as a temporary migration escape hatch. Use this when depending on legacy HTTPX transports, integrations, or mocking libraries.

```sh
pip install openai httpx

```

--------------------------------

### Install and configure legacy httpx-aiohttp client

Source: https://github.com/openai/openai-python/blob/main/httpx2.md

Installs the external httpx-aiohttp adapter and injects HttpxAiohttpClient into AsyncOpenAI using cast(Any, ...). This compatibility path serves as a temporary escape hatch; prefer openai[aiohttp] and DefaultAioHttpClient for new code.

```sh
pip install openai httpx-aiohttp

```

```python
from typing import Any, cast

from httpx_aiohttp import HttpxAiohttpClient
from openai import AsyncOpenAI

client = AsyncOpenAI(http_client=cast(Any, HttpxAiohttpClient()))

```

--------------------------------

### Basic Realtime API text example

Source: https://github.com/openai/openai-python/blob/main/README.md

Connect to the Realtime API using AsyncOpenAI and send a text message. The example updates the session to output text, creates a user message, and processes server events to print the response.

```python
import asyncio
from openai import AsyncOpenAI

async def main():
    client = AsyncOpenAI()

    async with client.realtime.connect(model="gpt-realtime-2") as connection:
        await connection.session.update(
            session={"type": "realtime", "output_modalities": ["text"]}
        )

        await connection.conversation.item.create(
            item={
                "type": "message",
                "role": "user",
                "content": [{"type": "input_text", "text": "Say hello!"}],
            }
        )
        await connection.response.create()

        async for event in connection:
            if event.type == "response.output_text.delta":
                print(event.delta, flush=True, end="")

            elif event.type == "response.output_text.done":
                print()

            elif event.type == "response.done":
                break

asyncio.run(main())
```

--------------------------------

### Install Fieldwork and browser dependency

Source: https://github.com/openai/openai-python/blob/main/examples/browser-use-demo/README.md

Use Python 3.10 or later. From the Python SDK checkout or source archive root, install this source and the browser dependency.

```sh
python3 -m venv .venv-browser
. .venv-browser/bin/activate
python -m pip install -e . playwright==1.63.0
python -m playwright install chromium
```

--------------------------------

### GET /agents/environments/templates

Source: https://github.com/openai/openai-python/blob/main/api.md

Lists all environment templates. Supports pagination.

```APIDOC
## GET /agents/environments/templates

### Description
Lists all environment templates.

### Method
GET

### Endpoint
/agents/environments/templates

### Query Parameters
- **params** (object) - Optional - Parameters for listing templates (e.g., pagination).

### Response
#### Success Response (200)
- **SyncCursorPage[EnvironmentTemplate]** (object) - A paginated list of templates.

#### Response Example
{
  "data": [
    {
      "id": "tmpl_123",
      "name": "My Template",
      "created_at": 1234567890
    }
  ],
  "has_more": false
}
```

--------------------------------

### Install optional Bedrock dependencies

Source: https://github.com/openai/openai-python/blob/main/bedrock.md

Install the optional dependencies required for AWS Signature Version 4 (SigV4) authentication with Amazon Bedrock.

```sh
pip install 'openai[bedrock]'
```

--------------------------------

### GET /agents/environments

Source: https://github.com/openai/openai-python/blob/main/api.md

Lists all environments. Supports pagination via query parameters.

```APIDOC
## GET /agents/environments

### Description
Lists all environments.

### Method
GET

### Endpoint
/agents/environments

### Query Parameters
- **params** (object) - Optional - Parameters for listing environments (e.g., pagination).

### Response
#### Success Response (200)
- **SyncCursorPage[EnvironmentInfo]** (object) - A paginated list of environments.

#### Response Example
{
  "data": [
    {
      "id": "env_123",
      "name": "My Environment",
      "created_at": 1234567890
    }
  ],
  "has_more": false
}
```

--------------------------------

### GET /containers

Source: https://github.com/openai/openai-python/blob/main/api.md

Lists all containers. Supports pagination via query parameters.

```APIDOC
## GET /containers

### Description
Lists all containers.

### Method
GET

### Endpoint
/containers

### Query Parameters
- **params** (ContainerListParams) - Optional - Parameters for pagination and filtering.

### Response
#### Success Response (200)
- **SyncCursorPage[ContainerListResponse]** - A paginated list of containers.

#### Response Example
```json
{
  "data": [
    {
      "id": "container_123",
      "name": "My Container",
      "created_at": "2023-01-01T00:00:00Z"
    }
  ],
  "has_more": false
}
```
```

--------------------------------

### Run setup with --media-dir

Source: https://github.com/openai/openai-python/blob/main/examples/computer-desktop/guest/README.md

Use this command to set up the runtime from an existing media directory. The --media-dir must point to an absolute path containing the required files.

```sh
python3 examples/computer-desktop/guest/setup.py \
  --runtime-dir /private/tmp/desktop-$UID --media-dir /absolute/path/to/media
```

--------------------------------

### Set up container backend with setup.py

Source: https://github.com/openai/openai-python/blob/main/examples/computer-desktop/guest/README.md

Run this command on an x86-64 Linux host with Docker to select the container backend. Requires Python 3.10+, Docker daemon accessible via /var/run/docker.sock, and a clear Docker context. The setup builds a local image and records it in setup.json.

```sh
python3 examples/computer-desktop/guest/setup.py \
  --backend container --runtime-dir /tmp/desktop-$UID
```

--------------------------------

### GET /organization/external_storage

Source: https://github.com/openai/openai-python/blob/main/api.md

Lists all external storage configurations for the organization. Supports pagination.

```APIDOC
## GET /organization/external_storage

### Description
Lists all external storage configurations.

### Method
GET

### Endpoint
/organization/external_storage

### Parameters
#### Query Parameters
- **params** (object) - Optional - Parameters for pagination and filtering.

### Response
#### Success Response (200)
- **SyncCursorPage[ExternalStorageConfiguration]** (object) - A paginated list of external storage configurations.

#### Response Example
{
  "data": [
    {
      "id": "storage_123",
      "provider": "aws",
      "bucket": "my-bucket"
    }
  ],
  "next_cursor": "cursor_abc"
}
```

--------------------------------

### Run setup with default tool paths

Source: https://github.com/openai/openai-python/blob/main/examples/computer-desktop/guest/README.md

Run this command from the SDK source root on an Apple-silicon Mac to set up the guest. It requires vfkit and xorriso on PATH and creates a private runtime directory.

```sh
python3 examples/computer-desktop/guest/setup.py --runtime-dir /private/tmp/desktop-$UID
```

--------------------------------

### Run setup with custom vfkit and xorriso paths

Source: https://github.com/openai/openai-python/blob/main/examples/computer-desktop/guest/README.md

Use this command if vfkit and xorriso are not on PATH. Provide absolute paths to the executables.

```sh
python3 examples/computer-desktop/guest/setup.py \
  --runtime-dir /private/tmp/desktop-$UID \
  --vfkit /absolute/path/to/vfkit --xorriso /absolute/path/to/xorriso
```

--------------------------------

### Stage files and download a turn artifact

Source: https://github.com/openai/openai-python/blob/main/helpers.md

Prepare files, create a session, stream input, and download the resulting artifact. Use `prepare_directory` for directory snapshots or `files.upload` for existing environments. With `AsyncOpenAI`, await preparation, staging, and artifact downloads.

```python
from pathlib import Path

prepared = client.beta.agents.environments.files.prepare({
    "/workspace/source.pdf": Path("source.pdf"),
})
session = client.beta.agents.sessions.create(
    agent={"model": MODEL},
    environment={"type": "openai_hosted", "files": prepared.files},
)
with client.beta.agents.sessions.stream(
    session.id, input="Read source.pdf and write /workspace/outputs/report.md."
) as stream:
    result = stream.get_final_result()

artifacts = client.beta.agents.sessions.artifacts.for_result(result)

# Read in memory, or stream to an application-owned local path.
report_bytes = artifacts.content("/workspace/outputs/report.md").content
artifact = artifacts.download(
    "/workspace/outputs/report.md", to=Path("downloaded-report.md")
)
```

--------------------------------

### GET /evals/{eval_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves an evaluation by its ID. Use this to get details about a specific eval.

```APIDOC
## GET /evals/{eval_id}

### Description
Retrieves an evaluation by its ID.

### Method
GET

### Endpoint
/evals/{eval_id}

### Parameters
#### Path Parameters
- **eval_id** (string) - Required - The ID of the eval to retrieve.

### Response
#### Success Response (200)
- **EvalRetrieveResponse** - The retrieved eval object.

### Example
```python
from openai import OpenAI

client = OpenAI()

eval = client.evals.retrieve("eval_id")
print(eval)
```
```

--------------------------------

### Set up VM on Apple-silicon Mac

Source: https://github.com/openai/openai-python/blob/main/examples/computer-desktop/README.md

Set up the VM on an Apple-silicon Mac using vfkit and xorriso.

```sh
python examples/computer-desktop/guest/setup.py --runtime-dir "/tmp/desktop-$(id -u)"
```

--------------------------------

### GET /responses/{response_id}

Source: https://github.com/openai/openai-python/blob/main/src/openai/resources/responses/api.md

Retrieves a response by its ID. Use this endpoint to get details about a specific response.

```APIDOC
## GET /responses/{response_id}

### Description
Retrieves a response by its ID.

### Method
GET

### Endpoint
/responses/{response_id}

### Parameters
#### Path Parameters
- **response_id** (string) - Required - The ID of the response to retrieve.

#### Query Parameters
- **params** (object) - Optional - Additional parameters for retrieval.

### Response
#### Success Response (200)
- **Response** (object) - The retrieved response object.

#### Response Example
{
  "id": "resp_123",
  "object": "response",
  "created": 1234567890,
  "model": "gpt-4",
  "choices": [
    {
      "text": "Hello!",
      "index": 0
    }
  ]
}
```

--------------------------------

### Set up container on x86-64 Linux

Source: https://github.com/openai/openai-python/blob/main/examples/computer-desktop/README.md

Set up the container on x86-64 Linux with local Docker.

```sh
python examples/computer-desktop/guest/setup.py --backend container --runtime-dir "/tmp/desktop-$(id -u)"
```

--------------------------------

### Bootstrap the development environment with ./scripts/bootstrap

Source: https://github.com/openai/openai-python/blob/main/CONTRIBUTING.md

Installs all SDK extras and Python development tools from uv.lock alongside contributor tools from pnpm-lock.yaml. Requires pre-installed Node.js and pnpm matching the repository specifications.

```sh
$ ./scripts/bootstrap
```

--------------------------------

### GET /videos/characters/{character_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves information about a specific character by its ID. Use this endpoint to get details of a character.

```APIDOC
## GET /videos/characters/{character_id}

### Description
Retrieves information about a specific character by its ID. Use this endpoint to get details of a character.

### Method
GET

### Endpoint
/videos/characters/{character_id}

### Parameters
#### Path Parameters
- **character_id** (string) - Required - The unique identifier of the character.

### Response
#### Success Response (200)
- **VideoGetCharacterResponse** (object) - The character object.

#### Response Example
{
  "id": "char_123",
  "name": "John Doe"
}
```

--------------------------------

### Run no-key exercise with runtime path

Source: https://github.com/openai/openai-python/blob/main/examples/computer-desktop/guest/README.md

After setup, run the exercise using the same runtime directory. This executes the fixed synthetic offline browser and editor exercise with real screenshots and input.

```sh
python examples/computer-desktop/exercise.py --runtime-dir /tmp/desktop-$UID
```

--------------------------------

### GET /batches/{batch_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves a batch by its ID. This method allows you to get the status and details of a specific batch.

```APIDOC
## GET /batches/{batch_id}

### Description
Retrieves a batch by its ID.

### Method
GET

### Endpoint
/batches/{batch_id}

### Parameters
#### Path Parameters
- **batch_id** (string) - Required - The ID of the batch to retrieve.

### Response
#### Success Response (200)
- **Batch** - The requested batch object.

#### Response Example
```json
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "completed",
  "output_file_id": "file-abc456",
  "error_file_id": null,
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": 1711557933,
  "finalizing_at": 1711493133,
  "completed_at": 1711493163,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 95,
    "failed": 5
  },
  "metadata": {}
}
```
```

--------------------------------

### GET /agents/sessions/{session_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves an existing agent session by its ID. Use this endpoint to get details about a specific session.

```APIDOC
## GET /agents/sessions/{session_id}

### Description
Retrieves an agent session by ID.

### Method
GET

### Endpoint
/agents/sessions/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session to retrieve.

### Response
#### Success Response (200)
- **AgentSession** (object) - The requested session object.

#### Response Example
{
  "id": "session_123",
  "object": "agent.session",
  "created_at": 1234567890,
  "agent_id": "agent_456"
}
```

--------------------------------

### GET /agents/{agent_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves an existing agent by its unique identifier. Use this endpoint to get details about a specific agent.

```APIDOC
## GET /agents/{agent_id}

### Description
Retrieves an existing agent by its unique identifier.

### Method
GET

### Endpoint
/agents/{agent_id}

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The ID of the agent to retrieve.

### Response
Returns an Agent object.

### Response Example
```json
{
  "id": "agent_123",
  "object": "agent",
  "created_at": 1710000000,
  "name": "My Agent",
  "description": "An example agent",
  "model": "gpt-4",
  "instructions": "You are a helpful assistant.",
  "tools": [],
  "metadata": {}
}
```
```

--------------------------------

### GET /organization/projects/{project_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves details of a specific project by its ID. Use this to get information about a project's configuration and status.

```APIDOC
## GET /organization/projects/{project_id}

### Description
Retrieves details of a specific project.

### Method
GET

### Endpoint
/organization/projects/{project_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project to retrieve.

### Response
#### Success Response (200)
- **Project** (object) - The project object.

#### Response Example
{
  "id": "proj_123",
  "name": "My Project",
  "created_at": 1680000000
}
```

--------------------------------

### Start the Fieldwork server

Source: https://github.com/openai/openai-python/blob/main/examples/browser-use-demo/README.md

Start the server in the same shell. Open the private URL printed in your terminal. Rehearsal uses Decisions to choose among local scripted actions and makes no model request. For Live mode, set OPENAI_API_KEY and OPENAI_MODEL on the server before launch. Live defaults to Responses; select Decisions to compare the candidate-based runner. API-specific model names can use OPENAI_RESPONSES_MODEL and OPENAI_DECISIONS_MODEL. Live requests can spend API credits.

```sh
python examples/browser-use-demo/server.py
```

--------------------------------

### GET /organization/certificates/{certificate_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves details of a specific certificate by its ID. Use this to get information about a certificate's status and metadata.

```APIDOC
## GET /organization/certificates/{certificate_id}

### Description
Retrieves details of a specific certificate.

### Method
GET

### Endpoint
/organization/certificates/{certificate_id}

### Parameters
#### Path Parameters
- **certificate_id** (string) - Required - The ID of the certificate to retrieve.

#### Query Parameters
- **params** (object) - Optional - Additional parameters for the request.

### Response
#### Success Response (200)
- **Certificate** (object) - The certificate object.

#### Response Example
{
  "id": "cert_123",
  "name": "My Certificate",
  "created_at": 1680000000
}
```

--------------------------------

### Import BrowserReadV1 and create a structured page read

Source: https://github.com/openai/openai-python/blob/main/docs/browser.md

Use this to construct a `BrowserReadV1` dictionary. The example shows the required `version`, `text`, and `elements` fields, plus an optional `omitted` list.

```python
from openai.lib.browser import BrowserReadV1

read: BrowserReadV1 = {
    "version": 1,
    "text": "Dispatch queue",
    "elements": [{"ref": "current-button", "role": "button", "label": "Dispatch BP-1207"}],
    "omitted": ["value"],
}
```

--------------------------------

### GET /organization/roles/{role_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves details of a specific role by its ID. Use this to get information about a role's permissions and settings.

```APIDOC
## GET /organization/roles/{role_id}

### Description
Retrieves details of a specific role.

### Method
GET

### Endpoint
/organization/roles/{role_id}

### Parameters
#### Path Parameters
- **role_id** (string) - Required - The ID of the role to retrieve.

### Response
#### Success Response (200)
- **Role** (object) - The requested role object.

#### Response Example
{
  "id": "role_123",
  "name": "Custom Role",
  "permissions": ["read", "write"]
}
```

--------------------------------

### client.beta.agents.environments.files.prepare_directory

Source: https://github.com/openai/openai-python/blob/main/helpers.md

Prepares a directory snapshot for upload to an agent environment. Allows selection of files using glob patterns.

```APIDOC
## client.beta.agents.environments.files.prepare_directory

### Description
Prepares a directory snapshot for upload to an agent environment. Allows selection of files using glob patterns.

### Method
SDK method

### Endpoint
client.beta.agents.environments.files.prepare_directory

### Parameters
- **source_dir** (str) - Required - The local directory to prepare.
- **destination** (str) - Required - The destination path in the workspace.
- **include** (list) - Optional - List of glob patterns to include.

### Request Example
```python
prepared = client.beta.agents.environments.files.prepare_directory(
    "docs", destination="/workspace/docs", include=["**/*.md"]
)
```

### Response
Returns a prepared object similar to `prepare`.

```

--------------------------------

### GET /organization/users/{user_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves details of a specific user in the organization. Use this to get information about a user's profile and status.

```APIDOC
## GET /organization/users/{user_id}

### Description
Retrieves details of a specific user.

### Method
GET

### Endpoint
/organization/users/{user_id}

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The ID of the user to retrieve.

### Response
#### Success Response (200)
- **OrganizationUser** (object) - The user object.

#### Response Example
{
  "id": "user_123",
  "email": "user@example.com",
  "name": "John Doe",
  "status": "active"
}
```

--------------------------------

### GET /threads/{thread_id}/messages/{message_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieve a message from a thread. This method allows you to get details of a specific message by its ID.

```APIDOC
## GET /threads/{thread_id}/messages/{message_id}

### Description
Retrieve a message from a thread.

### Method
GET

### Endpoint
/threads/{thread_id}/messages/{message_id}

### Parameters
#### Path Parameters
- **thread_id** (string) - Required - The ID of the thread the message belongs to.
- **message_id** (string) - Required - The ID of the message to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The identifier of the message.
- **content** (array) - The content of the message.
- **role** (string) - The role of the entity that created the message.
- **thread_id** (string) - The ID of the thread the message belongs to.
- **created_at** (integer) - The Unix timestamp (in seconds) for when the message was created.
- **metadata** (object) - Set of 16 key-value pairs that can be attached to an object.

#### Response Example
{
  "id": "msg_abc123",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "Hello, world!",
        "annotations": []
      }
    }
  ],
  "role": "user",
  "thread_id": "thread_abc123",
  "created_at": 1698983503,
  "metadata": {}
}
```

--------------------------------

### GET /agents/sessions/{session_id}/subagents/{subagent_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves a specific subagent within a session. Use this endpoint to get details about a subagent.

```APIDOC
## GET /agents/sessions/{session_id}/subagents/{subagent_id}

### Description
Retrieves a subagent by ID.

### Method
GET

### Endpoint
/agents/sessions/{session_id}/subagents/{subagent_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session.
- **subagent_id** (string) - Required - The ID of the subagent to retrieve.

### Response
#### Success Response (200)
- **Subagent** (object) - The requested subagent object.

#### Response Example
{
  "id": "subagent_789",
  "object": "agent.subagent",
  "session_id": "session_123",
  "created_at": 1234567890
}
```

--------------------------------

### client.beta.agents.environments.files.prepare

Source: https://github.com/openai/openai-python/blob/main/helpers.md

Prepares files for upload to an agent environment by mapping local paths to workspace paths. Returns a prepared object containing file information and uploaded file IDs.

```APIDOC
## client.beta.agents.environments.files.prepare

### Description
Prepares files for upload to an agent environment by mapping local paths to workspace paths. Returns a prepared object containing file information and uploaded file IDs.

### Method
SDK method

### Endpoint
client.beta.agents.environments.files.prepare

### Parameters
- **files** (dict) - Required - A dictionary mapping workspace paths to local file paths or file-like objects.

### Request Example
```python
from pathlib import Path

prepared = client.beta.agents.environments.files.prepare({
    "/workspace/source.pdf": Path("source.pdf"),
})
```

### Response
Returns a prepared object with attributes:
- **files** - The prepared files to be used in environment configuration.
- **uploaded_file_ids** - IDs of uploaded files for use with the Files API.
- **error** - If preparation fails, contains a `prepared` attribute with partial uploads.

```

--------------------------------

### GET /evals/{eval_id}/runs/{run_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves a specific run for an evaluation. Use this to get details about a run's status and results.

```APIDOC
## GET /evals/{eval_id}/runs/{run_id}

### Description
Retrieves a specific run for an evaluation.

### Method
GET

### Endpoint
/evals/{eval_id}/runs/{run_id}

### Parameters
#### Path Parameters
- **eval_id** (string) - Required - The ID of the eval.
- **run_id** (string) - Required - The ID of the run.

### Response
#### Success Response (200)
- **RunRetrieveResponse** - The retrieved run object.

### Example
```python
from openai import OpenAI

client = OpenAI()

run = client.evals.runs.retrieve(
    "run_id",
    eval_id="eval_id"
)
print(run)
```
```

--------------------------------

### GET /organization/projects/{project_id}/groups/{group_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves details of a specific group within a project. Use this to get information about a group by its ID.

```APIDOC
## GET /organization/projects/{project_id}/groups/{group_id}

### Description
Retrieves details of a specific group within a project.

### Method
GET

### Endpoint
/organization/projects/{project_id}/groups/{group_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **group_id** (string) - Required - The ID of the group to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The group ID.
- **name** (string) - The group name.
- **created_at** (integer) - Unix timestamp of when the group was created.

#### Response Example
{
  "id": "group_abc123",
  "name": "My Group",
  "created_at": 1710000000
}
```

--------------------------------

### Required media directory structure

Source: https://github.com/openai/openai-python/blob/main/examples/computer-desktop/guest/README.md

The --media-dir option expects this directory layout with the Debian DVD ISO and two extra .deb packages. Setup copies and verifies these files before use.

```text
media/
  debian-12.13.0-arm64-DVD-1.iso
  extra/xdotool_3.20160805.1-5_arm64.deb
  extra/xvfb_21.1.7-3+deb12u11_arm64.deb
```

--------------------------------

### GET /agents/sessions/{session_id}/turns/{turn_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves a specific turn from an agent session. Use this endpoint to get details about a particular turn.

```APIDOC
## GET /agents/sessions/{session_id}/turns/{turn_id}

### Description
Retrieves a specific turn from an agent session.

### Method
GET

### Endpoint
/agents/sessions/{session_id}/turns/{turn_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session.
- **turn_id** (string) - Required - The ID of the turn to retrieve.

### Response
#### Success Response (200)
- **Turn** - The requested turn object.

#### Response Example
```json
{
  "id": "turn_abc123",
  "object": "session.turn",
  "created_at": 1710000000,
  "session_id": "session_xyz789",
  "status": "completed"
}
```
```

--------------------------------

### GET /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves a specific turn within a subagent. Use this endpoint to get details about a turn.

```APIDOC
## GET /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}

### Description
Retrieves a turn by ID.

### Method
GET

### Endpoint
/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session.
- **subagent_id** (string) - Required - The ID of the subagent.
- **turn_id** (string) - Required - The ID of the turn to retrieve.

### Response
#### Success Response (200)
- **Turn** (object) - The requested turn object.

#### Response Example
{
  "id": "turn_202",
  "object": "agent.turn",
  "subagent_id": "subagent_789",
  "created_at": 1234567890
}
```

--------------------------------

### client.beta.agents.sessions.create

Source: https://github.com/openai/openai-python/blob/main/helpers.md

Creates a new agent session with a specified agent and environment configuration. The environment can include prepared files.

```APIDOC
## client.beta.agents.sessions.create

### Description
Creates a new agent session with a specified agent and environment configuration. The environment can include prepared files.

### Method
SDK method

### Endpoint
client.beta.agents.sessions.create

### Parameters
- **agent** (dict) - Required - Configuration for the agent, including the model.
- **environment** (dict) - Required - Configuration for the environment, including type and files.

### Request Example
```python
session = client.beta.agents.sessions.create(
    agent={"model": MODEL},
    environment={"type": "openai_hosted", "files": prepared.files},
)
```

### Response
Returns a session object with an `id` attribute.

```

--------------------------------

### Enable aiohttp transport with DefaultAioHttpClient

Source: https://github.com/openai/openai-python/blob/main/README.md

Instantiate AsyncOpenAI with http_client=DefaultAioHttpClient() to use aiohttp as the HTTP transport. Requires the aiohttp extra to be installed.

```python
import os
import asyncio
from openai import DefaultAioHttpClient
from openai import AsyncOpenAI


async def main() -> None:
    async with AsyncOpenAI(
        api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
        http_client=DefaultAioHttpClient(),
    ) as client:
        chat_completion = await client.chat.completions.create(
            messages=[
                {
                    "role": "user",
                    "content": "Say this is a test",
                }
            ],
            model="gpt-5.5",
        )


asyncio.run(main())
```

--------------------------------

### GET /projects/{project_id}/roles/{role_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves details of a specific role within a project. Use this to get information about a role's permissions and metadata.

```APIDOC
## GET /projects/{project_id}/roles/{role_id}

### Description
Retrieves details of a specific role within a project. Use this to get information about a role's permissions and metadata.

### Method
GET

### Endpoint
/projects/{project_id}/roles/{role_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **role_id** (string) - Required - The ID of the role to retrieve.

### Response
#### Success Response (200)
- **Role** (object) - The requested role object.

#### Response Example
{
  "id": "role_abc123",
  "name": "Custom Role",
  "description": "A custom role for project members",
  "permissions": ["read", "write"],
  "created_at": 1698765432
}
```

--------------------------------

### Run test suite

Source: https://github.com/openai/openai-python/blob/main/CONTRIBUTING.md

Execute tests using ./scripts/test, which automatically starts the Steady mock server if one is not already running.

```sh
$ ./scripts/test
```

--------------------------------

### GET /organization/projects/{project_id}/api_keys/{api_key_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves details of a specific API key within a project. Use this to get information about an existing API key.

```APIDOC
## GET /organization/projects/{project_id}/api_keys/{api_key_id}

### Description
Retrieves details of a specific API key within a project.

### Method
GET

### Endpoint
/organization/projects/{project_id}/api_keys/{api_key_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **api_key_id** (string) - Required - The ID of the API key.

### Response
#### Success Response (200)
- **ProjectAPIKey** (object) - The API key details.

#### Response Example
{
  "id": "key_abc123",
  "name": "My API Key",
  "created_at": 1710000000
}
```

--------------------------------

### client.beta.agents.sessions.create

Source: https://github.com/openai/openai-python/blob/main/helpers.md

Creates a new beta Agents session with the specified agent configuration, environment, input, and optional tools and output type. Supports streaming and tool handlers.

```APIDOC
## client.beta.agents.sessions.create

### Description
Creates a new beta Agents session with the specified agent configuration, environment, input, and optional tools and output type. Supports streaming and tool handlers.

### Signature
```python
client.beta.agents.sessions.create(
    agent: dict,
    environment: dict,
    input: str,
    stream: bool = False,
    tools: list = None,
    tool_handlers: dict = None,
    output_type: Type[BaseModel] = None,
    on_tool_error: Callable = None,
    **kwargs
) -> Session or Stream
```

### Parameters
- **agent** (dict) - Required - Configuration for the agent, including model and tools.
- **environment** (dict) - Required - Environment configuration, e.g., `{"type": "none"}`.
- **input** (str) - Required - The input prompt for the session.
- **stream** (bool) - Optional - If True, returns a stream context manager. Defaults to False.
- **tools** (list) - Optional - List of tool definitions to use in the session.
- **tool_handlers** (dict) - Optional - Mapping of tool names to handler functions.
- **output_type** (Type[BaseModel]) - Optional - Pydantic model for parsing the output.
- **on_tool_error** (Callable) - Optional - Callback for tool errors.

### Returns
- **Session or Stream** - If `stream=True`, returns a stream context manager; otherwise, returns a Session object.

### Example
```python
with client.beta.agents.sessions.create(
    agent={"model": MODEL, "tools": [lookup.definition]},
    environment={"type": "none"}, input="Find catalog item A123.",
    stream=True, tool_handlers={lookup.name: lookup},
) as stream:
    print(stream.get_final_result().output_text)
```

### Notes
- Creation requires `stream=True` when using `tool_handlers`.
- For typed output, pass a Pydantic model to `output_type`.
```

--------------------------------

### GET /organization/projects/{project_id}/service_accounts/{service_account_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves details of a specific service account within a project. Use this to get information about an existing service account.

```APIDOC
## GET /organization/projects/{project_id}/service_accounts/{service_account_id}

### Description
Retrieves details of a specific service account within a project.

### Method
GET

### Endpoint
/organization/projects/{project_id}/service_accounts/{service_account_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **service_account_id** (string) - Required - The ID of the service account.

### Response
#### Success Response (200)
- **ProjectServiceAccount** (object) - The service account details.

#### Response Example
{
  "id": "sa_abc123",
  "name": "My Service Account",
  "created_at": 1710000000
}
```

--------------------------------

### GET /agents/sessions/{session_id}/artifacts/{artifact_id}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves a specific artifact from an agent session. Use this endpoint to get details about a particular artifact generated during the session.

```APIDOC
## GET /agents/sessions/{session_id}/artifacts/{artifact_id}

### Description
Retrieves a specific artifact from an agent session.

### Method
GET

### Endpoint
/agents/sessions/{session_id}/artifacts/{artifact_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session.
- **artifact_id** (string) - Required - The ID of the artifact to retrieve.

### Response
#### Success Response (200)
- **SessionArtifact** - The requested artifact object.

#### Response Example
```json
{
  "id": "artifact_abc123",
  "object": "session.artifact",
  "created_at": 1710000000,
  "session_id": "session_xyz789",
  "type": "file",
  "data": {
    "file_id": "file_123"
  }
}
```
```

--------------------------------

### GET /models/{model}

Source: https://github.com/openai/openai-python/blob/main/api.md

Retrieves details about a specific model available in the OpenAI API. Use this to get information such as the model's owner and creation date.

```APIDOC
## GET /models/{model}

### Description
Retrieves details about a specific model available in the OpenAI API. Use this to get information such as the model's owner and creation date.

### Method
GET

### Endpoint
/models/{model}

### Parameters
#### Path Parameters
- **model** (string) - Required - The ID of the model to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The model ID.
- **object** (string) - The object type, which is always "model".
- **created** (integer) - The Unix timestamp (in seconds) when the model was created.
- **owned_by** (string) - The organization that owns the model.

#### Response Example
{
  "id": "gpt-3.5-turbo",
  "object": "model",
  "created": 1677610602,
  "owned_by": "openai"
}
```

--------------------------------

### Configure AsyncOpenAI with DefaultAioHttpClient

Source: https://github.com/openai/openai-python/blob/main/httpx2.md

Installs the supported aiohttp extra and configures AsyncOpenAI with DefaultAioHttpClient. DefaultAioHttpClient is an httpx2.AsyncClient, eliminating the need to directly import or construct the transport.

```sh
pip install 'openai[aiohttp]'

```

```python
from openai import AsyncOpenAI, DefaultAioHttpClient

client = AsyncOpenAI(http_client=DefaultAioHttpClient())

```

--------------------------------

### Configure custom HTTPX2 clients with DefaultHttpx2Client and DefaultAsyncHttpx2Client

Source: https://github.com/openai/openai-python/blob/main/httpx2.md

Use DefaultHttpx2Client and DefaultAsyncHttpx2Client helpers to customize proxy, transport, or timeout settings while preserving recommended SDK defaults for connection pooling and redirects.

```python
import httpx2
from openai import OpenAI, AsyncOpenAI, DefaultHttpx2Client, DefaultAsyncHttpx2Client

proxy_client = OpenAI(http_client=DefaultHttpx2Client(proxy="http://proxy.example.com:8080"))

transport_client = OpenAI(
    http_client=DefaultHttpx2Client(
        transport=httpx2.HTTPTransport(local_address="0.0.0.0"),
        timeout=httpx2.Timeout(30.0, connect=5.0),
    )
)

async_client = AsyncOpenAI(http_client=DefaultAsyncHttpx2Client(timeout=httpx2.Timeout(30.0)))
```

--------------------------------

### GET /vaults

Source: https://github.com/openai/openai-python/blob/main/api.md

Lists all vaults.

```APIDOC
## GET /vaults

### Description
Lists all vaults.

### Method
GET

### Endpoint
/vaults

### Parameters
#### Query Parameters
- **params** (object) - Optional - Parameters for filtering and pagination.

### Response
#### Success Response (200)
- **SyncCursorPage[Vault]** (object) - A paginated list of vaults.

#### Response Example
{
  "data": [
    {
      "id": "vault_123",
      "name": "My Vault",
      "status": "active",
      "created_at": "2023-01-01T00:00:00Z"
    }
  ],
  "has_more": false
}
```

--------------------------------

### Determine the installed openai-python version

Source: https://github.com/openai/openai-python/blob/main/README.md

Use this to check which version of the openai package is currently installed in your Python environment. This is helpful when you have upgraded but are not seeing expected new features, as your environment might still be using an older version.

```python
import openai
print(openai.__version__)
```

--------------------------------

### Create stream with new message and run

Source: https://github.com/openai/openai-python/blob/main/helpers.md

Use `client.beta.threads.create_and_run_stream()` to add a message to a thread, start a run, and then stream the response.

```python
client.beta.threads.create_and_run_stream()
```
Tokens:
Raw