Reference — Spybara

Files

go
- index.md
java
- index.md
python
- index.md
ruby
- index.md

go/index.md +1 −1

Details

3030

31 31

32```sh32```sh

~~33go get -u 'github.com/openai/openai-go/v3@v3.51.0'~~33go get -u 'github.com/openai/openai-go/v3@v3.52.0'

34```34```

35 35

3636

java/index.md +3 −3

Details

15### Gradle15### Gradle

16 16

17```kotlin17```kotlin

~~18implementation("com.openai:openai-java:4.51.0")~~18implementation("com.openai:openai-java:4.52.0")

19```19```

20 20

21### Maven21### Maven

24<dependency>24<dependency>

25 <groupId>com.openai</groupId>25 <groupId>com.openai</groupId>

26 <artifactId>openai-java</artifactId>26 <artifactId>openai-java</artifactId>

~~27 <version>4.51.0</version>~~27 <version>4.52.0</version>

28</dependency>28</dependency>

29```29```

30 30

8787

88 88

89```kotlin89```kotlin

~~90implementation("com.openai:openai-java-bedrock:4.51.0")~~90implementation("com.openai:openai-java-bedrock:4.52.0")

91```91```

92 92

9393

python/index.md +68 −7

Details

167)167)

168```168```

169 169

170#### X.509 workload identity (mutual TLS)

171

172For X.509 workload identity federation, configure the client certificate and

173server trust on an HTTPX2 client, then pass only the identity-provider and

174service-account IDs to the SDK:

175

176```python

177import os

178import ssl

179

180from openai import OpenAI, DefaultHttpx2Client

181from openai.auth import x509_workload_identity

182

183tls_context = ssl.create_default_context(

184 cafile=os.getenv("OPENAI_MTLS_CA_BUNDLE"),

185)

186tls_context.load_cert_chain(

187 certfile=os.environ["OPENAI_MTLS_CERTIFICATE_CHAIN"],

188 keyfile=os.environ["OPENAI_MTLS_PRIVATE_KEY"],

189 password=os.getenv("OPENAI_MTLS_PRIVATE_KEY_PASSWORD"),

190)

191

192client = OpenAI(

193 workload_identity=x509_workload_identity(

194 identity_provider_id=os.environ["OPENAI_IDENTITY_PROVIDER_ID"],

195 service_account_id=os.environ["OPENAI_SERVICE_ACCOUNT_ID"],

196 # refresh_buffer_seconds=120.0,

197 ),

198 http_client=DefaultHttpx2Client(

199 verify=tls_context,

200 follow_redirects=False,

201 ),

202)

203```

204

205X.509 mode defaults to `https://mtls.api.openai.com/v1` when neither `base_url`

206nor `OPENAI_BASE_URL` is set. The same configured HTTP client presents its

207certificate to the fixed mTLS token-exchange endpoint and to the API. Tokens

208are exchanged lazily, cached, and refreshed automatically. Certificate files,

209private keys, passwords, server trust, proxies, and rotation remain application

210and transport concerns.

211

212X.509 API requests require HTTPS and must stay on the configured API origin.

213The effective HTTP Host authority must match that origin.

214Provider API-key and proxy-only headers cannot be sent to the API alongside

215X.509 authentication.

216Token exchanges do not inherit API request hooks, authentication, or cookies.

217Identity settings are captured when the client is constructed; create a new

218client to change the identity. Azure clients do not support X.509 workload

219identity.

220

221For asynchronous requests, use `AsyncOpenAI` with

222`DefaultAsyncHttpx2Client`. See the complete [sync rollout-toggle

223example](examples/x509_workload_identity.py) and [async rollout-toggle

224example](examples/x509_workload_identity_async.py), which select API-key or

225X.509 authentication with the application-owned `OPENAI_AUTH_MODE`

226environment variable. X.509 workload identity currently supports HTTP APIs;

227Realtime and WebSockets are not included.

228

170### Vision229### Vision

171 230

172With an image URL:231With an image URL:

950See the complete [sync HTTPX2](examples/mtls_httpx2.py) and1009See the complete [sync HTTPX2](examples/mtls_httpx2.py) and

951[async HTTPX2](examples/mtls_httpx2_async.py) examples.1010[async HTTPX2](examples/mtls_httpx2_async.py) examples.

952 1011

953The certificate-bearing HTTP client is transport-wide. Dedicate it to the1012The certificate-bearing HTTP client is transport-wide. For API-key mTLS,

954selected mTLS origin; do not reuse it for other services or pass it through1013dedicate it to the selected API origin; X.509 workload identity also uses the

955`with_options()` with a different `base_url`. If redirects are required, add an1014fixed OpenAI mTLS token-exchange origin. Do not reuse the client for unrelated

1015services or pass it through `with_options()` with a different `base_url`.

1016If redirects are required for API-key mTLS, add an

956HTTPX2 request hook that rejects requests whose scheme, host, or port differs1017HTTPX2 request hook that rejects requests whose scheme, host, or port differs

957from the configured mTLS origin before enabling `follow_redirects`.1018from the configured mTLS origin before enabling `follow_redirects`.

958 1019

969client after its in-flight requests finish. Do not assume existing TLS1030client after its in-flight requests finish. Do not assume existing TLS

970connections will renegotiate.1031connections will renegotiate.

971 1032

972This recipe applies to ordinary API-key HTTP traffic. It does not implement1033This recipe applies to ordinary API-key HTTP traffic. For certificate-backed

973certificate-only X.509 workload identity, token exchange, or Realtime WebSocket1034token exchange, use the X.509 workload identity configuration described above.

974mTLS.1035Realtime WebSocket mTLS is not included.

975 1036

976### Managing HTTP resources1037### Managing HTTP resources

977 1038

1073 1134

1074You can also pass `access_key_id` and `secret_access_key`, with an optional `session_token`, or a refreshable `credential_provider` that returns botocore-compatible credentials. Explicit bearer and AWS credential options are mutually exclusive.1135You can also pass `access_key_id` and `secret_access_key`, with an optional `session_token`, or a refreshable `credential_provider` that returns botocore-compatible credentials. Explicit bearer and AWS credential options are mutually exclusive.

1075 1136

1076Pass `base_url` to `bedrock(...)` or set `AWS_BEDROCK_BASE_URL` to override the derived `https://bedrock-mantle.<region>.api.aws/openai/v1` endpoint.1137Pass `base_url` to `bedrock(...)` or set `AWS_BEDROCK_BASE_URL` to override the derived `https://bedrock-mantle.<region>.api.aws/openai/v1` endpoint. Custom URLs retain Mantle signing by default; pass `endpoint="runtime"` to use Runtime signing.

1077 1138

1078SigV4 requests require replayable, fully serialized request bodies. Standard JSON requests already meet this requirement, and response streaming is unaffected. Low-level one-shot request streams must be buffered before sending, or sent with bearer authentication and retries disabled.1139SigV4 requests require replayable, fully serialized request bodies. Standard JSON requests already meet this requirement, and response streaming is unaffected. Low-level one-shot request streams must be buffered before sending, or sent with bearer authentication and retries disabled.

1079 1140

ruby/index.md +48 −2

Details

1515

16 16

17```ruby17```ruby

~~18gem "openai", "~> 0.79.0"~~18gem "openai", "~> 0.80.0"

19```19```

20 20

2121

112image = OpenAI::FilePart.new(Pathname("dog.jpg"), content_type: "image/jpeg")112image = OpenAI::FilePart.new(Pathname("dog.jpg"), content_type: "image/jpeg")

113edited = openai.images.edit(113edited = openai.images.edit(

114 prompt: "make this image look like a painting",114 prompt: "make this image look like a painting",

115 model: "gpt-image-1",115 model: "gpt-image-2",

116 size: "1024x1024",116 size: "1024x1024",

117 image: image117 image: image

118)118)

122 122

123Note that you can also pass a raw `IO` descriptor, but this disables retries, as the library can't be sure if the descriptor is a file or pipe (which cannot be rewound).123Note that you can also pass a raw `IO` descriptor, but this disables retries, as the library can't be sure if the descriptor is a file or pipe (which cannot be rewound).

124 124

125#### Polling and vector store ingestion

126

127Polling helpers wait for file processing and return the final resource. Durations are

128expressed in seconds. By default, the helpers honor the API's recommended polling

129interval, fall back to 5 seconds, and stop after 30 minutes. Pass `timeout: nil` to

130wait indefinitely.

131

132To keep a finite overall deadline strict, each polling retrieval includes

133authentication and request replay time and does not perform transport-level retries.

134Pass `timeout: nil` to retain the client's configured retry behavior.

135

136```ruby

137file = openai.files.wait_for_processing(

138 file_object.id,

139 poll_interval: 2,

140 timeout: 10 * 60

141)

142

143vector_file = openai.vector_stores.files.upload_and_poll(

144 vector_store.id,

145 file: Pathname("handbook.pdf"),

146 attributes: {department: "engineering"}

147)

148

149batch = openai.vector_stores.file_batches.upload_and_poll(

150 vector_store.id,

151 files: [Pathname("one.pdf"), Pathname("two.pdf")],

152 file_ids: [file_object.id],

153 max_concurrency: 3

154)

155```

156

157The vector store helpers return terminal `failed` and `cancelled` resources instead

158of raising, so inspect `status`, `last_error`, or `file_counts` as appropriate. An

159overall polling timeout raises `OpenAI::Errors::PollingTimeoutError`; its `resource`

160attribute contains the last object returned by the API, or `nil` if the deadline

161elapsed before the first response.

162

163Batch inputs are enumerated before requests begin so the 2,000-file API limit can be

164checked without orphaning uploads. IO streams yielded by an enumerable must remain

165open until the helper returns; use paths for block-scoped lazy enumeration. Batch

166uploads are concurrent but not transactional. If one upload fails, the helper stops

167starting queued uploads and raises that error; files uploaded successfully before the

168failure remain available through the Files API.

169

125### Custom HTTP clients170### Custom HTTP clients

126 171

127`OpenAI::Client` accepts an `http_client` for advanced transport requirements.172`OpenAI::Client` accepts an `http_client` for advanced transport requirements.

675| Polling timeout | `PollingTimeoutError` |

631 677

632### Request logging678### Request logging

Reference 2026-08-16 16:58 UTC to 2026-08-17 22:57 UTC