Documentation 2026-08-31 23:00 UTC to 2026-09-02 22:59 UTC

687response_id = ""687response_id = ""

688stream.each do |event|688stream.each do |event|

689 puts(event.type)689 puts(event.type)

690 last_sequence_number = event.sequence_number690 last_sequence_number = event.sequence_number || last_sequence_number

691 if event.is_a?(OpenAI::Models::Responses::ResponseCreatedEvent)691 if event.is_a?(OpenAI::Models::Responses::ResponseCreatedEvent)

692 response_id = event.response.id692 response_id = event.response.id

693 end693 end

268System.out.println(output);268System.out.println(output);

269```269```

270 270 

271```ruby

272require "fileutils"

273require "json"

274require "openai"

275 

276client = OpenAI::Client.new

277reviews = ["A rich cup of coffee.", "A bright herbal tea."]

278 

279response = client.embeddings.create(

280 model: "text-embedding-3-small",

281 input: reviews.map { |review| review.tr("\n", " ") }

282)

283 

284csv_field = ->(value) { %("#{value.gsub('"', '""')}") }

285rows = response.data.map.with_index do |embedding, index|

286 [csv_field.call(reviews.fetch(index)), csv_field.call(JSON.generate(embedding.embedding))].join(",")

287end

288 

289FileUtils.mkdir_p("output")

290File.write("output/embedded_1k_reviews.csv", (["combined,ada_embedding"] + rows).join("\n") + "\n")

291```

292 

271 293 

272To load the data from a saved file, you can run the following:294To load the data from a saved file, you can run the following:

273 295 

388);410);

389```411```

390 412 

413```ruby

414require "openai"

415 

416client = OpenAI::Client.new

417 

418response = client.embeddings.create(

419 model: "text-embedding-3-small",

420 input: "Testing 123",

421 encoding_format: :float

422)

423 

424shortened = response.data.fetch(0).embedding.first(256)

425magnitude = Math.sqrt(shortened.sum { |value| value**2 })

426normalized = shortened.map { |value| magnitude.zero? ? 0 : value / magnitude }

427 

428puts(normalized)

429```

430 

391 431 

392Dynamically changing the dimensions enables very flexible usage. For example, when using a vector data store that only supports embeddings up to 1024 dimensions long, developers can now still use our best embedding model `text-embedding-3-large` and specify a value of 1024 for the `dimensions` API parameter, which will shorten the embedding down from 3072 dimensions, trading off some accuracy in exchange for the smaller vector size.432Dynamically changing the dimensions enables very flexible usage. For example, when using a vector data store that only supports embeddings up to 1024 dimensions long, developers can now still use our best embedding model `text-embedding-3-large` and specify a value of 1024 for the `dimensions` API parameter, which will shorten the embedding down from 3072 dimensions, trading off some accuracy in exchange for the smaller vector size.

393 433 

488 .forEach(System.out::println);528 .forEach(System.out::println);

489```529```

490 530 

531```ruby

532require "openai"

533 

534client = OpenAI::Client.new

535article = "At the 2022 Winter Olympics, Great Britain won women's curling and Sweden won men's curling."

536question = <<~QUESTION

537 Use the article below to answer the question. If the answer cannot be found, say "I don't know."

538 

539 Article:

540 #{article}

541 

542 Question: Which athletes won the gold medal in curling at the 2022 Winter Olympics?

543QUESTION

544 

545response = client.chat.completions.create(

546 model: "gpt-4.1-mini",

547 messages: [

548 {

549 role: :system,

550 content: "You answer questions about the 2022 Winter Olympics."

551 },

552 {role: :user, content: question}

553 ],

554 temperature: 0

555)

556 

557puts(response.choices.fetch(0).message.content)

558```

559 

491 560 

492 561 

493 562 

600 .forEach(System.out::println);669 .forEach(System.out::println);

601```670```

602 671 

672```ruby

673require "openai"

674 

675client = OpenAI::Client.new

676reviews = [

677 "A rich cup of coffee.",

678 "Smooth beans in tomato sauce.",

679 "Dark chocolate with orange."

680]

681 

682response = client.embeddings.create(

683 model: "text-embedding-3-small",

684 input: reviews + ["delicious beans"]

685)

686 

687query = response.data.fetch(-1).embedding

688similarity = lambda do |embedding|

689 dot_product = embedding.zip(query).sum { |value, query_value| value * query_value }

690 magnitude = Math.sqrt(embedding.sum { |value| value**2 })

691 query_magnitude = Math.sqrt(query.sum { |value| value**2 })

692 dot_product / (magnitude * query_magnitude)

693end

694 

695results = reviews.map.with_index do |review, index|

696 {

697 review: review,

698 score: similarity.call(response.data.fetch(index).embedding)

699 }

700end.sort_by { |result| -result.fetch(:score) }.first(3)

701 

702puts(results)

703```

704 

603 705 

604 706 

605 707 

713 .forEach(System.out::println);815 .forEach(System.out::println);

714```816```

715 817 

818```ruby

819require "openai"

820 

821client = OpenAI::Client.new

822functions = [

823 "function add(a, b) { return a + b; }",

824 "function complete(prompt) { return prompt; }"

825]

826 

827response = client.embeddings.create(

828 model: "text-embedding-3-small",

829 input: functions + ["Completions API tests"]

830)

831 

832query = response.data.fetch(-1).embedding

833similarity = lambda do |embedding|

834 dot_product = embedding.zip(query).sum { |value, query_value| value * query_value }

835 magnitude = Math.sqrt(embedding.sum { |value| value**2 })

836 query_magnitude = Math.sqrt(query.sum { |value| value**2 })

837 dot_product / (magnitude * query_magnitude)

838end

839 

840results = functions.map.with_index do |source, index|

841 {

842 source: source,

843 score: similarity.call(response.data.fetch(index).embedding)

844 }

845end.sort_by { |result| -result.fetch(:score) }

846 

847puts(results)

848```

849 

716 850 

717 851 

718 852 

837System.out.println(nearestNeighbors);971System.out.println(nearestNeighbors);

838```972```

839 973 

974```ruby

975require "openai"

976 

977client = OpenAI::Client.new

978strings = [

979 "A cheetah is a fast land animal.",

980 "A peregrine falcon is a fast bird.",

981 "A tortoise moves slowly."

982]

983 

984response = client.embeddings.create(

985 model: "text-embedding-3-small",

986 input: strings

987)

988 

989query = response.data.fetch(0).embedding

990similarity = lambda do |embedding|

991 dot_product = embedding.zip(query).sum { |value, query_value| value * query_value }

992 magnitude = Math.sqrt(embedding.sum { |value| value**2 })

993 query_magnitude = Math.sqrt(query.sum { |value| value**2 })

994 dot_product / (magnitude * query_magnitude)

995end

996 

997recommendations = response.data.map.with_index do |embedding, index|

998 {

999 index: index,

1000 text: strings.fetch(index),

1001 similarity: similarity.call(embedding.embedding)

1002 }

1003end.sort_by { |recommendation| -recommendation.fetch(:similarity) }

1004 

1005puts(recommendations)

1006```

1007 

840 1008 

841 1009 

842 1010 

1050System.out.println(positive > negative ? "positive" : "negative");1218System.out.println(positive > negative ? "positive" : "negative");

1051```1219```

1052 1220 

1221```ruby

1222require "openai"

1223 

1224client = OpenAI::Client.new

1225labels = ["negative", "positive"]

1226 

1227response = client.embeddings.create(

1228 model: "text-embedding-3-small",

1229 input: labels + ["The coffee arrived quickly and tastes great."]

1230)

1231 

1232review = response.data.fetch(-1).embedding

1233similarity = lambda do |embedding|

1234 dot_product = embedding.zip(review).sum { |value, review_value| value * review_value }

1235 magnitude = Math.sqrt(embedding.sum { |value| value**2 })

1236 review_magnitude = Math.sqrt(review.sum { |value| value**2 })

1237 dot_product / (magnitude * review_magnitude)

1238end

1239 

1240negative, positive = response.data.first(2).map do |embedding|

1241 similarity.call(embedding.embedding)

1242end

1243puts((positive > negative) ? "positive" : "negative")

1244```

1245 

1053 1246 

1054 1247 

1055 1248 

7## API errors7## API errors

8 8 

9| Code | Overview |9| Code | Overview |

10| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |10| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

11| 400 - Invalid `service_tier` argument | **Cause:** The requested or resolved service tier is not allowed for the project. <br /> **Solution:** Set `service_tier` to a tier allowed for the project, or update the allowed service tiers in [project settings](https://platform.openai.com/settings/). |11| 400 - Invalid `service_tier` argument | **Cause:** The requested or resolved service tier is not allowed for the project. <br /> **Solution:** Set `service_tier` to a tier allowed for the project, or update the allowed service tiers in [project settings](https://platform.openai.com/settings/). |

12| 401 - Invalid Authentication | **Cause:** Invalid Authentication <br /> **Solution:** Ensure the correct [API key](https://platform.openai.com/settings/organization/api-keys) and requesting organization are being used. |12| 401 - Invalid Authentication | **Cause:** Invalid Authentication <br /> **Solution:** Ensure the correct [API key](https://platform.openai.com/settings/organization/api-keys) and requesting organization are being used. |

13| 401 - Incorrect API key provided | **Cause:** The requesting API key is not correct. <br /> **Solution:** Ensure the API key used is correct, clear your browser cache, or [generate a new one](https://platform.openai.com/settings/organization/api-keys). |13| 401 - Incorrect API key provided | **Cause:** The requesting API key is not correct. <br /> **Solution:** Ensure the API key used is correct, clear your browser cache, or [generate a new one](https://platform.openai.com/settings/organization/api-keys). |

16| 403 - Country, region, or territory not supported | **Cause:** You are accessing the API from an unsupported country, region, or territory. <br /> **Solution:** Please see [this page](https://developers.openai.com/api/docs/supported-countries) for more information. |16| 403 - Country, region, or territory not supported | **Cause:** You are accessing the API from an unsupported country, region, or territory. <br /> **Solution:** Please see [this page](https://developers.openai.com/api/docs/supported-countries) for more information. |

17| 429 - Credit balance exhausted | **Code:** `credit_balance_exhausted` <br /> **Cause:** Your organization has no prepaid credits remaining. <br /> **Solution:** [Add credits](https://platform.openai.com/settings/organization/billing) to continue using the API. |17| 429 - Credit balance exhausted | **Code:** `credit_balance_exhausted` <br /> **Cause:** Your organization has no prepaid credits remaining. <br /> **Solution:** [Add credits](https://platform.openai.com/settings/organization/billing) to continue using the API. |

18| 429 - Rate limit reached for requests | **Cause:** You are sending requests too quickly. <br /> **Solution:** Pace your requests and follow the `Retry-After` header when it's present. Read the [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits). |18| 429 - Rate limit reached for requests | **Cause:** You are sending requests too quickly. <br /> **Solution:** Pace your requests and follow the `Retry-After` header when it's present. Read the [Rate limit guide](https://developers.openai.com/api/docs/guides/rate-limits). |

19| 429 - Slow down | **Type:** `rate_limit_error` <br /> **Code:** `slow_down` <br /> **Cause:** Your request rate increased too quickly. <br /> **Solution:** Follow the `Retry-After` header when it's present, reduce your request rate, and increase it gradually. |

19| 429 - Organization spend limit reached | **Code:** `organization_spend_limit_exceeded` <br /> **Cause:** Your organization reached its enforced spend limit. <br /> **Solution:** Increase or remove your [organization spend limit](https://platform.openai.com/settings/organization/limits). |20| 429 - Organization spend limit reached | **Code:** `organization_spend_limit_exceeded` <br /> **Cause:** Your organization reached its enforced spend limit. <br /> **Solution:** Increase or remove your [organization spend limit](https://platform.openai.com/settings/organization/limits). |

20| 429 - Project spend limit reached | **Code:** `project_spend_limit_exceeded` <br /> **Cause:** Your project reached its enforced spend limit. <br /> **Solution:** Increase or remove the spend limit in your [project settings](https://platform.openai.com/settings/). |21| 429 - Project spend limit reached | **Code:** `project_spend_limit_exceeded` <br /> **Cause:** Your project reached its enforced spend limit. <br /> **Solution:** Increase or remove the spend limit in your [project settings](https://platform.openai.com/settings/). |

21| 429 - Organization usage limit reached | **Code:** `organization_usage_limit_exceeded` <br /> **Cause:** Your organization reached its OpenAI-assigned usage limit. <br /> **Solution:** Request a higher [approved usage limit](https://platform.openai.com/settings/organization/limits) or [contact support](https://help.openai.com/). |22| 429 - Organization usage limit reached | **Code:** `organization_usage_limit_exceeded` <br /> **Cause:** Your organization reached its OpenAI-assigned usage limit. <br /> **Solution:** Request a higher [approved usage limit](https://platform.openai.com/settings/organization/limits) or [contact support](https://help.openai.com/). |

22| 500 - The server had an error while processing your request | **Cause:** Issue on our servers. <br /> **Solution:** Retry your request after a brief wait and contact us if the issue persists. Check the [status page](https://status.openai.com/). |23| 500 - The server had an error while processing your request | **Cause:** Issue on our servers. <br /> **Solution:** Retry your request after a brief wait and contact us if the issue persists. Check the [status page](https://status.openai.com/). |

23| 503 - The engine is currently overloaded, please try again later | **Cause:** Our servers are experiencing high traffic. <br /> **Solution:** Please retry your requests after a brief wait. |24| 503 - Model temporarily overloaded | **Type:** `service_unavailable_error` <br /> **Code:** `server_is_overloaded` <br /> **Cause:** The requested model is temporarily overloaded. <br /> **Solution:** Follow the `Retry-After` header when it's present, then retry your request. |

24| 503 - Slow Down | **Cause:** A sudden increase in your request rate is impacting service reliability. <br /> **Solution:** Please reduce your request rate to its original level, maintain a consistent rate for at least 15 minutes, and then gradually increase it. |

25 25 

26For billing-related errors, inspect `error.code` to identify the specific cause. The broader `error.type` can still be `insufficient_quota`.26For billing-related errors, inspect `error.code` to identify the specific cause. The broader `error.type` can still be `insufficient_quota`.

27 27 

156 156 

157 157 

158 158 

159### 429 - Organization spend limit reached159### 429 - Slow down

160 160 

161 161 

162The `organization_spend_limit_exceeded` error indicates that your organization reached its enforced monthly [spend limit](https://developers.openai.com/api/docs/guides/spend-limits). The limit applies to API traffic across all projects in the organization.162A `429` response with the `rate_limit_error` type and `slow_down` code indicates that your request rate increased faster than the service can safely handle. It can occur even when your traffic is within its requests-per-minute and tokens-per-minute limits.

163 163 

164To restore API access, increase or remove the limit in your [organization limit settings](https://platform.openai.com/settings/organization/limits). Otherwise, access resumes after the monthly limit resets.164As a rule of thumb, once your traffic reaches 1 million input tokens per minute (TPM), increase it by no more than 50% every 15 minutes. The exact point at which the ramp-rate limit applies can vary by model and traffic conditions.

165 165 

166To resolve this error:

166 167 

168- If a `Retry-After` header is present, wait at least as long as it specifies before retrying. If it's missing, increase the delay between retries and add a small random delay.

169- Reduce your request rate, then increase it gradually.

170- Keep your traffic pattern steady to reduce the chance of another `slow_down` error.

167 171 

172Enterprise customers whose pay-as-you-go traffic routinely hits ramp-rate limits can consider [Scale Tier](https://openai.com/api-scale-tier/) for more predictable capacity on eligible models. For GPT-5.6 and later models, see [Reserved Tier](https://openai.com/api-reserved-tier/). These capacity options don't replace the recovery steps above: continue to follow `Retry-After` when it's present and ramp traffic gradually.

168 173 

169 174 

170 175 

171 176 

172### 429 - Project spend limit reached

173 177 

174 178 

175The `project_spend_limit_exceeded` error indicates that your project reached its enforced monthly [spend limit](https://developers.openai.com/api/docs/guides/spend-limits). Other projects can continue unless their own limit or the organization limit is also reached.

176 179 

177To restore API access, increase or remove the limit in your [project settings](https://platform.openai.com/settings/). Otherwise, access resumes after the monthly limit resets.180### 429 - Organization spend limit reached

178 181 

179 182 

183The `organization_spend_limit_exceeded` error indicates that your organization reached its enforced monthly [spend limit](https://developers.openai.com/api/docs/guides/spend-limits). The limit applies to API traffic across all projects in the organization.

180 184 

185To restore API access, increase or remove the limit in your [organization limit settings](https://platform.openai.com/settings/organization/limits). Otherwise, access resumes after the monthly limit resets.

181 186 

182 187 

183 188 

184 189 

185### 429 - Organization usage limit reached

186 190 

187 191 

188The `organization_usage_limit_exceeded` error indicates that your organization reached its OpenAI-assigned monthly [usage limit](https://developers.openai.com/api/docs/guides/rate-limits#usage-tiers). This limit is separate from organization and project spend limits that you configure.

189 192 

190To restore API access, request a higher [approved usage limit](https://platform.openai.com/settings/organization/limits) or [contact support](https://help.openai.com/).193### 429 - Project spend limit reached

191 194 

192 195 

196The `project_spend_limit_exceeded` error indicates that your project reached its enforced monthly [spend limit](https://developers.openai.com/api/docs/guides/spend-limits). Other projects can continue unless their own limit or the organization limit is also reached.

193 197 

198To restore API access, increase or remove the limit in your [project settings](https://platform.openai.com/settings/). Otherwise, access resumes after the monthly limit resets.

194 199 

195 200 

196 201 

197 202 

198### 503 - The engine is currently overloaded, please try again later

199 203 

200 204 

201This error message indicates that our servers are experiencing high traffic and are unable to process your request at the moment. This could happen for several reasons, such as:

202 205 

203- There is a sudden spike or surge in demand for our services.206### 429 - Organization usage limit reached

204- There is scheduled or unscheduled maintenance or update on our servers.

205- There is an unexpected or unavoidable outage or incident on our servers.

206 207 

207To resolve this error, please follow these steps:

208 208 

209- Retry your request after a brief wait. We recommend using an exponential backoff strategy or a retry logic that respects the response headers and the rate limit. You can read more about our rate limit [best practices](https://help.openai.com/en/articles/6891753-rate-limit-advice).209The `organization_usage_limit_exceeded` error indicates that your organization reached its OpenAI-assigned monthly [usage limit](https://developers.openai.com/api/docs/guides/rate-limits#usage-tiers). This limit is separate from organization and project spend limits that you configure.

210- Check our [status page](https://status.openai.com/) for any updates or announcements regarding our services and servers.

211- If you are still getting this error after a reasonable amount of time, please contact us for further assistance. We apologize for any inconvenience and appreciate your patience and understanding.

212 210 

211To restore API access, request a higher [approved usage limit](https://platform.openai.com/settings/organization/limits) or [contact support](https://help.openai.com/).

213 212 

214 213 

215 214 

216 215 

217 216 

218 217 

219### 503 - Slow Down

220 218 

219### 503 - Model temporarily overloaded

221 220 

222This error can occur with Pay-As-You-Go models, which are shared across all OpenAI users. It indicates that your traffic has significantly increased, overloading the model and triggering temporary throttling to maintain service stability.

223 221 

224To resolve this error, please follow these steps:222A `503` response with the `service_unavailable_error` type and `server_is_overloaded` code indicates that the requested model does not have enough capacity to process your request at the moment.

225 223 

226- Reduce your request rate to its original level, keep it stable for at least 15 minutes, and then gradually ramp it up.224If a `Retry-After` header is present, wait at least as long as it specifies before retrying. If it's missing, increase the delay between retries. If the error continues, check the [status page](https://status.openai.com/) for an active incident.

227- Maintain a consistent traffic pattern to minimize the likelihood of throttling. You should rarely encounter this error if your request volume remains steady.

228- Consider upgrading to the [Scale Tier](https://openai.com/api-scale-tier/) for guaranteed capacity and performance, ensuring more reliable access during peak demand periods.

229 225 

230 226 

231 227 

126 126 

127**Ramp rate limit**127**Ramp rate limit**

128 128 

129If your traffic ramps too fast, the system may downgrade some Fast mode requests to standard speeds and charge standard rates. When this happens, the response contains `service_tier: "default"`. The ramp rate limit may apply if you send at least 1 million tokens per minute (TPM) and increase TPM by more than 50% within 15 minutes.129If your traffic ramps too fast, the system may downgrade some Fast mode requests to standard speeds and charge standard rates. When this happens, the response contains `service_tier: "default"`. As a rule of thumb, once your traffic reaches 1 million input tokens per minute (TPM), increase it by no more than 50% every 15 minutes. The exact point at which the ramp-rate limit applies can vary by model and traffic conditions.

130 130 

131To avoid triggering the ramp rate limit:131To avoid triggering the ramp rate limit:

132 132 

298 if err := json.Unmarshal([]byte(call.Arguments), &arguments); err != nil {298 if err := json.Unmarshal([]byte(call.Arguments), &arguments); err != nil {

299 panic(err)299 panic(err)

300 }300 }

301 functionOutput = responses.ResponseInputItemParamOfFunctionCallOutput(call.CallID, getHoroscope(arguments.Sign))301 functionOutput = responses.ResponseInputItemParamOfFunctionCallOutput(getHoroscope(arguments.Sign))

302 functionOutput.OfFunctionCallOutput.CallID = openai.String(call.CallID)

302 }303 }

303 if functionOutput.OfFunctionCallOutput == nil {304 if functionOutput.OfFunctionCallOutput == nil {

304 panic("the model did not call get_horoscope")305 panic("the model did not call get_horoscope")

680 if err != nil {681 if err != nil {

681 panic(err)682 panic(err)

682 }683 }

683 input = append(input, responses.ResponseInputItemParamOfFunctionCallOutput(toolCall.CallID, result))684 toolOutput := responses.ResponseInputItemParamOfFunctionCallOutput(result)

685 toolOutput.OfFunctionCallOutput.CallID = openai.String(toolCall.CallID)

686 input = append(input, toolOutput)

684}687}

685```688```

686 689 

153 .build();153 .build();

154 154 

155var response = client.responses().create(params);155var response = client.responses().create(params);

156JsonValue moderation = response._additionalProperties().get("moderation");156var moderation =

157if (moderation == null) {157 response

158 throw new IllegalStateException("The response did not include moderation results");158 .moderation()

159}159 .orElseThrow(

160Map<?, ?> results = moderation.convert(Map.class);160 () -> new IllegalStateException("The response did not include moderation results"));

161List<Boolean> flags = new ArrayList<>();161List<Boolean> flags = new ArrayList<>();

162for (String side : List.of("input", "output")) {162 

163 if (!(results.get(side) instanceof Map<?, ?> result)) {163var input = moderation.input();

164 throw new IllegalStateException("Missing " + side + " moderation result");164if (input.isError()) {

165 }165 throw new IllegalStateException(input.asError().message());

166 if ("error".equals(result.get("type"))) {166}

167 throw new IllegalStateException(String.valueOf(result.get("message")));167if (!input.isModerationResult()) {

168 }168 throw new IllegalStateException("Missing input moderation flag");

169 if (!"moderation_result".equals(result.get("type"))) {169}

170 throw new IllegalStateException("Unexpected " + side + " moderation result type");170flags.add(input.asModerationResult().flagged());

171 }171 

172 if (!(result.get("flagged") instanceof Boolean flagged)) {172var output = moderation.output();

173 throw new IllegalStateException("Missing " + side + " moderation flag");173if (output.isError()) {

174 }174 throw new IllegalStateException(output.asError().message());

175 flags.add(flagged);175}

176if (!output.isModerationResult()) {

177 throw new IllegalStateException("Missing output moderation flag");

176}178}

179flags.add(output.asModerationResult().flagged());

180 

177flags.forEach(System.out::println);181flags.forEach(System.out::println);

178```182```

179 183 

232 .forEach(System.out::println);232 .forEach(System.out::println);

233````233````

234 234 

235````ruby

236require "openai"

237 

238client = OpenAI::Client.new

239meta_prompt = <<~PROMPT

240 Given a task description or existing prompt, produce a detailed system prompt to guide a language model in completing the task effectively.

241 

242 # Guidelines

243 

244 - Understand the Task: Grasp the main objective, goals, requirements, constraints, and expected output.

245 - Minimal Changes: If an existing prompt is provided, improve it only if it's simple. For complex prompts, enhance clarity and add missing elements without altering the original structure.

246 - Reasoning Before Conclusions**: Encourage reasoning steps before any conclusions are reached. ATTENTION! If the user provides examples where the reasoning happens afterward, REVERSE the order! NEVER START EXAMPLES WITH CONCLUSIONS!

247 - Reasoning Order: Call out reasoning portions of the prompt and conclusion parts (specific fields by name). For each, determine the ORDER in which this is done, and whether it needs to be reversed.

248 - Conclusion, classifications, or results should ALWAYS appear last.

249 - Examples: Include high-quality examples if helpful, using placeholders [in brackets] for complex elements.

250 - What kinds of examples may need to be included, how many, and whether they are complex enough to benefit from placeholders.

251 - Clarity and Conciseness: Use clear, specific language. Avoid unnecessary instructions or bland statements.

252 - Formatting: Use markdown features for readability. DO NOT USE ``` CODE BLOCKS UNLESS SPECIFICALLY REQUESTED.

253 - Preserve User Content: If the input task or prompt includes extensive guidelines or examples, preserve them entirely, or as closely as possible. If they are vague, consider breaking down into sub-steps. Keep any details, guidelines, examples, variables, or placeholders provided by the user.

254 - Constants: DO include constants in the prompt, as they are not susceptible to prompt injection. Such as guides, rubrics, and examples.

255 - Output Format: Explicitly the most appropriate output format, in detail. This should include length and syntax (e.g. short sentence, paragraph, JSON, etc.)

256 - For tasks outputting well-defined or structured data (classification, JSON, etc.) bias toward outputting a JSON.

257 - JSON should never be wrapped in code blocks (```) unless explicitly requested.

258 

259 The final prompt you output should adhere to the following structure below. Do not include any additional commentary, only output the completed system prompt. SPECIFICALLY, do not include any additional messages at the start or end of the prompt. (e.g. no "---")

260 

261 [Concise instruction describing the task - this should be the first line in the prompt, no section header]

262 

263 [Additional details as needed.]

264 

265 [Optional sections with headings or bullet points for detailed steps.]

266 

267 # Steps [optional]

268 

269 [optional: a detailed breakdown of the steps necessary to accomplish the task]

270 

271 # Output Format

272 

273 [Specifically call out how the output should be formatted, be it response length, structure e.g. JSON, markdown, etc]

274 

275 # Examples [optional]

276 

277 [Optional: 1-3 well-defined examples with placeholders if necessary. Clearly mark where examples start and end, and what the input and output are. User placeholders as necessary.]

278 [If the examples are shorter than what a realistic example is expected to be, make a reference with () explaining how real examples should be longer / shorter / different. AND USE PLACEHOLDERS! ]

279 

280 # Notes [optional]

281 

282 [optional: edge cases, details, and an area to call or repeat out specific important considerations]

283PROMPT

284 

285def generate_prompt(client, meta_prompt, task_or_prompt)

286 completion = client.chat.completions.create(

287 model: "gpt-5.6",

288 messages: [

289 {role: :system, content: meta_prompt},

290 {

291 role: :user,

292 content: "Task, Goal, or Current Prompt:\n#{task_or_prompt}"

293 }

294 ]

295 )

296 

297 completion.choices.fetch(0).message.content

298end

299 

300puts(generate_prompt(client, meta_prompt, "Write a concise product launch announcement."))

301````

302 

235 303

236 304 

237 305

420 .forEach(System.out::println);488 .forEach(System.out::println);

421```489```

422 490 

491```ruby

492require "openai"

493 

494client = OpenAI::Client.new

495meta_prompt = <<~PROMPT

496 Given a task description or existing prompt, produce a detailed system prompt to guide a realtime audio output language model in completing the task effectively.

497 

498 # Guidelines

499 

500 - Understand the Task: Grasp the main objective, goals, requirements, constraints, and expected output.

501 - Tone: Make sure to specifically call out the tone. By default it should be emotive and friendly, and speak quickly to avoid keeping the user just waiting.

502 - Audio Output Constraints: Because the model is outputting audio, the responses should be short and conversational.

503 - Minimal Changes: If an existing prompt is provided, improve it only if it's simple. For complex prompts, enhance clarity and add missing elements without altering the original structure.

504 - Examples: Include high-quality examples if helpful, using placeholders [in brackets] for complex elements.

505 - What kinds of examples may need to be included, how many, and whether they are complex enough to benefit from placeholders.

506 - It is very important that any examples included reflect the short, conversational output responses of the model.

507 Keep the sentences very short by default. Instead of 3 sentences in a row by the assistant, it should be split up with a back and forth with the user instead.

508 - By default each sentence should be a few words only (5-20ish words). However, if the user specifically asks for "short" responses, then the examples should truly have 1-10 word responses max.

509 - Make sure the examples are multi-turn (at least 4 back-forth-back-forth per example), not just one questions an response. They should reflect an organic conversation.

510 - Clarity and Conciseness: Use clear, specific language. Avoid unnecessary instructions or bland statements.

511 - Preserve User Content: If the input task or prompt includes extensive guidelines or examples, preserve them entirely, or as closely as possible. If they are vague, consider breaking down into sub-steps. Keep any details, guidelines, examples, variables, or placeholders provided by the user.

512 - Constants: DO include constants in the prompt, as they are not susceptible to prompt injection. Such as guides, rubrics, and examples.

513 

514 The final prompt you output should adhere to the following structure below. Do not include any additional commentary, only output the completed system prompt. SPECIFICALLY, do not include any additional messages at the start or end of the prompt. (e.g. no "---")

515 

516 [Concise instruction describing the task - this should be the first line in the prompt, no section header]

517 

518 [Additional details as needed.]

519 

520 [Optional sections with headings or bullet points for detailed steps.]

521 

522 # Examples [optional]

523 

524 [Optional: 1-3 well-defined examples with placeholders if necessary. Clearly mark where examples start and end, and what the input and output are. User placeholders as necessary.]

525 [If the examples are shorter than what a realistic example is expected to be, make a reference with () explaining how real examples should be longer / shorter / different. AND USE PLACEHOLDERS! ]

526 

527 # Notes [optional]

528 

529 [optional: edge cases, details, and an area to call or repeat out specific important considerations]

530PROMPT

531 

532def generate_prompt(client, meta_prompt, task_or_prompt)

533 completion = client.chat.completions.create(

534 model: "gpt-5.6",

535 messages: [

536 {role: :system, content: meta_prompt},

537 {

538 role: :user,

539 content: "Task, Goal, or Current Prompt:\n#{task_or_prompt}"

540 }

541 ]

542 )

543 

544 completion.choices.fetch(0).message.content

545end

546 

547puts(generate_prompt(client, meta_prompt, "Create a friendly voice assistant for a bike shop."))

548```

549 

423 550 

424 551 

425### Prompt edits552### Prompt edits

694 .forEach(System.out::println);821 .forEach(System.out::println);

695````822````

696 823 

824````ruby

825require "openai"

826 

827client = OpenAI::Client.new

828meta_prompt = <<~PROMPT

829 Given a current prompt and a change description, produce a detailed system prompt to guide a language model in completing the task effectively.

830 

831 Your final output will be the full corrected prompt verbatim. However, before that, at the very beginning of your response, use <reasoning> tags to analyze the prompt and determine the following, explicitly:

832 <reasoning>

833 - Simple Change: (yes/no) Is the change description explicit and simple? (If so, skip the rest of these questions.)

834 - Reasoning: (yes/no) Does the current prompt use reasoning, analysis, or chain of thought?

835 - Identify: (max 10 words) if so, which section(s) utilize reasoning?

836 - Conclusion: (yes/no) is the chain of thought used to determine a conclusion?

837 - Ordering: (before/after) is the chain of though located before or after

838 - Structure: (yes/no) does the input prompt have a well defined structure

839 - Examples: (yes/no) does the input prompt have few-shot examples

840 - Representative: (1-5) if present, how representative are the examples?

841 - Complexity: (1-5) how complex is the input prompt?

842 - Task: (1-5) how complex is the implied task?

843 - Necessity: ()

844 - Specificity: (1-5) how detailed and specific is the prompt? (not to be confused with length)

845 - Prioritization: (list) what 1-3 categories are the MOST important to address.

846 - Conclusion: (max 30 words) given the previous assessment, give a very concise, imperative description of what should be changed and how. this does not have to adhere strictly to only the categories listed

847 </reasoning>

848 

849 # Guidelines

850 

851 - Understand the Task: Grasp the main objective, goals, requirements, constraints, and expected output.

852 - Minimal Changes: If an existing prompt is provided, improve it only if it's simple. For complex prompts, enhance clarity and add missing elements without altering the original structure.

853 - Reasoning Before Conclusions**: Encourage reasoning steps before any conclusions are reached. ATTENTION! If the user provides examples where the reasoning happens afterward, REVERSE the order! NEVER START EXAMPLES WITH CONCLUSIONS!

854 - Reasoning Order: Call out reasoning portions of the prompt and conclusion parts (specific fields by name). For each, determine the ORDER in which this is done, and whether it needs to be reversed.

855 - Conclusion, classifications, or results should ALWAYS appear last.

856 - Examples: Include high-quality examples if helpful, using placeholders [in brackets] for complex elements.

857 - What kinds of examples may need to be included, how many, and whether they are complex enough to benefit from placeholders.

858 - Clarity and Conciseness: Use clear, specific language. Avoid unnecessary instructions or bland statements.

859 - Formatting: Use markdown features for readability. DO NOT USE ``` CODE BLOCKS UNLESS SPECIFICALLY REQUESTED.

860 - Preserve User Content: If the input task or prompt includes extensive guidelines or examples, preserve them entirely, or as closely as possible. If they are vague, consider breaking down into sub-steps. Keep any details, guidelines, examples, variables, or placeholders provided by the user.

861 - Constants: DO include constants in the prompt, as they are not susceptible to prompt injection. Such as guides, rubrics, and examples.

862 - Output Format: Explicitly the most appropriate output format, in detail. This should include length and syntax (e.g. short sentence, paragraph, JSON, etc.)

863 - For tasks outputting well-defined or structured data (classification, JSON, etc.) bias toward outputting a JSON.

864 - JSON should never be wrapped in code blocks (```) unless explicitly requested.

865 

866 The final prompt you output should adhere to the following structure below. Do not include any additional commentary, only output the completed system prompt. SPECIFICALLY, do not include any additional messages at the start or end of the prompt. (e.g. no "---")

867 

868 [Concise instruction describing the task - this should be the first line in the prompt, no section header]

869 

870 [Additional details as needed.]

871 

872 [Optional sections with headings or bullet points for detailed steps.]

873 

874 # Steps [optional]

875 

876 [optional: a detailed breakdown of the steps necessary to accomplish the task]

877 

878 # Output Format

879 

880 [Specifically call out how the output should be formatted, be it response length, structure e.g. JSON, markdown, etc]

881 

882 # Examples [optional]

883 

884 [Optional: 1-3 well-defined examples with placeholders if necessary. Clearly mark where examples start and end, and what the input and output are. User placeholders as necessary.]

885 [If the examples are shorter than what a realistic example is expected to be, make a reference with () explaining how real examples should be longer / shorter / different. AND USE PLACEHOLDERS! ]

886 

887 # Notes [optional]

888 

889 [optional: edge cases, details, and an area to call or repeat out specific important considerations]

890 [NOTE: you must start with a <reasoning> section. the immediate next token you produce should be <reasoning>]

891PROMPT

892 

893def generate_prompt(client, meta_prompt, task_or_prompt)

894 completion = client.chat.completions.create(

895 model: "gpt-5.6",

896 messages: [

897 {role: :system, content: meta_prompt},

898 {

899 role: :user,

900 content: "Task, Goal, or Current Prompt:\n#{task_or_prompt}"

901 }

902 ]

903 )

904 

905 completion.choices.fetch(0).message.content

906end

907 

908puts(generate_prompt(client, meta_prompt, "Make this support prompt more concise and empathetic."))

909````

910 

697 911

698 912 

699 913

940 .forEach(System.out::println);1154 .forEach(System.out::println);

941```1155```

942 1156 

1157```ruby

1158require "openai"

1159 

1160client = OpenAI::Client.new

1161meta_prompt = <<~PROMPT

1162 Given a current prompt and a change description, produce a detailed system prompt to guide a realtime audio output language model in completing the task effectively.

1163 

1164 Your final output will be the full corrected prompt verbatim. However, before that, at the very beginning of your response, use <reasoning> tags to analyze the prompt and determine the following, explicitly:

1165 <reasoning>

1166 - Simple Change: (yes/no) Is the change description explicit and simple? (If so, skip the rest of these questions.)

1167 - Reasoning: (yes/no) Does the current prompt use reasoning, analysis, or chain of thought?

1168 - Identify: (max 10 words) if so, which section(s) utilize reasoning?

1169 - Conclusion: (yes/no) is the chain of thought used to determine a conclusion?

1170 - Ordering: (before/after) is the chain of though located before or after

1171 - Structure: (yes/no) does the input prompt have a well defined structure

1172 - Examples: (yes/no) does the input prompt have few-shot examples

1173 - Representative: (1-5) if present, how representative are the examples?

1174 - Complexity: (1-5) how complex is the input prompt?

1175 - Task: (1-5) how complex is the implied task?

1176 - Necessity: ()

1177 - Specificity: (1-5) how detailed and specific is the prompt? (not to be confused with length)

1178 - Prioritization: (list) what 1-3 categories are the MOST important to address.

1179 - Conclusion: (max 30 words) given the previous assessment, give a very concise, imperative description of what should be changed and how. this does not have to adhere strictly to only the categories listed

1180 </reasoning>

1181 

1182 # Guidelines

1183 

1184 - Understand the Task: Grasp the main objective, goals, requirements, constraints, and expected output.

1185 - Tone: Make sure to specifically call out the tone. By default it should be emotive and friendly, and speak quickly to avoid keeping the user just waiting.

1186 - Audio Output Constraints: Because the model is outputting audio, the responses should be short and conversational.

1187 - Minimal Changes: If an existing prompt is provided, improve it only if it's simple. For complex prompts, enhance clarity and add missing elements without altering the original structure.

1188 - Examples: Include high-quality examples if helpful, using placeholders [in brackets] for complex elements.

1189 - What kinds of examples may need to be included, how many, and whether they are complex enough to benefit from placeholders.

1190 - It is very important that any examples included reflect the short, conversational output responses of the model.

1191 Keep the sentences very short by default. Instead of 3 sentences in a row by the assistant, it should be split up with a back and forth with the user instead.

1192 - By default each sentence should be a few words only (5-20ish words). However, if the user specifically asks for "short" responses, then the examples should truly have 1-10 word responses max.

1193 - Make sure the examples are multi-turn (at least 4 back-forth-back-forth per example), not just one questions an response. They should reflect an organic conversation.

1194 - Clarity and Conciseness: Use clear, specific language. Avoid unnecessary instructions or bland statements.

1195 - Preserve User Content: If the input task or prompt includes extensive guidelines or examples, preserve them entirely, or as closely as possible. If they are vague, consider breaking down into sub-steps. Keep any details, guidelines, examples, variables, or placeholders provided by the user.

1196 - Constants: DO include constants in the prompt, as they are not susceptible to prompt injection. Such as guides, rubrics, and examples.

1197 

1198 The final prompt you output should adhere to the following structure below. Do not include any additional commentary, only output the completed system prompt. SPECIFICALLY, do not include any additional messages at the start or end of the prompt. (e.g. no "---")

1199 

1200 [Concise instruction describing the task - this should be the first line in the prompt, no section header]

1201 

1202 [Additional details as needed.]

1203 

1204 [Optional sections with headings or bullet points for detailed steps.]

1205 

1206 # Examples [optional]

1207 

1208 [Optional: 1-3 well-defined examples with placeholders if necessary. Clearly mark where examples start and end, and what the input and output are. User placeholders as necessary.]

1209 [If the examples are shorter than what a realistic example is expected to be, make a reference with () explaining how real examples should be longer / shorter / different. AND USE PLACEHOLDERS! ]

1210 

1211 # Notes [optional]

1212 

1213 [optional: edge cases, details, and an area to call or repeat out specific important considerations]

1214 [NOTE: you must start with a <reasoning> section. the immediate next token you produce should be <reasoning>]

1215PROMPT

1216 

1217def generate_prompt(client, meta_prompt, task_or_prompt)

1218 completion = client.chat.completions.create(

1219 model: "gpt-5.6",

1220 messages: [

1221 {role: :system, content: meta_prompt},

1222 {

1223 role: :user,

1224 content: "Task, Goal, or Current Prompt:\n#{task_or_prompt}"

1225 }

1226 ]

1227 )

1228 

1229 completion.choices.fetch(0).message.content

1230end

1231 

1232puts(generate_prompt(client, meta_prompt, "Make this voice assistant prompt warmer and more direct."))

1233```

1234 

943 1235 

944 1236 

945## Schemas1237## Schemas

81 81 

82## Error mitigation82## Error mitigation

83 83 

84### Handle rapid traffic increases and model overload

85 

86The API can return `slow_down` when your request rate increases too quickly, or `server_is_overloaded` when the requested model is temporarily overloaded. Check the HTTP status and `error.code` to tell these conditions apart:

87 

88| HTTP status | Error type | Error code | What it means | What to do |

89| ----------- | --------------------------- | ---------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |

90| `429` | `rate_limit_error` | `slow_down` | Your request rate increased too quickly. | Follow `Retry-After` when it's present, reduce your request rate, and then increase it gradually. |

91| `503` | `service_unavailable_error` | `server_is_overloaded` | The requested model is temporarily overloaded. | Follow `Retry-After` when it's present, then retry. If the error continues, increase the delay between retry attempts. |

92 

93If `Retry-After` is missing, increase the delay between retries and add a small random delay.

94 

95A `slow_down` error can occur even when your traffic is within its requests-per-minute and tokens-per-minute limits. It reflects how quickly traffic increased, not whether you exhausted those limits.

96 

97As a rule of thumb, once your traffic reaches 1 million input tokens per minute (TPM), increase it by no more than 50% every 15 minutes. The exact point at which the ramp-rate limit applies can vary by model and traffic conditions.

98 

99Enterprise customers whose pay-as-you-go traffic routinely hits ramp-rate limits can consider [Scale Tier](https://openai.com/api-scale-tier/) for more predictable capacity on eligible models. For GPT-5.6 and later models, see [Reserved Tier](https://openai.com/api-reserved-tier/). Capacity tiers don't change how you should handle a `slow_down` response: follow `Retry-After` when it's present, reduce traffic, and ramp gradually.

100 

84### What are some steps I can take to mitigate this?101### What are some steps I can take to mitigate this?

85 102 

86The OpenAI Cookbook has a [Python notebook](https://developers.openai.com/cookbook/examples/how_to_handle_rate_limits) that explains how to avoid rate limit errors, as well an example [Python script](https://github.com/openai/openai-cookbook/blob/main/examples/api_request_parallel_processor.py) for staying under rate limits while batch processing API requests.103The OpenAI Cookbook has a [Python notebook](https://developers.openai.com/cookbook/examples/how_to_handle_rate_limits) that explains how to avoid rate limit errors, as well an example [Python script](https://github.com/openai/openai-cookbook/blob/main/examples/api_request_parallel_processor.py) for staying under rate limits while batch processing API requests.

3470}3470}

3471```3471```

3472 3472 

3473```ruby

3474require "openai"

3475 

3476client = OpenAI::Client.new

3477entities_schema = {

3478 type: :object,

3479 properties: {

3480 attributes: {type: :array, items: {type: :string}},

3481 colors: {type: :array, items: {type: :string}},

3482 animals: {type: :array, items: {type: :string}}

3483 },

3484 required: %w[attributes colors animals],

3485 additionalProperties: false

3486}

3487 

3488stream = client.responses.stream(

3489 model: "gpt-5.6",

3490 input: [

3491 {role: :system, content: "Extract entities from the input text."},

3492 {

3493 role: :user,

3494 content: "The quick brown fox jumps over the lazy dog with piercing blue eyes."

3495 }

3496 ],

3497 text: {

3498 format: {

3499 type: :json_schema,

3500 name: "entities",

3501 strict: true,

3502 schema: entities_schema

3503 }

3504 }

3505)

3506 

3507stream.each do |event|

3508 case event

3509 when OpenAI::Models::Responses::ResponseRefusalDeltaEvent,

3510 OpenAI::Models::Responses::ResponseTextDeltaEvent

3511 print(event.delta)

3512 when OpenAI::Models::Responses::ResponseErrorEvent

3513 warn(event.message)

3514 when OpenAI::Models::Responses::ResponseCompletedEvent

3515 puts("\nCompleted")

3516 end

3517end

3518```

3519 

3473 3520 

3474 3521 

3475## Supported schemas3522## Supported schemas

96 96 

97The provider list displays the provider ID, and the mapping details display the selected service account and its service account ID. Record both identifiers; the workload sends them during token exchange.97The provider list displays the provider ID, and the mapping details display the selected service account and its service account ID. Record both identifiers; the workload sends them during token exchange.

98 98 

99## Exchange the certificate for an access token99## Use X.509 workload identity with an SDK

100 100 

101Set environment variables for the certificate chain, private key, provider, and service account:101Set environment variables for the certificate chain, private key, provider, and service account:

102 102 

109 109 

110The certificate-chain file should contain the leaf certificate first, followed by any intermediate certificates. Don't include certificate material or a `subject_token` in the request body.110The certificate-chain file should contain the leaf certificate first, followed by any intermediate certificates. Don't include certificate material or a `subject_token` in the request body.

111 111 

112Configure an OpenAI SDK client with these values. The SDK presents the client certificate during token exchange and API requests, routes API requests to the mTLS endpoint, and renews short-lived access tokens automatically.

113 

114Authenticate with an X.509 client certificate

115 

116```javascript

117import { readFile } from "node:fs/promises";

118 

119import OpenAI from "openai";

120import { workloadIdentity } from "openai/auth/x509-transport";

121 

122const certificatePath = process.env.OPENAI_MTLS_CERT_CHAIN;

123const privateKeyPath = process.env.OPENAI_MTLS_KEY;

124const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;

125const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;

126 

127if (

128 !certificatePath ||

129 !privateKeyPath ||

130 !identityProviderId ||

131 !serviceAccountId

132) {

133 throw new Error(

134 "Set OPENAI_MTLS_CERT_CHAIN, OPENAI_MTLS_KEY, OPENAI_IDENTITY_PROVIDER_ID, and OPENAI_SERVICE_ACCOUNT_ID"

135 );

136}

137 

138const credential = workloadIdentity.fromX509({

139 certificateChain: await readFile(certificatePath, "utf8"),

140 privateKey: await readFile(privateKeyPath, "utf8"),

141 identityProviderId,

142 serviceAccountId,

143});

144 

145try {

146 const client = new OpenAI({ credential });

147 const response = await client.responses.create({

148 model: "gpt-5.6-terra",

149 input: "Say hello from X.509 workload identity federation.",

150 });

151 

152 console.log(response.output_text);

153} finally {

154 await credential.close();

155}

156```

157 

158```python

159import os

160import ssl

161 

162from openai import DefaultHttpx2Client, OpenAI

163from openai.auth import x509_workload_identity

164 

165tls_context = ssl.create_default_context()

166tls_context.load_cert_chain(

167 certfile=os.environ["OPENAI_MTLS_CERT_CHAIN"],

168 keyfile=os.environ["OPENAI_MTLS_KEY"],

169)

170 

171with OpenAI(

172 base_url="https://mtls.api.openai.com/v1",

173 workload_identity=x509_workload_identity(

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

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

176 ),

177 http_client=DefaultHttpx2Client(verify=tls_context, follow_redirects=False),

178) as client:

179 response = client.responses.create(

180 model="gpt-5.6-terra",

181 input="Say hello from X.509 workload identity federation.",

182 )

183 

184 print(response.output_text)

185```

186 

187```go

188package main

189 

190import (

191 "context"

192 "crypto/tls"

193 "fmt"

194 "log"

195 "net/http"

196 "os"

197 

198 "github.com/openai/openai-go/v3"

199 "github.com/openai/openai-go/v3/auth"

200 "github.com/openai/openai-go/v3/option"

201 "github.com/openai/openai-go/v3/responses"

202)

203 

204func main() {

205 certificate, err := tls.LoadX509KeyPair(

206 os.Getenv("OPENAI_MTLS_CERT_CHAIN"),

207 os.Getenv("OPENAI_MTLS_KEY"),

208 )

209 if err != nil {

210 log.Fatal(err)

211 }

212 

213 transport, err := auth.NewX509Transport(&http.Transport{

214 TLSClientConfig: &tls.Config{

215 Certificates: []tls.Certificate{certificate},

216 MinVersion: tls.VersionTLS12,

217 },

218 })

219 if err != nil {

220 log.Fatal(err)

221 }

222 defer transport.Close()

223 

224 client := openai.NewClient(

225 option.WithX509WorkloadIdentity(auth.X509WorkloadIdentity{

226 IdentityProviderID: os.Getenv("OPENAI_IDENTITY_PROVIDER_ID"),

227 ServiceAccountID: os.Getenv("OPENAI_SERVICE_ACCOUNT_ID"),

228 Transport: transport,

229 }),

230 )

231 

232 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{

233 Model: "gpt-5.6-terra",

234 Input: responses.ResponseNewParamsInputUnion{

235 OfString: openai.String("Say hello from X.509 workload identity federation."),

236 },

237 })

238 if err != nil {

239 log.Fatal(err)

240 }

241 

242 fmt.Println(response.OutputText())

243}

244```

245 

246```java

247import com.openai.client.OpenAIClient;

248import com.openai.client.okhttp.OpenAIOkHttpClient;

249import com.openai.client.okhttp.X509Transport;

250import com.openai.client.okhttp.X509WorkloadIdentity;

251import com.openai.models.responses.ResponseCreateParams;

252import java.io.InputStream;

253import java.nio.file.Files;

254import java.nio.file.Paths;

255import java.security.KeyStore;

256import java.time.Duration;

257import java.util.Arrays;

258import javax.net.ssl.KeyManagerFactory;

259import javax.net.ssl.TrustManagerFactory;

260import javax.net.ssl.X509ExtendedKeyManager;

261import javax.net.ssl.X509TrustManager;

262 

263char[] password = System.getenv("OPENAI_X509_KEYSTORE_PASSWORD").toCharArray();

264try {

265 KeyStore keyStore = KeyStore.getInstance("PKCS12");

266 try (InputStream input =

267 Files.newInputStream(Paths.get(System.getenv("OPENAI_X509_KEYSTORE_PATH")))) {

268 keyStore.load(input, password);

269 }

270 

271 KeyManagerFactory keyManagers =

272 KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());

273 keyManagers.init(keyStore, password);

274 X509ExtendedKeyManager keyManager =

275 Arrays.stream(keyManagers.getKeyManagers())

276 .filter(X509ExtendedKeyManager.class::isInstance)

277 .map(X509ExtendedKeyManager.class::cast)

278 .findFirst()

279 .orElseThrow(() -> new IllegalStateException("No X.509 key manager available"));

280 

281 TrustManagerFactory trustManagers =

282 TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());

283 trustManagers.init((KeyStore) null);

284 X509TrustManager trustManager =

285 Arrays.stream(trustManagers.getTrustManagers())

286 .filter(X509TrustManager.class::isInstance)

287 .map(X509TrustManager.class::cast)

288 .findFirst()

289 .orElseThrow(() -> new IllegalStateException("No X.509 trust manager available"));

290 

291 X509Transport transport =

292 X509Transport.builder()

293 .keyManager(keyManager)

294 .certificateAlias(System.getenv("OPENAI_X509_CERTIFICATE_ALIAS"))

295 .trustManager(trustManager)

296 .build();

297 X509WorkloadIdentity identity =

298 X509WorkloadIdentity.builder()

299 .identityProviderId(System.getenv("OPENAI_IDENTITY_PROVIDER_ID"))

300 .serviceAccountId(System.getenv("OPENAI_SERVICE_ACCOUNT_ID"))

301 .transport(transport)

302 .refreshBuffer(Duration.ofMinutes(10))

303 .build();

304 

305 OpenAIClient client = OpenAIOkHttpClient.builder().x509WorkloadIdentity(identity).build();

306 try {

307 ResponseCreateParams params =

308 ResponseCreateParams.builder()

309 .model("gpt-5.6-terra")

310 .input("Say hello from X.509 workload identity federation.")

311 .build();

312 

313 client.responses().create(params).output().stream()

314 .flatMap(item -> item.message().stream())

315 .flatMap(message -> message.content().stream())

316 .flatMap(content -> content.outputText().stream())

317 .forEach(outputText -> System.out.println(outputText.text()));

318 } finally {

319 client.close();

320 }

321} finally {

322 Arrays.fill(password, '\0');

323}

324```

325 

326```ruby

327require "openai"

328require "openssl"

329 

330certificate_chain = OpenSSL::X509::Certificate.load(

331 File.binread(ENV.fetch("OPENAI_MTLS_CERT_CHAIN"))

332)

333certificate, *intermediates = certificate_chain

334private_key = OpenSSL::PKey.read(File.binread(ENV.fetch("OPENAI_MTLS_KEY")))

335 

336http_client = OpenAI::NetHTTPClient.new do |connection|

337 connection.cert = certificate

338 connection.extra_chain_cert = intermediates

339 connection.key = private_key

340end

341 

342workload_identity = OpenAI::Auth::X509WorkloadIdentity.new(

343 identity_provider_id: ENV.fetch("OPENAI_IDENTITY_PROVIDER_ID"),

344 service_account_id: ENV.fetch("OPENAI_SERVICE_ACCOUNT_ID"),

345 http_client: http_client

346)

347 

348begin

349 client = OpenAI::Client.new(api_key: nil, workload_identity: workload_identity)

350 response = client.responses.create(

351 model: "gpt-5.6-terra",

352 input: "Say hello from X.509 workload identity federation."

353 )

354 

355 puts(response.output_text)

356ensure

357 http_client.close

358end

359```

360 

361 

362These examples require OpenAI SDK versions that support the X.509 configuration shown here: JavaScript 7.8.0 or later with the `undici` peer dependency installed, Python 3.6.0 or later, Go 3.54.0 or later, Java 4.55.0 or later, and Ruby 0.83.0 or later.

363 

364The Java example loads a PKCS12 keystore to construct its `X509ExtendedKeyManager` and uses the platform default trust store to construct its `X509TrustManager`. Set `OPENAI_X509_KEYSTORE_PATH`, `OPENAI_X509_KEYSTORE_PASSWORD`, and `OPENAI_X509_CERTIFICATE_ALIAS` for this example. You can instead supply PEM-backed or hardware-backed managers to the SDK.

365 

366## Exchange the certificate manually

367 

368To inspect or implement the token exchange protocol directly, present the certificate to the X.509 token endpoint:

369 

112```bash370```bash

113curl --cert "$OPENAI_MTLS_CERT_CHAIN" \371curl --cert "$OPENAI_MTLS_CERT_CHAIN" \

114 --key "$OPENAI_MTLS_KEY" \372 --key "$OPENAI_MTLS_KEY" \

142 400 

143Read the `access_token` value from the successful response into your application's credential store or an environment variable such as `OPENAI_WIF_ACCESS_TOKEN`. Treat it as a secret and don't print, log, or commit it.401Read the `access_token` value from the successful response into your application's credential store or an environment variable such as `OPENAI_WIF_ACCESS_TOKEN`. Treat it as a secret and don't print, log, or commit it.

144 402 

145## Call the OpenAI API403## Call the OpenAI API manually

146 404 

147Set `OPENAI_MODEL` to `gpt-5.6`, the current default, or another model available to the target project. Then send the bearer token and an accepted client certificate to the API mTLS endpoint:405Set `OPENAI_MODEL` to `gpt-5.6`, the current default, or another model available to the target project. Then send the bearer token and an accepted client certificate to the API mTLS endpoint:

148 406 

261 261 

262| Endpoint or feature | Service | Storage regions | Processing regions | Supported models and snapshots | Regional processing snapshot exceptions | Notes |262| Endpoint or feature | Service | Storage regions | Processing regions | Supported models and snapshots | Regional processing snapshot exceptions | Notes |

263| -------------------------------------------------------------------- | ---------------- | ----------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |263| -------------------------------------------------------------------- | ---------------- | ----------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |

264| `/v1/audio/transcriptions, /v1/audio/translations, /v1/audio/speech` | Audio | All listed regions | United States, Europe (EEA + Switzerland) | `tts-1`, `whisper-1`, `gpt-4o-tts`, `gpt-4o-transcribe`, `gpt-4o-mini-transcribe` | None | — |264| `/v1/audio/transcriptions, /v1/audio/translations, /v1/audio/speech` | Audio | All listed regions | United States, Europe (EEA + Switzerland) | `tts-1`, `whisper-1`, `gpt-4o-tts`, `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, `gpt-transcribe` | None | — |

265| `/v1/batches` | Batches | All listed regions | United States, Europe (EEA + Switzerland) | `gpt-5.5-pro-2026-04-23`, `gpt-5.4-pro-2026-03-05`, `gpt-5.2-pro-2025-12-11`, `gpt-5-pro-2025-10-06`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5-2026-04-23`, `gpt-5.4-2026-03-05`, `gpt-5-2025-08-07`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.2-2025-12-11`, `gpt-5.1-2025-11-13`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `o3-2025-04-16`, `o4-mini-2025-04-16`, `o1-pro`, `o1-pro-2025-03-19`, `o3-mini-2025-01-31`, `o1-2024-12-17`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-mini-2024-07-18`, `gpt-4-turbo-2024-04-09`, `gpt-4-0613`, `gpt-3.5-turbo-0125` | None | — |265| `/v1/batches` | Batches | All listed regions | United States, Europe (EEA + Switzerland) | `gpt-5.5-pro-2026-04-23`, `gpt-5.4-pro-2026-03-05`, `gpt-5.2-pro-2025-12-11`, `gpt-5-pro-2025-10-06`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5-2026-04-23`, `gpt-5.4-2026-03-05`, `gpt-5-2025-08-07`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.2-2025-12-11`, `gpt-5.1-2025-11-13`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `o3-2025-04-16`, `o4-mini-2025-04-16`, `o1-pro`, `o1-pro-2025-03-19`, `o3-mini-2025-01-31`, `o1-2024-12-17`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-mini-2024-07-18`, `gpt-4-turbo-2024-04-09`, `gpt-4-0613`, `gpt-3.5-turbo-0125` | None | — |

266| `/v1/chat/completions` | Chat Completions | All listed regions | United States, Europe (EEA + Switzerland), United Arab Emirates | `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5-2026-04-23`, `gpt-5.4-2026-03-05`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.2-2025-12-11`, `gpt-5.1-2025-11-13`, `gpt-5-2025-08-07`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `o3-mini-2025-01-31`, `o3-2025-04-16`, `o4-mini-2025-04-16`, `o1-2024-12-17`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-mini-2024-07-18`, `gpt-4-turbo-2024-04-09`, `gpt-4-0613`, `gpt-3.5-turbo-0125` | United Arab Emirates: `gpt-5.6-luna`, `gpt-5.5-2026-04-23`, `gpt-5.2-2025-12-11` | — |266| `/v1/chat/completions` | Chat Completions | All listed regions | United States, Europe (EEA + Switzerland), United Arab Emirates | `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5-2026-04-23`, `gpt-5.4-2026-03-05`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.2-2025-12-11`, `gpt-5.1-2025-11-13`, `gpt-5-2025-08-07`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `o3-mini-2025-01-31`, `o3-2025-04-16`, `o4-mini-2025-04-16`, `o1-2024-12-17`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-mini-2024-07-18`, `gpt-4-turbo-2024-04-09`, `gpt-4-0613`, `gpt-3.5-turbo-0125` | United Arab Emirates: `gpt-5.6-luna`, `gpt-5.5-2026-04-23`, `gpt-5.2-2025-12-11` | — |

267| `/v1/embeddings` | Embeddings | All listed regions | United States, Europe (EEA + Switzerland), United Arab Emirates | `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002` | United Arab Emirates: `text-embedding-3-large` | — |267| `/v1/embeddings` | Embeddings | All listed regions | United States, Europe (EEA + Switzerland), United Arab Emirates | `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002` | United Arab Emirates: `text-embedding-3-large` | — |

272| `/v1/images/generations` | Images | All listed regions | United States, Europe (EEA + Switzerland) | `gpt-image-2`, `gpt-image-1`, `gpt-image-1.5`, `gpt-image-1-mini` | None | — |272| `/v1/images/generations` | Images | All listed regions | United States, Europe (EEA + Switzerland) | `gpt-image-2`, `gpt-image-1`, `gpt-image-1.5`, `gpt-image-1-mini` | None | — |

273| `/v1/moderations` | Moderation | All listed regions | United States, Europe (EEA + Switzerland) | `omni-moderation-latest` | None | — |273| `/v1/moderations` | Moderation | All listed regions | United States, Europe (EEA + Switzerland) | `omni-moderation-latest` | None | — |

274| `/v1/realtime` | Realtime | United States, Europe (EEA + Switzerland) | United States, Europe (EEA + Switzerland) | `gpt-realtime`, `gpt-realtime-1.5`, `gpt-realtime-mini`, `gpt-realtime-2`, `gpt-realtime-2.1`, `gpt-realtime-2.1-mini` | None | — |274| `/v1/realtime` | Realtime | United States, Europe (EEA + Switzerland) | United States, Europe (EEA + Switzerland) | `gpt-realtime`, `gpt-realtime-1.5`, `gpt-realtime-mini`, `gpt-realtime-2`, `gpt-realtime-2.1`, `gpt-realtime-2.1-mini` | None | — |

275| `/v1/realtime/transcription_sessions` | Realtime | United States, Europe (EEA + Switzerland) | United States, Europe (EEA + Switzerland) | `gpt-realtime-whisper` | None | — |275| `/v1/realtime/transcription_sessions` | Realtime | United States, Europe (EEA + Switzerland) | United States, Europe (EEA + Switzerland) | `gpt-realtime-whisper`, `gpt-live-transcribe`, `gpt-transcribe` | None | — |

276| `/v1/realtime/translations` | Realtime | United States, Europe (EEA + Switzerland) | United States, Europe (EEA + Switzerland) | `gpt-realtime-translate` | None | — |276| `/v1/realtime/translations` | Realtime | United States, Europe (EEA + Switzerland) | United States, Europe (EEA + Switzerland) | `gpt-realtime-translate` | None | — |

277| `/v1/responses` | Responses | All listed regions | United States, Europe (EEA + Switzerland), United Arab Emirates | `gpt-5.5-pro-2026-04-23`, `gpt-5.4-pro-2026-03-05`, `gpt-5.2-pro-2025-12-11`, `gpt-5-pro-2025-10-06`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5-2026-04-23`, `gpt-5.4-2026-03-05`, `gpt-5-2025-08-07`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.2-2025-12-11`, `gpt-5.1-2025-11-13`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `o3-2025-04-16`, `o4-mini-2025-04-16`, `o1-pro`, `o1-pro-2025-03-19`, `o3-mini-2025-01-31`, `o1-2024-12-17`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-mini-2024-07-18`, `gpt-4-turbo-2024-04-09`, `gpt-4-0613`, `gpt-3.5-turbo-0125` | United Arab Emirates: `gpt-5.5-pro-2026-04-23`, `gpt-5.6-luna`, `gpt-5.5-2026-04-23`, `gpt-5.2-2025-12-11` | — |277| `/v1/responses` | Responses | All listed regions | United States, Europe (EEA + Switzerland), United Arab Emirates | `gpt-5.5-pro-2026-04-23`, `gpt-5.4-pro-2026-03-05`, `gpt-5.2-pro-2025-12-11`, `gpt-5-pro-2025-10-06`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5-2026-04-23`, `gpt-5.4-2026-03-05`, `gpt-5-2025-08-07`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5.2-2025-12-11`, `gpt-5.1-2025-11-13`, `gpt-5-mini-2025-08-07`, `gpt-5-nano-2025-08-07`, `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, `gpt-4.1-nano-2025-04-14`, `o3-2025-04-16`, `o4-mini-2025-04-16`, `o1-pro`, `o1-pro-2025-03-19`, `o3-mini-2025-01-31`, `o1-2024-12-17`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-mini-2024-07-18`, `gpt-4-turbo-2024-04-09`, `gpt-4-0613`, `gpt-3.5-turbo-0125` | United Arab Emirates: `gpt-5.5-pro-2026-04-23`, `gpt-5.6-luna`, `gpt-5.5-2026-04-23`, `gpt-5.2-2025-12-11` | — |

278| `/v1/responses File Search` | Responses | All listed regions | United States, Europe (EEA + Switzerland) | Service-level support | None | — |278| `/v1/responses File Search` | Responses | All listed regions | United States, Europe (EEA + Switzerland) | Service-level support | None | — |

173<dependency>173<dependency>

174 <groupId>com.openai</groupId>174 <groupId>com.openai</groupId>

175 <artifactId>openai-java</artifactId>175 <artifactId>openai-java</artifactId>

176 <version>4.55.0</version>176 <version>4.56.0</version>

177</dependency>177</dependency>

178```178```

179 179 

190<dependency>190<dependency>

191 <groupId>com.openai</groupId>191 <groupId>com.openai</groupId>

192 <artifactId>openai-java</artifactId>192 <artifactId>openai-java</artifactId>

193 <version>4.55.0</version>193 <version>4.56.0</version>

194</dependency>194</dependency>

195```195```

196 196