Documentation 2026-08-13 22:00 UTC to 2026-08-14 20:01 UTC

51}51}

52```52```

53 53 

54```ruby

55require "openai"

56require "pathname"

57 

58client = OpenAI::Client.new

59file = Pathname("revenue-forecast.csv")

60uploaded = client.files.create(file: file, purpose: :assistants)

61puts(uploaded.id)

62```

63 

54```bash64```bash

55curl https://api.openai.com/v1/files \65curl https://api.openai.com/v1/files \

56 -H "Authorization: Bearer $OPENAI_API_KEY" \66 -H "Authorization: Bearer $OPENAI_API_KEY" \

101}111}

102```112```

103 113 

114```ruby

115require "openai"

116 

117client = OpenAI::Client.new

118assistant = client.beta.assistants.create(

119 name: "Data visualizer",

120 model: "gpt-4o",

121 instructions: "Analyze CSV data, create relevant visualizations, and summarize the trends.",

122 tools: [{type: :code_interpreter}],

123 tool_resources: {

124 code_interpreter: {file_ids: ["file-BK7bzQj3FfZFXr7DbL6xJwfo"]}

125 }

126)

127puts(assistant.id)

128```

129 

104```bash130```bash

105curl https://api.openai.com/v1/assistants \131curl https://api.openai.com/v1/assistants \

106 -H "Authorization: Bearer $OPENAI_API_KEY" \132 -H "Authorization: Bearer $OPENAI_API_KEY" \

179}205}

180```206```

181 207 

208```ruby

209require "openai"

210 

211client = OpenAI::Client.new

212thread = client.beta.threads.create(

213 messages: [{

214 role: :user,

215 content: "Create 3 data visualizations based on the trends in this file.",

216 attachments: [{

217 file_id: "file-ACq8OjcLQm2eIG0BvRM4z5qX",

218 tools: [{type: :code_interpreter}]

219 }]

220 }]

221)

222puts(thread.id)

223```

224 

182```bash225```bash

183curl https://api.openai.com/v1/threads \226curl https://api.openai.com/v1/threads \

184 -H "Authorization: Bearer $OPENAI_API_KEY" \227 -H "Authorization: Bearer $OPENAI_API_KEY" \

293}336}

294```337```

295 338 

339```ruby

340require "openai"

341require "pathname"

342 

343client = OpenAI::Client.new

344file = client.files.create(

345 file: Pathname("myimage.png"),

346 purpose: :vision

347)

348thread = client.beta.threads.create(

349 messages: [{

350 role: :user,

351 content: [

352 {type: :text, text: "What is the difference between these images?"},

353 {

354 type: :image_url,

355 image_url: {url: "https://openai-documentation.vercel.app/images/cat_and_otter.png"}

356 },

357 {type: :image_file, image_file: {file_id: file.id}}

358 ]

359 }]

360)

361puts(thread.id)

362```

363 

296```bash364```bash

297# Upload a file with an "vision" purpose365# Upload a file with an "vision" purpose

298curl https://api.openai.com/v1/files \366curl https://api.openai.com/v1/files \

398}466}

399```467```

400 468 

469```ruby

470require "openai"

471 

472client = OpenAI::Client.new

473thread = client.beta.threads.create(

474 messages: [{

475 role: :user,

476 content: [

477 {type: :text, text: "What is this an image of?"},

478 {

479 type: :image_url,

480 image_url: {

481 url: "https://openai-documentation.vercel.app/images/cat_and_otter.png",

482 detail: :high

483 }

484 }

485 ]

486 }]

487)

488puts(thread.id)

489```

490 

401```bash491```bash

402curl https://api.openai.com/v1/threads \492curl https://api.openai.com/v1/threads \

403 -H "Authorization: Bearer $OPENAI_API_KEY" \493 -H "Authorization: Bearer $OPENAI_API_KEY" \

557fmt.Println(messageContent.Value)647fmt.Println(messageContent.Value)

558```648```

559 649 

650```ruby

651require "openai"

652require "pathname"

653 

654client = OpenAI::Client.new

655message = client.beta.threads.messages.retrieve(

656 "msg_abc123",

657 thread_id: "thread_abc123"

658)

659text_block = message.content.find do |content|

660 content.is_a?(OpenAI::Models::Beta::Threads::TextContentBlock)

661end

662unless text_block.is_a?(OpenAI::Models::Beta::Threads::TextContentBlock)

663 raise "No text content returned"

664end

665text = text_block.text

666downloads = Pathname("downloads")

667references = text.annotations.each_with_index.filter_map do |annotation, index|

668 text.value = text.value.sub(annotation.text, " [#{index}]")

669 

670 case annotation

671 when OpenAI::Models::Beta::Threads::FileCitationAnnotation

672 file = client.files.retrieve(annotation.file_citation.file_id)

673 "[#{index}] #{file.filename}"

674 when OpenAI::Models::Beta::Threads::FilePathAnnotation

675 file_id = annotation.file_path.file_id

676 file = client.files.retrieve(file_id)

677 downloads.mkpath

678 output_path = downloads.join(Pathname(file.filename).basename)

679 output_path.binwrite(client.files.content(file_id).read)

680 "[#{index}] Downloaded #{output_path}"

681 end

682end

683 

684puts(([text.value] + references).join("\n"))

685```

686 

560 687 

561## Runs and Run Steps688## Runs and Run Steps

562 689 

584}711}

585```712```

586 713 

714```ruby

715require "openai"

716 

717client = OpenAI::Client.new

718run = client.beta.threads.runs.create("thread_abc123", assistant_id: "asst_ToSF7Gb04YMj8AMMm50ZLLtY")

719puts(run.id)

720```

721 

587```bash722```bash

588curl https://api.openai.com/v1/threads/THREAD_ID/runs \723curl https://api.openai.com/v1/threads/THREAD_ID/runs \

589 -H "Authorization: Bearer $OPENAI_API_KEY" \724 -H "Authorization: Bearer $OPENAI_API_KEY" \

631}766}

632```767```

633 768 

769```ruby

770require "openai"

771 

772client = OpenAI::Client.new

773run = client.beta.threads.runs.create(

774 "thread_abc123",

775 assistant_id: "asst_ToSF7Gb04YMj8AMMm50ZLLtY",

776 model: "gpt-4o",

777 instructions: "New instructions that override the Assistant instructions",

778 tools: [{type: :code_interpreter}, {type: :file_search}]

779)

780puts(run.id)

781```

782 

634```bash783```bash

635curl https://api.openai.com/v1/threads/THREAD_ID/runs \784curl https://api.openai.com/v1/threads/THREAD_ID/runs \

636 -H "Authorization: Bearer $OPENAI_API_KEY" \785 -H "Authorization: Bearer $OPENAI_API_KEY" \

323conversation = openai.conversations.create(items=items)323conversation = openai.conversations.create(items=items)

324```324```

325 325 

326```ruby

327require "openai"

328 

329client = OpenAI::Client.new

330thread_id = ENV.fetch("OPENAI_THREAD_ID")

331messages = client.beta.threads.messages.list(thread_id, order: :asc)

332items = []

333messages.auto_paging_each do |message|

334 content = message.content.filter_map do |part|

335 case part

336 when OpenAI::Models::Beta::Threads::TextContentBlock

337 type = if message.role == OpenAI::Models::Beta::Threads::Message::Role::USER

338 :input_text

339 else

340 :output_text

341 end

342 {type: type, text: part.text.value}

343 when OpenAI::Models::Beta::Threads::ImageURLContentBlock

344 {

345 type: :input_image,

346 image_url: part.image_url.url,

347 detail: part.image_url.detail

348 }

349 end

350 end

351 items << {role: message.role, content: content}

352end

353conversation = client.conversations.create(

354 items: items

355)

356puts(conversation.id)

357```

358 

326 359 

327## Comparing full examples360## Comparing full examples

328 361 

371 return {"content": messages.data[0].content}404 return {"content": messages.data[0].content}

372```405```

373 406 

407```ruby

408require "openai"

409 

410client = OpenAI::Client.new

411assistant_id = ENV.fetch("OPENAI_ASSISTANT_ID")

412threads_by_session = {}

413 

414handle_message = lambda do |session_id:, content:|

415 thread_id = threads_by_session[session_id]

416 unless thread_id

417 thread_id = client.beta.threads.create.id

418 threads_by_session[session_id] = thread_id

419 end

420 

421 client.beta.threads.messages.create(

422 thread_id,

423 role: :user,

424 content: content

425 )

426 run = client.beta.threads.runs.create(

427 thread_id,

428 assistant_id: assistant_id

429 )

430 while [:queued, :in_progress].include?(run.status)

431 sleep(1)

432 run = client.beta.threads.runs.retrieve(run.id, thread_id: thread_id)

433 end

434 

435 messages = client.beta.threads.messages.list(

436 thread_id,

437 order: :desc,

438 limit: 1

439 )

440 {content: messages.data&.first&.content}

441end

442 

443puts(handle_message.call(

444 session_id: "example-session",

445 content: "What are the five Ds of dodgeball?"

446))

447```

448 

374 449 

375 450

376 451 

398 473 

399 return {"content": response.output_text}474 return {"content": response.output_text}

400```475```

476 

477```ruby

478require "openai"

479 

480client = OpenAI::Client.new

481conversations_by_session = {}

482 

483handle_message = lambda do |session_id:, content:|

484 conversation_id = conversations_by_session[session_id]

485 unless conversation_id

486 conversation_id = client.conversations.create.id

487 conversations_by_session[session_id] = conversation_id

488 end

489 

490 response = client.responses.create(

491 prompt: {id: ENV.fetch("OPENAI_PROMPT_ID")},

492 input: [{role: :user, content: content}],

493 conversation: conversation_id

494 )

495 {content: response.output_text}

496end

497 

498puts(handle_message.call(

499 session_id: "example-session",

500 content: "What are the five Ds of dodgeball?"

501))

502```

46}46}

47```47```

48 48 

49```ruby

50require "openai"

51 

52client = OpenAI::Client.new

53assistant = client.beta.assistants.create(

54 model: "gpt-4o",

55 tools: [{type: :code_interpreter}]

56)

57puts(assistant.id)

58```

59 

49```bash60```bash

50curl https://api.openai.com/v1/assistants \61curl https://api.openai.com/v1/assistants \

51 -u :$OPENAI_API_KEY \62 -u :$OPENAI_API_KEY \

127}138}

128```139```

129 140 

141```ruby

142require "openai"

143require "pathname"

144 

145client = OpenAI::Client.new

146file = client.files.create(

147 file: Pathname("revenue-forecast.csv"),

148 purpose: :assistants

149)

150assistant = client.beta.assistants.create(

151 model: "gpt-4o",

152 instructions: "When asked a math question, write and run code to answer it.",

153 tools: [{type: :code_interpreter}],

154 tool_resources: {

155 code_interpreter: {file_ids: [file.id]}

156 }

157)

158puts(assistant.id)

159```

160 

130```bash161```bash

131# Upload a file with an "assistants" purpose162# Upload a file with an "assistants" purpose

132curl https://api.openai.com/v1/files \163curl https://api.openai.com/v1/files \

201}232}

202```233```

203 234 

235```ruby

236require "openai"

237 

238client = OpenAI::Client.new

239thread = client.beta.threads.create(

240 messages: [{

241 role: :user,

242 content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",

243 attachments: [{

244 file_id: "file-ACq8OjcLQm2eIG0BvRM4z5qX",

245 tools: [{type: :code_interpreter}]

246 }]

247 }]

248)

249puts(thread.id)

250```

251 

204```bash252```bash

205curl https://api.openai.com/v1/threads/thread_abc123/messages \253curl https://api.openai.com/v1/threads/thread_abc123/messages \

206 -u :$OPENAI_API_KEY \254 -u :$OPENAI_API_KEY \

307}355}

308```356```

309 357 

358```ruby

359require "openai"

360 

361client = OpenAI::Client.new

362image = client.files.content("file-abc123")

363File.binwrite("my-image.png", image.read)

364```

365 

310```bash366```bash

311curl https://api.openai.com/v1/files/file-abc123/content \367curl https://api.openai.com/v1/files/file-abc123/content \

312 -H "Authorization: Bearer $OPENAI_API_KEY" \368 -H "Authorization: Bearer $OPENAI_API_KEY" \

371fmt.Println(runSteps.Data)427fmt.Println(runSteps.Data)

372```428```

373 429 

430```ruby

431require "openai"

432 

433client = OpenAI::Client.new

434steps = client.beta.threads.runs.steps.list(

435 "run_abc123",

436 thread_id: "thread_abc123"

437)

438puts(steps.data)

439```

440 

374```bash441```bash

375curl https://api.openai.com/v1/threads/thread_abc123/runs/RUN_ID/steps \442curl https://api.openai.com/v1/threads/thread_abc123/runs/RUN_ID/steps \

376 -H "Authorization: Bearer $OPENAI_API_KEY" \443 -H "Authorization: Bearer $OPENAI_API_KEY" \

58}58}

59```59```

60 60 

61```ruby

62require "openai"

63 

64client = OpenAI::Client.new

65assistant = client.beta.assistants.create(

66 model: "gpt-4o",

67 name: "Financial Analyst Assistant",

68 instructions: "Use the knowledge base to answer questions about audited financial statements.",

69 tools: [{type: :file_search}]

70)

71puts(assistant.id)

72```

73 

61```bash74```bash

62curl https://api.openai.com/v1/assistants \75curl https://api.openai.com/v1/assistants \

63-H "Content-Type: application/json" \76-H "Content-Type: application/json" \

151}164}

152```165```

153 166 

167```ruby

168require "openai"

169 

170client = OpenAI::Client.new

171assistant = client.beta.assistants.update(

172 "asst_abc123",

173 tool_resources: {

174 file_search: {vector_store_ids: ["vs_abc123"]}

175 }

176)

177puts(assistant.id)

178```

179 

154 180 

155### Step 4: Create a thread181### Step 4: Create a thread

156 182 

441}467}

442```468```

443 469 

470```ruby

471require "openai"

472 

473client = OpenAI::Client.new

474store = client.vector_stores.create(

475 name: "Product Documentation",

476 file_ids: [

477 "file_1",

478 "file_2",

479 "file_3",

480 "file_4",

481 "file_5"

482 ]

483)

484puts(store.id)

485```

486 

444 487 

445Adding files to vector stores is an async operation. To ensure the operation is complete, we recommend that you use the 'create and poll' helpers in our official SDKs. If you're not using the SDKs, you can retrieve the `vector_store` object and monitor its [`file_counts`](https://developers.openai.com/api/reference/resources/vector_stores#vector-stores/object-file_counts) property to see the result of the file ingestion operation.488Adding files to vector stores is an async operation. To ensure the operation is complete, we recommend that you use the 'create and poll' helpers in our official SDKs. If you're not using the SDKs, you can retrieve the `vector_store` object and monitor its [`file_counts`](https://developers.openai.com/api/reference/resources/vector_stores#vector-stores/object-file_counts) property to see the result of the file ingestion operation.

446 489 

472}515}

473```516```

474 517 

518```ruby

519require "openai"

520 

521client = OpenAI::Client.new

522file = client.vector_stores.files.create(

523 "vs_abc123",

524 file_id: "file-abc123"

525)

526until [:completed, :failed, :cancelled].include?(file.status)

527 sleep(1)

528 file = client.vector_stores.files.retrieve(

529 file.id,

530 vector_store_id: "vs_abc123"

531 )

532end

533puts(file.status)

534```

535 

475 536 

476Alternatively, you can add several files to a vector store by [creating batches](https://developers.openai.com/api/reference/resources/vector_stores/subresources/file_batches/methods/create) of up to 500 files.537Alternatively, you can add several files to a vector store by [creating batches](https://developers.openai.com/api/reference/resources/vector_stores/subresources/file_batches/methods/create) of up to 500 files.

477 538 

542}603}

543```604```

544 605 

606```ruby

607require "openai"

608 

609client = OpenAI::Client.new

610batch = client.vector_stores.file_batches.create(

611 "vs_abc123",

612 files: [

613 {file_id: "file_1", attributes: {category: "finance"}},

614 {

615 file_id: "file_2",

616 chunking_strategy: {

617 type: :static,

618 max_chunk_size_tokens: 1_000,

619 chunk_overlap_tokens: 200

620 }

621 }

622 ]

623)

624until [:completed, :failed, :cancelled].include?(batch.status)

625 sleep(1)

626 batch = client.vector_stores.file_batches.retrieve(

627 batch.id,

628 vector_store_id: "vs_abc123"

629 )

630end

631puts(batch.status)

632```

633 

545 634 

546Similarly, these files can be removed from a vector store by either:635Similarly, these files can be removed from a vector store by either:

547 636 

619}708}

620```709```

621 710 

711```ruby

712require "openai"

713 

714client = OpenAI::Client.new

715assistant = client.beta.assistants.create(

716 instructions: "Answer product support questions using the provided files.",

717 model: "gpt-4o",

718 tools: [{type: :file_search}],

719 tool_resources: {

720 file_search: {vector_store_ids: ["vs_1"]}

721 }

722)

723thread = client.beta.threads.create(

724 messages: [{role: :user, content: "How do I cancel my subscription?"}],

725 tool_resources: {

726 file_search: {vector_store_ids: ["vs_2"]}

727 }

728)

729puts([assistant.id, thread.id])

730```

731 

622 732 

623You can also attach a vector store to Threads or Assistants after they're created by updating them with the right `tool_resources`.733You can also attach a vector store to Threads or Assistants after they're created by updating them with the right `tool_resources`.

624 734 

708fmt.Println(runStep)818fmt.Println(runStep)

709```819```

710 820 

821```ruby

822require "openai"

823 

824client = OpenAI::Client.new

825step = client.beta.threads.runs.steps.retrieve(

826 "step_abc123",

827 thread_id: "thread_abc123",

828 run_id: "run_abc123",

829 include: ["step_details.tool_calls[*].file_search.results[*].content"]

830)

831puts(step)

832```

833 

711```bash834```bash

712curl -g https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123?include[]=step_details.tool_calls[*].file_search.results[*].content \835curl -g https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123?include[]=step_details.tool_calls[*].file_search.results[*].content \

713-H "Authorization: Bearer $OPENAI_API_KEY" \836-H "Authorization: Bearer $OPENAI_API_KEY" \

781}904}

782```905```

783 906 

907```ruby

908require "openai"

909 

910client = OpenAI::Client.new

911store = client.vector_stores.create(

912 name: "Product Documentation",

913 file_ids: [

914 "file_1",

915 "file_2",

916 "file_3",

917 "file_4",

918 "file_5"

919 ],

920 expires_after: {anchor: :last_active_at, days: 7}

921)

922puts(store.id)

923```

924 

784 925 

785**Thread vector stores have default expiration policies**926**Thread vector stores have default expiration policies**

786 927 

859}1000}

860```1001```

861 1002 

1003```ruby

1004require "openai"

1005 

1006client = OpenAI::Client.new

1007files = client.vector_stores.files.list("vs_expired")

1008store = client.vector_stores.create(name: "rag-store")

1009client.beta.threads.update(

1010 "thread_abc123",

1011 tool_resources: {file_search: {vector_store_ids: [store.id]}}

1012)

1013file_ids = []

1014files.auto_paging_each { |file| file_ids << file.id }

1015file_ids.each_slice(100) do |batch_ids|

1016 batch = client.vector_stores.file_batches.create(store.id, file_ids: batch_ids)

1017 while batch.status == OpenAI::VectorStores::VectorStoreFileBatch::Status::IN_PROGRESS

1018 sleep(2)

1019 batch = client.vector_stores.file_batches.retrieve(

1020 batch.id,

1021 vector_store_id: store.id

1022 )

1023 end

1024 unless batch.status == OpenAI::VectorStores::VectorStoreFileBatch::Status::COMPLETED

1025 raise "File batch ended with status: #{batch.status}"

1026 end

1027end

1028puts(store.id)

1029```

1030 

862 1031 

863## Supported files1032## Supported files

864 1033 

170}170}

171```171```

172 172 

173```ruby

174require "openai"

175 

176client = OpenAI::Client.new

177assistant = client.beta.assistants.create(

178 model: "gpt-4o",

179 instructions: "Use the provided functions to answer weather questions.",

180 tools: [

181 {

182 type: :function,

183 function: {

184 name: "get_current_temperature",

185 description: "Get the current temperature for a location",

186 parameters: {

187 type: :object,

188 properties: {

189 location: {type: :string},

190 unit: {type: :string, enum: ["Celsius", "Fahrenheit"]}

191 },

192 required: ["location", "unit"]

193 }

194 }

195 },

196 {

197 type: :function,

198 function: {

199 name: "get_rain_probability",

200 description: "Get the probability of rain for a location",

201 parameters: {

202 type: :object,

203 properties: {location: {type: :string}},

204 required: ["location"]

205 }

206 }

207 }

208 ]

209)

210puts(assistant.id)

211```

212 

173 213 

174### Step 2: Create a Thread and add Messages214### Step 2: Create a Thread and add Messages

175 215 

209}249}

210```250```

211 251 

252```ruby

253require "openai"

254 

255client = OpenAI::Client.new

256thread = client.beta.threads.create

257message = client.beta.threads.messages.create(

258 thread.id,

259 role: :user,

260 content: "What's the weather in San Francisco today, and will it rain?"

261)

262puts(message.id)

263```

264 

212 265 

213### Step 3: Initiate a Run266### Step 3: Initiate a Run

214 267 

556}609}

557```610```

558 611 

612```ruby

613require "openai"

614 

615client = OpenAI::Client.new

616thread_id = ENV.fetch("OPENAI_THREAD_ID")

617assistant_id = ENV.fetch("OPENAI_ASSISTANT_ID")

618 

619poll_run = lambda do |run|

620 while [

621 OpenAI::Beta::Threads::RunStatus::QUEUED,

622 OpenAI::Beta::Threads::RunStatus::IN_PROGRESS

623 ].include?(run.status)

624 sleep(2)

625 run = client.beta.threads.runs.retrieve(run.id, thread_id: thread_id)

626 end

627 run

628end

629 

630run = client.beta.threads.runs.create(thread_id, assistant_id: assistant_id)

631run = poll_run.call(run)

632 

633if run.status == OpenAI::Beta::Threads::RunStatus::REQUIRES_ACTION

634 required_action = run.required_action or raise "Run has no required action"

635 tool_outputs = required_action.submit_tool_outputs.tool_calls.filter_map do |tool_call|

636 output = case tool_call.function.name

637 when "get_current_temperature" then "57"

638 when "get_rain_probability" then "0.06"

639 end

640 {tool_call_id: tool_call.id, output: output} if output

641 end

642 raise "No supported tool calls were requested" if tool_outputs.empty?

643 

644 run = client.beta.threads.runs.submit_tool_outputs(

645 run.id,

646 thread_id: thread_id,

647 tool_outputs: tool_outputs

648 )

649 run = poll_run.call(run)

650end

651 

652if run.status == OpenAI::Beta::Threads::RunStatus::COMPLETED

653 messages = client.beta.threads.messages.list(thread_id)

654 messages.auto_paging_each { |message| puts(message.content) }

655else

656 warn("Run ended with status: #{run.status}")

657end

658```

659 

559 660 

560 661 

561### Using Structured Outputs662### Using Structured Outputs

730 }831 }

731}832}

732```833```

834 

835```ruby

836require "openai"

837 

838client = OpenAI::Client.new

839assistant = client.beta.assistants.create(

840 model: "gpt-4o",

841 name: "Weather assistant",

842 tools: [{type: :function, function: {name: "get_weather", description: "Get weather", parameters: {type: :object, properties: {city: {type: :string}}, required: ["city"], additionalProperties: false}, strict: true}}]

843)

844puts(assistant.id)

845```

463```ruby463```ruby

464audit_logs = openai.admin.organization.audit_logs.list(limit: 10)464audit_logs = openai.admin.organization.audit_logs.list(limit: 10)

465 465 

466audit_logs.data.each do |audit_log|466(audit_logs.data || []).each do |audit_log|

467 puts(audit_log.id)467 puts(audit_log.id)

468end468end

469```469```

171}171}

172```172```

173 173 

174```ruby

175require "base64"

176require "openai"

177 

178client = OpenAI::Client.new

179completion = client.chat.completions.create(

180 model: "gpt-audio-1.5",

181 messages: [{role: :user, content: "Is a golden retriever a good family dog?"}],

182 modalities: [:text, :audio],

183 audio: {voice: :alloy, format: :wav},

184 store: true

185)

186 

187audio = completion.choices.fetch(0).message.audio or raise "No audio returned"

188File.binwrite("dog.wav", Base64.strict_decode64(audio.data))

189```

190 

174```bash191```bash

175curl "https://api.openai.com/v1/chat/completions" \192curl "https://api.openai.com/v1/chat/completions" \

176 -H "Content-Type: application/json" \193 -H "Content-Type: application/json" \

304}321}

305```322```

306 323 

324```ruby

325require "base64"

326require "openai"

327 

328client = OpenAI::Client.new

329audio = Base64.strict_encode64(File.binread("audio.wav"))

330completion = client.chat.completions.create(

331 model: "gpt-audio-1.5",

332 messages: [{

333 role: :user,

334 content: [

335 {type: :text, text: "What is in this recording?"},

336 {type: :input_audio, input_audio: {data: audio, format: :wav}}

337 ]

338 }],

339 modalities: [:text, :audio],

340 audio: {voice: :alloy, format: :wav},

341 store: true

342)

343 

344puts(completion.choices.fetch(0).message.content)

345```

346 

307```bash347```bash

308curl "https://api.openai.com/v1/chat/completions" \348curl "https://api.openai.com/v1/chat/completions" \

309 -H "Content-Type: application/json" \349 -H "Content-Type: application/json" \

79}79}

80```80```

81 81 

82```ruby

83require "openai"

84 

85client = OpenAI::Client.new

86response = client.responses.create(

87 model: "gpt-5.6",

88 input: "Write a detailed market analysis.",

89 background: true

90)

91 

92puts(response.status)

93```

94 

82 95 

83## Polling background responses96## Polling background responses

84 97 

170}183}

171```184```

172 185 

186```ruby

187require "openai"

188 

189client = OpenAI::Client.new

190response = client.responses.create(

191 model: "gpt-5.6",

192 input: "Write a very long novel about otters in space.",

193 background: true

194)

195 

196while [:queued, :in_progress].include?(response.status)

197 puts("Current status: #{response.status}")

198 sleep(2)

199 response = client.responses.retrieve(response.id)

200end

201 

202puts("Final status: #{response.status}")

203puts(response.output_text)

204```

205 

173 206 

174## Cancelling a background response207## Cancelling a background response

175 208 

227}260}

228```261```

229 262 

263```ruby

264require "openai"

265 

266client = OpenAI::Client.new

267response = client.responses.cancel("resp_123")

268puts(response.status)

269```

270 

230 271 

231Cancelling twice is idempotent - subsequent calls simply return the final `Response` object.272Cancelling twice is idempotent - subsequent calls simply return the final `Response` object.

232 273 

351}392}

352```393```

353 394 

395```ruby

396require "openai"

397 

398client = OpenAI::Client.new

399stream = client.responses.stream(

400 model: "gpt-5.6",

401 input: "Write a very long novel about otters in space.",

402 background: true

403)

404 

405last_sequence_number = -1

406response_id = ""

407stream.each do |event|

408 puts(event.type)

409 last_sequence_number = event.sequence_number

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

411 response_id = event.response.id

412 end

413end

414 

415puts("Response #{response_id}; last sequence number #{last_sequence_number}")

416 

417# If the connection drops, resume from the last sequence number:

418# client.responses.stream(response_id: response_id, starting_after: last_sequence_number).each do |event|

419# puts(event.type)

420# end

421```

422 

354 423 

355## Limits424## Limits

356 425 

160}160}

161```161```

162 162 

163```ruby

164require "openai"

165require "pathname"

166 

167client = OpenAI::Client.new

168file = Pathname("batchinput.jsonl")

169uploaded = client.files.create(file: file, purpose: :batch)

170puts(uploaded.id)

171```

172 

163```bash173```bash

164curl https://api.openai.com/v1/files \174curl https://api.openai.com/v1/files \

165 -H "Authorization: Bearer $OPENAI_API_KEY" \175 -H "Authorization: Bearer $OPENAI_API_KEY" \

227}237}

228```238```

229 239 

240```ruby

241require "openai"

242 

243client = OpenAI::Client.new

244batch = client.batches.create(input_file_id: "file-abc123", endpoint: "/v1/responses", completion_window: "24h")

245puts(batch.id)

246```

247 

230```bash248```bash

231curl https://api.openai.com/v1/batches \249curl https://api.openai.com/v1/batches \

232 -H "Authorization: Bearer $OPENAI_API_KEY" \250 -H "Authorization: Bearer $OPENAI_API_KEY" \

313}331}

314```332```

315 333 

334```ruby

335require "openai"

336 

337client = OpenAI::Client.new

338batch = client.batches.retrieve("batch_abc123")

339puts(batch.status)

340```

341 

316```bash342```bash

317curl https://api.openai.com/v1/batches/batch_abc123 \343curl https://api.openai.com/v1/batches/batch_abc123 \

318 -H "Authorization: Bearer $OPENAI_API_KEY" \344 -H "Authorization: Bearer $OPENAI_API_KEY" \

392}418}

393```419```

394 420 

421```ruby

422require "openai"

423 

424client = OpenAI::Client.new

425content = client.files.content("file-xyz123")

426puts(content.read)

427```

428 

395```bash429```bash

396curl https://api.openai.com/v1/files/file-xyz123/content \430curl https://api.openai.com/v1/files/file-xyz123/content \

397 -H "Authorization: Bearer $OPENAI_API_KEY" > batch_output.jsonl431 -H "Authorization: Bearer $OPENAI_API_KEY" > batch_output.jsonl

465}499}

466```500```

467 501 

502```ruby

503require "openai"

504 

505client = OpenAI::Client.new

506batch = client.batches.cancel("batch_abc123")

507puts(batch.status)

508```

509 

468```bash510```bash

469curl https://api.openai.com/v1/batches/batch_abc123/cancel \511curl https://api.openai.com/v1/batches/batch_abc123/cancel \

470 -H "Authorization: Bearer $OPENAI_API_KEY" \512 -H "Authorization: Bearer $OPENAI_API_KEY" \

525}567}

526```568```

527 569 

570```ruby

571require "openai"

572 

573client = OpenAI::Client.new

574client.batches.list(limit: 10).auto_paging_each do |batch|

575 puts(batch.id)

576end

577```

578 

528```bash579```bash

529curl https://api.openai.com/v1/batches?limit=10 \580curl https://api.openai.com/v1/batches?limit=10 \

530 -H "Authorization: Bearer $OPENAI_API_KEY" \581 -H "Authorization: Bearer $OPENAI_API_KEY" \

99}99}

100```100```

101 101 

102```ruby

103require "openai"

104 

105client = OpenAI::Client.new

106code = <<~PYTHON

107 def display_name(user):

108 return user.profile.name

109 

110 print(display_name(None))

111PYTHON

112 

113response = client.responses.create(

114 model: "gpt-5.6",

115 input: "Find the null pointer exception in this code:\n\n#{code}",

116 reasoning: {effort: :high}

117)

118 

119puts(response.output_text)

120```

121 

102```bash122```bash

103curl https://api.openai.com/v1/responses \123curl https://api.openai.com/v1/responses \

104 -H "Content-Type: application/json" \124 -H "Content-Type: application/json" \

139}139}

140```140```

141 141 

142```ruby

143require "openai"

144 

145client = OpenAI::Client.new

146conversation = [{

147 type: :message,

148 role: :user,

149 content: "Let's begin a long coding task."

150}]

151 

152response = client.responses.create(

153 model: "gpt-5.3-codex",

154 input: conversation,

155 store: false,

156 context_management: [{type: :compaction, compact_threshold: 200_000}]

157)

158conversation.concat(response.output)

159conversation << {

160 type: :message,

161 role: :user,

162 content: "Now implement the next step."

163}

164next_response = client.responses.create(

165 model: "gpt-5.3-codex",

166 input: conversation,

167 store: false,

168 context_management: [{type: :compaction, compact_threshold: 200_000}]

169)

170puts(next_response.output_text)

171```

172 

142 173 

143## Standalone compact endpoint174## Standalone compact endpoint

144 175 

260 return input291 return input

261}292}

262```293```

294 

295```ruby

296require "openai"

297 

298client = OpenAI::Client.new

299long_input = [{role: :user, content: "Plan a trip to Kyoto."}]

300compaction = client.responses.compact(

301 model: "gpt-5.6",

302 input: long_input

303)

304next_input = [

305 *compaction.output,

306 {type: :message, role: :user, content: "Add restaurant recommendations."}

307]

308response = client.responses.create(

309 model: "gpt-5.6",

310 input: next_input,

311 store: false

312)

313puts(response.output_text)

314```

46}46}

47```47```

48 48 

49```ruby

50require "openai"

51 

52client = OpenAI::Client.new

53completion = client.completions.create(model: "gpt-3.5-turbo-instruct", prompt: "Write a tagline for a bakery.", max_tokens: 24)

54puts(completion.choices.fetch(0).text)

55```

56 

49 57 

50See the full [API reference documentation](https://platform.openai.com/docs/api-reference/completions) to learn more.58See the full [API reference documentation](https://platform.openai.com/docs/api-reference/completions) to learn more.

51 59 

85}85}

86```86```

87 87 

88```ruby

89require "openai"

90 

91client = OpenAI::Client.new

92 

93response = client.responses.create(

94 model: "gpt-5.6",

95 input: [

96 {role: :user, content: "Knock knock."},

97 {role: :assistant, content: "Who's there?"},

98 {role: :user, content: "Orange."}

99 ]

100)

101 

102puts(response.output_text)

103```

104 

88 105 

89 106 

90By using alternating `user` and `assistant` messages, you capture the previous state of a conversation in one request to the model.107By using alternating `user` and `assistant` messages, you capture the previous state of a conversation in one request to the model.

220}237}

221```238```

222 239 

240```ruby

241require "openai"

242 

243client = OpenAI::Client.new

244history = [{role: :user, content: "Tell me a joke."}]

245 

246first = client.responses.create(

247 model: "gpt-5.6",

248 input: history,

249 store: false

250)

251puts(first.output_text)

252 

253history.concat(first.output.map(&:to_h))

254history << {role: :user, content: "Tell me another."}

255 

256second = client.responses.create(

257 model: "gpt-5.6",

258 input: history,

259 store: false

260)

261puts(second.output_text)

262```

263 

223 264 

224 265 

225## OpenAI APIs for conversation state266## OpenAI APIs for conversation state

249}290}

250```291```

251 292 

293```ruby

294conversation = client.conversations.create

295```

296 

252 297 

253In a multi-turn interaction, you can pass the `conversation` into subsequent responses to persist state and share context across subsequent responses, rather than having to chain multiple response items together.298In a multi-turn interaction, you can pass the `conversation` into subsequent responses to persist state and share context across subsequent responses, rather than having to chain multiple response items together.

254 299 

278fmt.Println(response.OutputText())323fmt.Println(response.OutputText())

279```324```

280 325 

326```ruby

327response = client.responses.create(

328 model: "gpt-5.6",

329 conversation: conversation.id,

330 input: "What are the five Ds of dodgeball?"

331)

332 

333puts(response.output_text)

334```

335 

281 336 

282### Passing context from the previous response337### Passing context from the previous response

283 338 

366}421}

367```422```

368 423 

424```ruby

425require "openai"

426 

427client = OpenAI::Client.new

428 

429first = client.responses.create(

430 model: "gpt-5.6",

431 input: "Tell me a joke."

432)

433puts(first.output_text)

434 

435second = client.responses.create(

436 model: "gpt-5.6",

437 previous_response_id: first.id,

438 input: "Explain why this is funny."

439)

440puts(second.output_text)

441```

442 

369 443 

370In the following example, we ask the model to tell a joke. Separately, we ask the model to explain why it's funny, and the model has all necessary context to deliver a good response.444In the following example, we ask the model to tell a joke. Separately, we ask the model to explain why it's funny, and the model has all necessary context to deliver a good response.

371 445 

453}527}

454```528```

455 529 

530```ruby

531require "openai"

532 

533client = OpenAI::Client.new

534 

535first = client.responses.create(

536 model: "gpt-5.6",

537 input: "Tell me a joke."

538)

539puts(first.output_text)

540 

541second = client.responses.create(

542 model: "gpt-5.6",

543 previous_response_id: first.id,

544 input: "Explain why this is funny."

545)

546puts(second.output_text)

547```

548 

456 549 

457#### `previous_response_id` in WebSocket mode550#### `previous_response_id` in WebSocket mode

458 551 

130}130}

131```131```

132 132 

133```ruby

134require "openai"

135 

136client = OpenAI::Client.new

137vector_store_id = ENV.fetch("OPENAI_VECTOR_STORE_ID")

138response = client.responses.create(

139 model: "o3-deep-research",

140 input: "Research the economic impact of semaglutide on global healthcare systems. Include measurable outcomes and cite primary sources.",

141 tools: [

142 {type: :web_search_preview},

143 {type: :file_search, vector_store_ids: [vector_store_id]},

144 {type: :code_interpreter, container: {type: :auto}}

145 ],

146 background: true

147)

148 

149while [

150 OpenAI::Responses::ResponseStatus::QUEUED,

151 OpenAI::Responses::ResponseStatus::IN_PROGRESS

152].include?(response.status)

153 sleep(2)

154 response = client.responses.retrieve(response.id)

155end

156unless response.status == OpenAI::Responses::ResponseStatus::COMPLETED

157 raise "Research ended with status: #{response.status}"

158end

159 

160puts(response.output_text)

161```

162 

133```bash163```bash

134curl https://api.openai.com/v1/responses \164curl https://api.openai.com/v1/responses \

135 -H "Authorization: Bearer $OPENAI_API_KEY" \165 -H "Authorization: Bearer $OPENAI_API_KEY" \

319}349}

320```350```

321 351 

352```ruby

353require "openai"

354 

355client = OpenAI::Client.new

356response = client.responses.create(

357 model: "gpt-5.6",

358 instructions: "Ask concise questions to gather all missing requirements. Do not conduct the research yet.",

359 input: "Research surfboards for me. I'm interested in ..."

360)

361 

362puts(response.output_text)

363```

364 

322```bash365```bash

323curl https://api.openai.com/v1/responses \366curl https://api.openai.com/v1/responses \

324-H "Authorization: Bearer $OPENAI_API_KEY" \367-H "Authorization: Bearer $OPENAI_API_KEY" \

587}630}

588```631```

589 632 

633```ruby

634require "openai"

635 

636client = OpenAI::Client.new

637response = client.responses.create(

638 model: "gpt-5.6",

639 instructions: "Rewrite the user's request as detailed research instructions. Preserve all stated preferences, identify open-ended dimensions, request primary sources, and specify a clear report format. Do not perform the research.",

640 input: "Research surfboards for me. I'm interested in ..."

641)

642 

643puts(response.output_text)

644```

645 

590```bash646```bash

591curl https://api.openai.com/v1/responses \647curl https://api.openai.com/v1/responses \

592 -H "Authorization: Bearer $OPENAI_API_KEY" \648 -H "Authorization: Bearer $OPENAI_API_KEY" \

741}797}

742```798```

743 799 

800```ruby

801require "openai"

802 

803client = OpenAI::Client.new

804mcp_server_url = ENV.fetch("OPENAI_MCP_SERVER_URL")

805response = client.responses.create(

806 model: "o3-deep-research",

807 input: "What patterns appear in our closed-lost Salesforce opportunities?",

808 instructions: "Produce a source-backed deep research report.",

809 reasoning: {summary: :auto},

810 tools: [{

811 type: :mcp,

812 server_label: "mycompany_mcp_server",

813 server_url: mcp_server_url,

814 require_approval: :never

815 }],

816 background: true

817)

818 

819while [

820 OpenAI::Responses::ResponseStatus::QUEUED,

821 OpenAI::Responses::ResponseStatus::IN_PROGRESS

822].include?(response.status)

823 sleep(2)

824 response = client.responses.retrieve(response.id)

825end

826unless response.status == OpenAI::Responses::ResponseStatus::COMPLETED

827 raise "Research ended with status: #{response.status}"

828end

829 

830puts(response.output_text)

831```

832 

744 833 

745[Build a deep research compatible remote MCP server834[Build a deep research compatible remote MCP server

746 835 

150}150}

151```151```

152 152 

153```ruby

154require "openai"

155 

156client = OpenAI::Client.new

157prompt = <<~PROMPT

158 Our CI job started failing after a dependency bump.

159 

160 Error:

161 TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'

162 

163 Identify the likeliest root cause and the smallest safe fix.

164PROMPT

165 

166response = client.responses.create(

167 model: "gpt-5.6",

168 reasoning: {effort: :xhigh, mode: :pro},

169 input: prompt

170)

171 

172puts(response.output_text)

173```

174 

153 175 

154## Set up `text.verbosity`176## Set up `text.verbosity`

155 177 

245}267}

246```268```

247 269 

270```ruby

271require "openai"

272 

273client = OpenAI::Client.new

274incident = <<~INCIDENT

275 Summarize this incident for the next on-call engineer.

276 - checkout latency spiked from 220 ms to 4.8 s

277 - only us-east-1 was affected

278 - rollback is complete

279 - likely trigger: cache stampede after deploy

280INCIDENT

281 

282response = client.responses.create(

283 model: "gpt-5.6",

284 text: {verbosity: :low},

285 input: incident

286)

287 

288puts(response.output_text)

289```

290 

248 291 

249## Set up the assistant `phase` parameter292## Set up the assistant `phase` parameter

250 293 

510}553}

511```554```

512 555 

556```ruby

557require "openai"

558 

559def namespace_tool(name, description, function_name, function_description, argument)

560 {

561 type: :namespace,

562 name: name,

563 description: description,

564 tools: [

565 {

566 type: :function,

567 name: function_name,

568 description: function_description,

569 defer_loading: true,

570 strict: true,

571 parameters: {

572 type: "object",

573 properties: {argument => {type: "string"}},

574 required: [argument],

575 additionalProperties: false

576 }

577 }

578 ]

579 }

580end

581 

582client = OpenAI::Client.new

583billing = namespace_tool(

584 "billing",

585 "Billing tools for invoices, payments, taxes, and credits.",

586 "lookup_invoice",

587 "Look up invoice state, taxes, credits, and payment attempts.",

588 "invoice_id"

589)

590crm = namespace_tool(

591 "crm",

592 "CRM tools for account ownership, plans, health, and payment history.",

593 "get_account",

594 "Fetch account owner, plan, health, and payment history.",

595 "account_id"

596)

597 

598response = client.responses.create(

599 model: "gpt-5.6",

600 input: "Find the right billing tool and explain why invoice INV-1043 still shows overdue after a payment yesterday.",

601 tools: [billing, crm, {type: :tool_search}]

602)

603 

604puts(response.output)

605```

606 

513 607 

514## Use Programmatic Tool Calling608## Use Programmatic Tool Calling

515 609 

740}834}

741```835```

742 836 

837```ruby

838require "openai"

839 

840client = OpenAI::Client.new

841long_window = [

842 {

843 role: :user,

844 content: "Find the cache invalidation bug in this debugging session."

845 }

846]

847 

848compacted = client.responses.compact(

849 model: "gpt-5.6",

850 input: long_window

851)

852input = compacted.output.map(&:to_h)

853input << {

854 role: :user,

855 content: "We found the bad cache invalidation path. Write the fix plan and the verification checklist."

856}

857 

858response = client.responses.create(

859 model: "gpt-5.6",

860 store: false,

861 input: input

862)

863 

864puts(response.output_text)

865```

866 

743 867 

744## Use `prompt_cache_key`868## Use `prompt_cache_key`

745 869 

846}970}

847```971```

848 972 

973```ruby

974require "openai"

975 

976client = OpenAI::Client.new

977instructions = <<~INSTRUCTIONS

978 You are the support agent for Acme.

979 Follow the Acme support policy and escalation rubric.

980 Use the same tone, safety rules, and tool plan for each ticket.

981INSTRUCTIONS

982 

983response = client.responses.create(

984 model: "gpt-5.6",

985 prompt_cache_key: "tenant-acme-support-agent",

986 instructions: instructions,

987 input: "Summarize the current escalation for the on-call lead."

988)

989 

990puts(response.output_text)

991```

992 

849 993 

850## Use `reasoning.encrypted_content`994## Use `reasoning.encrypted_content`

851 995 

1003}1147}

1004```1148```

1005 1149 

1150```ruby

1151require "openai"

1152 

1153client = OpenAI::Client.new

1154history = [

1155 {

1156 role: :user,

1157 content: "Investigate why invoice INV-1043 has mismatched tax totals."

1158 }

1159]

1160 

1161first = client.responses.create(

1162 model: "gpt-5.6",

1163 store: false,

1164 reasoning: {effort: :medium, context: :current_turn},

1165 include: ["reasoning.encrypted_content"],

1166 input: history

1167)

1168history.concat(first.output.map(&:to_h))

1169history << {

1170 role: :user,

1171 content: "Now write the customer-facing explanation in plain English."

1172}

1173 

1174second = client.responses.create(

1175 model: "gpt-5.6",

1176 store: false,

1177 reasoning: {effort: :medium, context: :all_turns},

1178 input: history

1179)

1180 

1181puts(second.output_text)

1182```

1183 

1006 1184 

1007## Set image detail intentionally1185## Set image detail intentionally

1008 1186 

1136}1314}

1137```1315```

1138 1316 

1317```ruby

1318require "openai"

1319 

1320client = OpenAI::Client.new

1321 

1322job = client.responses.create(

1323 model: "gpt-5.6",

1324 background: true,

1325 store: false,

1326 input: "Analyze this large log bundle and cluster the primary failure modes.",

1327 tools: [

1328 {

1329 type: :code_interpreter,

1330 container: {type: :auto, file_ids: ["file_abc123"]}

1331 }

1332 ]

1333)

1334 

1335while [:queued, :in_progress].include?(job.status)

1336 sleep(2)

1337 job = client.responses.retrieve(job.id)

1338end

1339 

1340puts(job.output_text)

1341```

1342 

1139 1343 

1140You can combine it with `stream=True` for progress events, but the first event1344You can combine it with `stream=True` for progress events, but the first event

1141may take longer than a normal request.1345may take longer than a normal request.

160}160}

161```161```

162 162 

163```ruby

164require "openai"

165 

166client = OpenAI::Client.new

167job = client.fine_tuning.jobs.create(

168 model: "gpt-4.1-mini-2025-04-14",

169 training_file: "file-all-about-the-weather",

170 method_: {

171 type: :dpo,

172 dpo: {hyperparameters: {beta: 0.1}}

173 }

174)

175puts(job.id)

176```

177 

163 178 

164## Use SFT and DPO together179## Use SFT and DPO together

165 180 

75}75}

76```76```

77 77 

78```ruby

79require "openai"

80 

81client = OpenAI::Client.new

82 

83response = client.embeddings.create(

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

85 input: "The food was delicious and the waiter..."

86)

87 

88puts(response.data.fetch(0).embedding)

89```

90 

78```bash91```bash

79curl https://api.openai.com/v1/embeddings \92curl https://api.openai.com/v1/embeddings \

80 -H "Content-Type: application/json" \93 -H "Content-Type: application/json" \

290 fmt.Println(response.OutputText())290 fmt.Println(response.OutputText())

291}291}

292```292```

293 

294```ruby

295require "openai"

296 

297client = OpenAI::Client.new

298begin

299 response = client.responses.create(model: "gpt-5.6", input: "Say hello.")

300 puts(response.output_text)

301rescue OpenAI::Errors::APIError => error

302 warn(error.message)

303end

304```