Documentation 2026-07-24 19:01 UTC to 2026-07-25 05:59 UTC

21 21 

22```python22```python

23file = client.files.create(23file = client.files.create(

24 file=open("revenue-forecast.csv", "rb"),24 file=open("revenue-forecast.csv", "rb"), purpose="assistants"

25 purpose='assistants'

26)25)

27```26```

28 27 

49 description="You are great at creating beautiful data visualizations. You analyze data present in .csv files, understand trends, and come up with data visualizations relevant to those trends. You also share a brief text summary of the trends observed.",48 description="You are great at creating beautiful data visualizations. You analyze data present in .csv files, understand trends, and come up with data visualizations relevant to those trends. You also share a brief text summary of the trends observed.",

50 model="gpt-4o",49 model="gpt-4o",

51 tools=[{"type": "code_interpreter"}],50 tools=[{"type": "code_interpreter"}],

52 tool_resources={51 tool_resources={"code_interpreter": {"file_ids": [file.id]}},

53 "code_interpreter": {

54 "file_ids": [file.id]

55 }

56 }

57)52)

58```53```

59 54 

107 "role": "user",102 "role": "user",

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

109 "attachments": [104 "attachments": [

110 {105 {"file_id": file.id, "tools": [{"type": "code_interpreter"}]}

111 "file_id": file.id,106 ],

112 "tools": [{"type": "code_interpreter"}]

113 }

114 ]

115 }107 }

116 ]108 ]

117)109)

165Tools cannot access image content unless specified. To pass image files to Code Interpreter, add the file ID in the message `attachments` list to allow the tool to read and analyze the input. Image URLs cannot be downloaded in Code Interpreter today.157Tools cannot access image content unless specified. To pass image files to Code Interpreter, add the file ID in the message `attachments` list to allow the tool to read and analyze the input. Image URLs cannot be downloaded in Code Interpreter today.

166 158 

167```python159```python

168file = client.files.create(160file = client.files.create(file=open("myimage.png", "rb"), purpose="vision")

169 file=open("myimage.png", "rb"),

170 purpose="vision"

171)

172thread = client.beta.threads.create(161thread = client.beta.threads.create(

173 messages=[162 messages=[

174 {163 {

176 "content": [165 "content": [

177 {166 {

178 "type": "text",167 "type": "text",

179 "text": "What is the difference between these images?"168 "text": "What is the difference between these images?",

180 },169 },

181 {170 {

182 "type": "image_url",171 "type": "image_url",

183 "image_url": {"url": "https://example.com/image.png"}172 "image_url": {

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

184 },174 },

185 {

186 "type": "image_file",

187 "image_file": {"file_id": file.id}

188 },175 },

176 {"type": "image_file", "image_file": {"file_id": file.id}},

189 ],177 ],

190 }178 }

191 ]179 ]

209 },198 },

210 {199 {

211 "type": "image_url",200 "type": "image_url",

212 "image_url": {"url": "https://example.com/image.png"}201 "image_url": {"url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"}

213 },202 },

214 {203 {

215 "type": "image_file",204 "type": "image_file",

245},234},

246{235{

247"type": "image_url",236"type": "image_url",

248"image_url": {"url": "https://example.com/image.png"}237"image_url": {"url": "https://openai-documentation.vercel.app/images/cat_and_otter.png"}

249},238},

250{239{

251"type": "image_file",240"type": "image_file",

271 {260 {

272 "role": "user",261 "role": "user",

273 "content": [262 "content": [

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

275 "type": "text",

276 "text": "What is this an image of?"

277 },

278 {264 {

279 "type": "image_url",265 "type": "image_url",

280 "image_url": {266 "image_url": {

281 "url": "https://example.com/image.png",267 "url": "https://openai-documentation.vercel.app/images/cat_and_otter.png",

282 "detail": "high"268 "detail": "high",

283 }269 },

284 },270 },

285 ],271 ],

286 }272 }

301 {287 {

302 "type": "image_url",288 "type": "image_url",

303 "image_url": {289 "image_url": {

304 "url": "https://example.com/image.png",290 "url": "https://openai-documentation.vercel.app/images/cat_and_otter.png",

305 "detail": "high"291 "detail": "high"

306 }292 }

307 },293 },

328 {314 {

329 "type": "image_url",315 "type": "image_url",

330 "image_url": {316 "image_url": {

331 "url": "https://example.com/image.png",317 "url": "https://openai-documentation.vercel.app/images/cat_and_otter.png",

332 "detail": "high"318 "detail": "high"

333 }319 }

334 },320 },

373When annotations are present in the Message object, you'll see illegible model-generated substrings in the text that you should replace with the annotations. These strings may look something like `【13†source】` or `sandbox:/mnt/data/file.csv`. Here’s an example python code snippet that replaces these strings with the annotations.359When annotations are present in the Message object, you'll see illegible model-generated substrings in the text that you should replace with the annotations. These strings may look something like `【13†source】` or `sandbox:/mnt/data/file.csv`. Here’s an example python code snippet that replaces these strings with the annotations.

374 360 

375```python361```python

362import os

363from pathlib import Path

364 

365thread_id = os.environ["OPENAI_THREAD_ID"]

366message_id = os.environ["OPENAI_MESSAGE_ID"]

367downloads = Path("downloads")

368downloads.mkdir(exist_ok=True)

369 

376# Retrieve the message object370# Retrieve the message object

377message = client.beta.threads.messages.retrieve(371message = client.beta.threads.messages.retrieve(

378 thread_id="...",372 thread_id=thread_id,

379 message_id="..."373 message_id=message_id,

380)374)

381 375 

382# Extract the message content376# Extract the message content

387 381 

388# Iterate over the annotations and add footnotes382# Iterate over the annotations and add footnotes

389 383 

390for index, annotation in enumerate(annotations): # Replace the text with a footnote384for index, annotation in enumerate(annotations):

391message_content.value = message_content.value.replace(annotation.text, f' [{index}]')385 # Replace the text with a footnote.

386 message_content.value = message_content.value.replace(

387 annotation.text, f" [{index}]"

388 )

392 389 

393 # Gather citations based on annotation attributes390 # Gather citations based on annotation attributes

394 if (file_citation := getattr(annotation, 'file_citation', None)):391 if file_citation := getattr(annotation, "file_citation", None):

395 cited_file = client.files.retrieve(file_citation.file_id)392 cited_file = client.files.retrieve(file_citation.file_id)

396 citations.append(f'[{index}] {file_citation.quote} from {cited_file.filename}')393 citations.append(f"[{index}] {file_citation.quote} from {cited_file.filename}")

397 elif (file_path := getattr(annotation, 'file_path', None)):394 elif file_path := getattr(annotation, "file_path", None):

398 cited_file = client.files.retrieve(file_path.file_id)395 cited_file = client.files.retrieve(file_path.file_id)

399 citations.append(f'[{index}] Click <here> to download {cited_file.filename}')396 file_content = client.files.content(file_path.file_id)

400 # Note: File download functionality not implemented above for brevity397 output_path = downloads / Path(cited_file.filename).name

398 output_path.write_bytes(file_content.read())

399 citations.append(f"[{index}] Downloaded {output_path}")

401 400 

402# Add footnotes to the end of the message before displaying to user401# Add footnotes to the end of the message before displaying to user

403 402 

404message_content.value += '\n' + '\n'.join(citations)403message_content.value += "\n" + "\n".join(citations)

405```404```

406 405 

407 406 

412```python411```python

413run = client.beta.threads.runs.create(412run = client.beta.threads.runs.create(

414 thread_id=thread.id,413 thread_id=thread.id,

415 assistant_id=assistant.id414 assistant_id=assistant.id,

416)415)

417```416```

418 417 

442 assistant_id=assistant.id,441 assistant_id=assistant.id,

443 model="gpt-4o",442 model="gpt-4o",

444 instructions="New instructions that override the Assistant instructions",443 instructions="New instructions that override the Assistant instructions",

445 tools=[{"type": "code_interpreter"}, {"type": "file_search"}]444 tools=[{"type": "code_interpreter"}, {"type": "file_search"}],

446)445)

447```446```

448 447 

94 client:load94 client:load

95 snippets={[95 snippets={[

96 {96 {

97 language: "python",97 language: "json",

98 code: `98 code: `

99{99{

100 "id": "run_FKIpcs5ECSwuCmehBqsqkORj",100 "id": "run_FKIpcs5ECSwuCmehBqsqkORj",

144 title: "Run object",144 title: "Run object",

145 },145 },

146 {146 {

147 language: "python",147 language: "json",

148 code: `148 code: `

149{149{

150 "id": "resp_687a7b53036c819baad6012d58b39bcb074adcd9e24850fc",150 "id": "resp_687a7b53036c819baad6012d58b39bcb074adcd9e24850fc",

237 237 

238### 2. Move new user chats over to conversations and responses238### 2. Move new user chats over to conversations and responses

239 239 

240We will not provide an automated tool for migrating Threads to Conversations. Instead, we recommend migrating new user threads onto conversations and backfilling old ones as necessary.240We will not provide an automated tool for migrating Threads to Conversations. Instead, we recommend migrating new user threads onto conversations and migrating older ones as necessary.

241 241 

242Here's an example for how you might backfill a thread:242Here's an example for how you might backfill a thread:

243 243 

244```python244```python

245thread_id = "thread_EIpHrTAVe0OzoLQg3TXfvrkG"245import os

246 246 

247for page in openai.beta.threads.messages.list(thread_id=thread_id, order="asc").iter_pages():247from openai import OpenAI

248 

249openai = OpenAI()

250messages = []

251thread_id = os.environ["OPENAI_THREAD_ID"]

252 

253for page in openai.beta.threads.messages.list(

254 thread_id=thread_id, order="asc"

255).iter_pages():

248 messages += page.data256 messages += page.data

249 257 

250items = []258items = []

256 match content.type:264 match content.type:

257 case "text":265 case "text":

258 item_content_type = "input_text" if m.role == "user" else "output_text"266 item_content_type = "input_text" if m.role == "user" else "output_text"

259 item_content += [{"type": item_content_type, "text": content.text.value}]267 item_content += [

268 {"type": item_content_type, "text": content.text.value}

269 ]

260 case "image_url":270 case "image_url":

261 item_content + [271 item_content += [

262 {272 {

263 "type": "input_image",273 "type": "input_image",

264 "image_url": content.image_url.url,274 "image_url": content.image_url.url,

276 286 

277## Comparing full examples287## Comparing full examples

278 288 

279Here’s a few simple examples of integrations using both the Assistants API and the Responses API so you can see how they compare.289Here are a few examples of integrations using both the Assistants API and the Responses API so you can see how they compare.

280 290 

281### User chat app291### User chat app

282 292 

285<div data-content-switcher-pane data-value="assistants">295<div data-content-switcher-pane data-value="assistants">

286 <div class="hidden">Assistants API</div>296 <div class="hidden">Assistants API</div>

287 ```python297 ```python

288thread = openai.threads.create()298threads_by_session: dict[str, str] = {}

299 

300 

301@app.post("/messages")

302async def message(message: Message):

303 thread_id = threads_by_session.get(message.session_id)

304 if thread_id is None:

305 thread_id = openai.beta.threads.create().id

306 threads_by_session[message.session_id] = thread_id

289 307 

290 @app.post("/messages")

291 async def message(message: Message):

292 openai.beta.threads.messages.create(308 openai.beta.threads.messages.create(

309 thread_id=thread_id,

293 role="user",310 role="user",

294 content=message.content311 content=message.content,

295 )312 )

296 313 

297 run = openai.beta.threads.runs.create(314 run = openai.beta.threads.runs.create(

298 assistant_id=os.getenv("ASSISTANT_ID"),315 assistant_id=os.environ["OPENAI_ASSISTANT_ID"],

299 thread_id=thread.id316 thread_id=thread_id,

300 )317 )

301 while run.status in ("queued", "in_progress"):318 while run.status in ("queued", "in_progress"):

302 await asyncio.sleep(1)319 await asyncio.sleep(1)

303 run = openai.beta.threads.runs.retrieve(thread_id=thread_id, run_id=run.id)320 run = openai.beta.threads.runs.retrieve(

321 thread_id=thread_id,

322 run_id=run.id,

323 )

304 324 

305 messages = openai.beta.threads.messages.list(325 messages = openai.beta.threads.messages.list(

306 order="desc", limit=1, thread_id=thread.id326 order="desc",

327 limit=1,

328 thread_id=thread_id,

307 )329 )

308 330 

309 return { "content": messages[-1].content }331 return {"content": messages.data[0].content}

310```332```

311 333 

312 334 

314 <div data-content-switcher-pane data-value="responses" hidden>336 <div data-content-switcher-pane data-value="responses" hidden>

315 <div class="hidden">Responses API</div>337 <div class="hidden">Responses API</div>

316 ```python338 ```python

317conversation = openai.conversations.create()339conversations_by_session: dict[str, str] = {}

340 

341 

342@app.post("/messages")

343async def message(message: Message):

344 conversation_id = conversations_by_session.get(message.session_id)

345 if conversation_id is None:

346 conversation_id = openai.conversations.create().id

347 conversations_by_session[message.session_id] = conversation_id

318 348 

319 @app.post("/messages")

320 async def message(message: Message):

321 response = openai.responses.create(349 response = openai.responses.create(

322 prompt={ "id": os.getenv("PROMPT_ID") },350 prompt={"id": os.environ["OPENAI_PROMPT_ID"]},

323 input=[{ "role": "user", "content": message.content }]351 input=[{"role": "user", "content": message.content}],

352 conversation=conversation_id,

324 )353 )

325 354 

326 return { "content": response.output_text }355 return {"content": response.output_text}

327```356```

328 357 

329 358 

18assistant = client.beta.assistants.create(18assistant = client.beta.assistants.create(

19 instructions="You are a personal math tutor. When asked a math question, write and run code to answer the question.",19 instructions="You are a personal math tutor. When asked a math question, write and run code to answer the question.",

20 model="gpt-4o",20 model="gpt-4o",

21 tools=[{"type": "code_interpreter"}]21 tools=[{"type": "code_interpreter"}],

22)22)

23```23```

24 24 

53 53 

54```python54```python

55# Upload a file with an "assistants" purpose55# Upload a file with an "assistants" purpose

56file = client.files.create(56file = client.files.create(file=open("mydata.csv", "rb"), purpose="assistants")

57 file=open("mydata.csv", "rb"),

58 purpose='assistants'

59)

60 57 

61# Create an assistant using the file ID58# Create an assistant using the file ID

62assistant = client.beta.assistants.create(59assistant = client.beta.assistants.create(

63 instructions="You are a personal math tutor. When asked a math question, write and run code to answer the question.",60 instructions="You are a personal math tutor. When asked a math question, write and run code to answer the question.",

64 model="gpt-4o",61 model="gpt-4o",

65 tools=[{"type": "code_interpreter"}],62 tools=[{"type": "code_interpreter"}],

66 tool_resources={63 tool_resources={"code_interpreter": {"file_ids": [file.id]}},

67 "code_interpreter": {

68 "file_ids": [file.id]

69 }

70 }

71)64)

72```65```

73 66 

125 "role": "user",118 "role": "user",

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

127 "attachments": [120 "attachments": [

128 {121 {"file_id": file.id, "tools": [{"type": "code_interpreter"}]}

129 "file_id": file.id,122 ],

130 "tools": [{"type": "code_interpreter"}]

131 }

132 ]

133 }123 }

134 ]124 ]

135)125)

203The file content can then be downloaded by passing the file ID to the Files API:193The file content can then be downloaded by passing the file ID to the Files API:

204 194 

205```python195```python

196import os

197 

206from openai import OpenAI198from openai import OpenAI

207 199 

200file_id = os.environ["OPENAI_FILE_ID"]

208client = OpenAI()201client = OpenAI()

209 202 

210image_data = client.files.content("file-abc123")203image_data = client.files.content(file_id)

211image_data_bytes = image_data.read()204image_data_bytes = image_data.read()

212 205 

213with open("./my-image.png", "wb") as file:206with open("./my-image.png", "wb") as file:

275By listing the steps of a Run that called Code Interpreter, you can inspect the code `input` and `outputs` logs of Code Interpreter:268By listing the steps of a Run that called Code Interpreter, you can inspect the code `input` and `outputs` logs of Code Interpreter:

276 269 

277```python270```python

271import os

272 

273thread_id = os.environ["OPENAI_THREAD_ID"]

274run_id = os.environ["OPENAI_RUN_ID"]

275 

278run_steps = client.beta.threads.runs.steps.list(276run_steps = client.beta.threads.runs.steps.list(

279 thread_id=thread.id,277 thread_id=thread_id,

280 run_id=run.id278 run_id=run_id,

281)279)

282```280```

283 281 

18client = OpenAI()18client = OpenAI()

19 19 

20assistant = client.beta.assistants.create(20assistant = client.beta.assistants.create(

21name="Financial Analyst Assistant",21 name="Financial Analyst Assistant",

22instructions="You are an expert financial analyst. Use you knowledge base to answer questions about audited financial statements.",22 instructions="You are an expert financial analyst. Use you knowledge base to answer questions about audited financial statements.",

23model="gpt-4o",23 model="gpt-4o",

24tools=[{"type": "file_search"}],24 tools=[{"type": "file_search"}],

25)25)

26```26```

27 27 

78# and poll the status of the file batch for completion.78# and poll the status of the file batch for completion.

79 79 

80file_batch = client.vector_stores.file_batches.upload_and_poll(80file_batch = client.vector_stores.file_batches.upload_and_poll(

81vector_store_id=vector_store.id, files=file_streams81 vector_store_id=vector_store.id, files=file_streams

82)82)

83 83 

84# You can print the status and the file counts of the batch to see the result of this operation.84# You can print the status and the file counts of the batch to see the result of this operation.

134# Create a thread and attach the file to the message134# Create a thread and attach the file to the message

135 135 

136thread = client.beta.threads.create(136thread = client.beta.threads.create(

137messages=[137 messages=[

138{138 {

139"role": "user",139 "role": "user",

140"content": "How many shares of AAPL were outstanding at the end of of October 2023?", # Attach the new file to the message.140 "content": "How many shares of AAPL were outstanding at the end of of October 2023?", # Attach the new file to the message.

141"attachments": [141 "attachments": [

142{ "file_id": message_file.id, "tools": [{"type": "file_search"}] }142 {"file_id": message_file.id, "tools": [{"type": "file_search"}]}

143],143 ],

144}144 }

145]145 ]

146)146)

147 147 

148# The thread now has a vector store with that file in its tool resources.148# The thread now has a vector store with that file in its tool resources.

191client = OpenAI()191client = OpenAI()

192 192 

193class EventHandler(AssistantEventHandler):193class EventHandler(AssistantEventHandler):

194@override194 @override

195def on_text_created(self, text) -> None:195 def on_text_created(self, text) -> None:

196print(f"\nassistant > ", end="", flush=True)196 print("\nassistant > ", end="", flush=True)

197 197 

198 @override198 @override

199 def on_tool_call_created(self, tool_call):199 def on_tool_call_created(self, tool_call):

223# and stream the response.223# and stream the response.

224 224 

225with client.beta.threads.runs.stream(225with client.beta.threads.runs.stream(

226thread_id=thread.id,226 thread_id=thread.id,

227assistant_id=assistant.id,227 assistant_id=assistant.id,

228instructions="Please address the user as Jane Doe. The user has a premium account.",228 instructions="Please address the user as Jane Doe. The user has a premium account.",

229event_handler=EventHandler(),229 event_handler=EventHandler(),

230) as stream:230) as stream:

231stream.until_done()231 stream.until_done()

232```232```

233 233 

234```javascript234```javascript

268# the run until it's in a terminal state.268# the run until it's in a terminal state.

269 269 

270run = client.beta.threads.runs.create_and_poll(270run = client.beta.threads.runs.create_and_poll(

271thread_id=thread.id, assistant_id=assistant.id271 thread_id=thread.id,

272 assistant_id=assistant.id,

272)273)

273 274 

274messages = list(client.beta.threads.messages.list(thread_id=thread.id, run_id=run.id))275messages = list(

276 client.beta.threads.messages.list(thread_id=thread.id, run_id=run.id)

277)

275 278 

276message_content = messages[0].content[0].text279message_content = messages[0].content[0].text

277annotations = message_content.annotations280annotations = message_content.annotations

278citations = []281citations = []

279for index, annotation in enumerate(annotations):282for index, annotation in enumerate(annotations):

280message_content.value = message_content.value.replace(annotation.text, f"[{index}]")283 message_content.value = message_content.value.replace(

281if file_citation := getattr(annotation, "file_citation", None):284 annotation.text, f"[{index}]"

282cited_file = client.files.retrieve(file_citation.file_id)285 )

283citations.append(f"[{index}] {cited_file.filename}")286 if file_citation := getattr(annotation, "file_citation", None):

287 cited_file = client.files.retrieve(file_citation.file_id)

288 citations.append(f"[{index}] {cited_file.filename}")

284 289 

285print(message_content.value)290print(message_content.value)

286print("\n".join(citations))291print("\n".join(citations))

365```python370```python

366vector_store = client.vector_stores.create(371vector_store = client.vector_stores.create(

367 name="Product Documentation",372 name="Product Documentation",

368 file_ids=['file_1', 'file_2', 'file_3', 'file_4', 'file_5']373 file_ids=[

374 "file_1",

375 "file_2",

376 "file_3",

377 "file_4",

378 "file_5",

379 ],

369)380)

370```381```

371 382 

385 396 

386```python397```python

387file = client.vector_stores.files.create_and_poll(398file = client.vector_stores.files.create_and_poll(

388 vector_store_id="vs_abc123",399 vector_store_id="vs_abc123", file_id="file-abc123"

389 file_id="file-abc123"

390)400)

391```401```

392 402 

408batch = client.vector_stores.file_batches.create_and_poll(418batch = client.vector_stores.file_batches.create_and_poll(

409 vector_store_id="vs_abc123",419 vector_store_id="vs_abc123",

410 files=[420 files=[

411 {421 {"file_id": "file_1", "attributes": {"category": "finance"}},

412 "file_id": "file_1",

413 "attributes": {"category": "finance"}

414 },

415 {422 {

416 "file_id": "file_2",423 "file_id": "file_2",

417 "chunking_strategy": {424 "chunking_strategy": {

418 "type": "static",425 "type": "static",

419 "max_chunk_size_tokens": 1000,426 "max_chunk_size_tokens": 1000,

420 "chunk_overlap_tokens": 200427 "chunk_overlap_tokens": 200,

421 }428 },

422 }429 },

423 ]430 ],

424)431)

425```432```

426 433 

465 instructions="You are a helpful product support assistant and you answer questions based on the files provided to you.",472 instructions="You are a helpful product support assistant and you answer questions based on the files provided to you.",

466 model="gpt-4o",473 model="gpt-4o",

467 tools=[{"type": "file_search"}],474 tools=[{"type": "file_search"}],

468 tool_resources={475 tool_resources={"file_search": {"vector_store_ids": ["vs_1"]}},

469 "file_search": {

470 "vector_store_ids": ["vs_1"]

471 }

472 }

473)476)

474 477 

475thread = client.beta.threads.create(478thread = client.beta.threads.create(

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

477tool_resources={480 tool_resources={"file_search": {"vector_store_ids": ["vs_2"]}},

478"file_search": {

479"vector_store_ids": ["vs_2"]

480}

481}

482)481)

483```482```

484 483 

553client = OpenAI()553client = OpenAI()

554 554 

555run_step = client.beta.threads.runs.steps.retrieve(555run_step = client.beta.threads.runs.steps.retrieve(

556thread_id="thread_abc123",556 thread_id="thread_abc123",

557run_id="run_abc123",557 run_id="run_abc123",

558step_id="step_abc123",558 step_id="step_abc123",

559include=["step_details.tool_calls[*].file_search.results[*].content"]559 include=["step_details.tool_calls[*].file_search.results[*].content"],

560)560)

561 561 

562print(run_step)562print(run_step)

610In order to help you manage the costs associated with these `vector_store` objects, we have added support for expiration policies in the `vector_store` object. You can set these policies when creating or updating the `vector_store` object.611In order to help you manage the costs associated with these `vector_store` objects, we have added support for expiration policies in the `vector_store` object. You can set these policies when creating or updating the `vector_store` object.

611 612 

612```python613```python

613vector_store = client.vector_stores.create_and_poll(614vector_store = client.vector_stores.create(

614 name="Product Documentation",615 name="Product Documentation",

615 file_ids=['file_1', 'file_2', 'file_3', 'file_4', 'file_5'],616 file_ids=[

616 expires_after={617 "file_1",

617 "anchor": "last_active_at",618 "file_2",

618 "days": 7619 "file_3",

619 }620 "file_4",

621 "file_5",

622 ],

623 expires_after={"anchor": "last_active_at", "days": 7},

620)624)

621```625```

622 626 

643 647 

644vector_store = client.vector_stores.create(name="rag-store")648vector_store = client.vector_stores.create(name="rag-store")

645client.beta.threads.update(649client.beta.threads.update(

646"thread_abc123",650 "thread_abc123",

647tool_resources={"file_search": {"vector_store_ids": [vector_store.id]}},651 tool_resources={"file_search": {"vector_store_ids": [vector_store.id]}},

648)652)

649 653 

650for file_batch in chunked(all_files, 100):654for file_batch in chunked(all_files, 100):

651client.vector_stores.file_batches.create_and_poll(655 client.vector_stores.file_batches.create_and_poll(

652vector_store_id=vector_store.id, file_ids=[file.id for file in file_batch]656 vector_store_id=vector_store.id,

653)657 file_ids=[file.id for file in file_batch],

658 )

654```659```

655 660 

656```javascript661```javascript

657const fileIds = [];662const fileIds = [];

658for await (const file of openai.vectorStores.files.list(663for await (const file of openai.vectorStores.files.list(

659"vs_toWTk90YblRLCkbE2xSVoJlF",664"vs_expired",

660)) {665)) {

661fileIds.push(file.id);666fileIds.push(file.id);

662}667}

664const vectorStore = await openai.vectorStores.create({669const vectorStore = await openai.vectorStores.create({

665name: "rag-store",670name: "rag-store",

666});671});

667await openai.beta.threads.update("thread_abcd", {672await openai.beta.threads.update("thread_abc123", {

668tool_resources: { file_search: { vector_store_ids: [vectorStore.id] } },673tool_resources: { file_search: { vector_store_ids: [vectorStore.id] } },

669});674});

670 675 

29client = OpenAI()30client = OpenAI()

30 31 

31assistant = client.beta.assistants.create(32assistant = client.beta.assistants.create(

32instructions="You are a weather bot. Use the provided functions to answer questions.",33 instructions="You are a weather bot. Use the provided functions to answer questions.",

33model="gpt-4o",34 model="gpt-4o",

34tools=[35 tools=[

35{36 {

36"type": "function",37 "type": "function",

37"function": {38 "function": {

38"name": "get_current_temperature",39 "name": "get_current_temperature",

39"description": "Get the current temperature for a specific location",40 "description": "Get the current temperature for a specific location",

40"parameters": {41 "parameters": {

41"type": "object",42 "type": "object",

42"properties": {43 "properties": {

43"location": {44 "location": {

44"type": "string",45 "type": "string",

45"description": "The city and state, e.g., San Francisco, CA"46 "description": "The city and state, e.g., San Francisco, CA",

46},47 },

47"unit": {48 "unit": {

48"type": "string",49 "type": "string",

49"enum": ["Celsius", "Fahrenheit"],50 "enum": ["Celsius", "Fahrenheit"],

50"description": "The temperature unit to use. Infer this from the user's location."51 "description": "The temperature unit to use. Infer this from the user's location.",

51}52 },

52},53 },

53"required": ["location", "unit"]54 "required": ["location", "unit"],

54}55 },

55}56 },

56},57 },

57{58 {

58"type": "function",59 "type": "function",

59"function": {60 "function": {

60"name": "get_rain_probability",61 "name": "get_rain_probability",

61"description": "Get the probability of rain for a specific location",62 "description": "Get the probability of rain for a specific location",

62"parameters": {63 "parameters": {

63"type": "object",64 "type": "object",

64"properties": {65 "properties": {

65"location": {66 "location": {

66"type": "string",67 "type": "string",

67"description": "The city and state, e.g., San Francisco, CA"68 "description": "The city and state, e.g., San Francisco, CA",

68}69 }

69},70 },

70"required": ["location"]71 "required": ["location"],

71}72 },

72}73 },

73}74 },

74]75 ],

75)76)

76```77```

77 78 

221client = OpenAI()223client = OpenAI()

222 224 

223assistant = client.beta.assistants.create(225assistant = client.beta.assistants.create(

224instructions="You are a weather bot. Use the provided functions to answer questions.",226 instructions="You are a weather bot. Use the provided functions to answer questions.",

225model="gpt-4o-2024-08-06",227 model="gpt-4o-2024-08-06",

226tools=[228 tools=[

227{229 {

228"type": "function",230 "type": "function",

229"function": {231 "function": {

230"name": "get_current_temperature",232 "name": "get_current_temperature",

231"description": "Get the current temperature for a specific location",233 "description": "Get the current temperature for a specific location",

232"parameters": {234 "parameters": {

233"type": "object",235 "type": "object",

234"properties": {236 "properties": {

235"location": {237 "location": {

236"type": "string",238 "type": "string",

237"description": "The city and state, e.g., San Francisco, CA"239 "description": "The city and state, e.g., San Francisco, CA",

238},240 },

239"unit": {241 "unit": {

240"type": "string",242 "type": "string",

241"enum": ["Celsius", "Fahrenheit"],243 "enum": ["Celsius", "Fahrenheit"],

242"description": "The temperature unit to use. Infer this from the user's location."244 "description": "The temperature unit to use. Infer this from the user's location.",

243}245 },

244},246 },

245"required": ["location", "unit"],247 "required": ["location", "unit"],

246// highlight-start248 # highlight-start

247"additionalProperties": False249 "additionalProperties": False,

248// highlight-end250 # highlight-end

249},251 },

250// highlight-start252 # highlight-start

251"strict": True253 "strict": True,

252// highlight-end254 # highlight-end

253}255 },

254},256 },

255{257 {

256"type": "function",258 "type": "function",

257"function": {259 "function": {

258"name": "get_rain_probability",260 "name": "get_rain_probability",

259"description": "Get the probability of rain for a specific location",261 "description": "Get the probability of rain for a specific location",

260"parameters": {262 "parameters": {

261"type": "object",263 "type": "object",

262"properties": {264 "properties": {

263"location": {265 "location": {

264"type": "string",266 "type": "string",

265"description": "The city and state, e.g., San Francisco, CA"267 "description": "The city and state, e.g., San Francisco, CA",

266}268 }

267},269 },

268"required": ["location"],270 "required": ["location"],

269// highlight-start271 # highlight-start

270"additionalProperties": False272 "additionalProperties": False,

271// highlight-end273 # highlight-end

272},274 },

273// highlight-start275 # highlight-start

274"strict": True276 "strict": True,

275// highlight-end277 # highlight-end

276}278 },

277}279 },

278]280 ],

279)281)

280```282```

281 283 

1# Advanced usage1# Advanced usage

2 2 

3OpenAI's text generation models (often called generative pre-trained transformers or large language models) have been trained to understand natural language, code, and images. The models provide text outputs in response to their inputs. The text inputs to these models are also referred to as "prompts". Designing a prompt is essentially how you “program” a large language model model, usually by providing instructions or some examples of how to successfully complete a task.3OpenAI's text generation models (often called generative pre-trained transformers or large language models) have been trained to understand natural language, code, and images. The models provide text outputs in response to their inputs. The text inputs to these models are also referred to as "prompts." Designing a prompt is essentially how you “program” a large language model, usually by providing instructions or some examples of how to successfully complete a task.

4 4 

5## Reproducible outputs5## Reproducible outputs

6 6 

7Chat Completions are non-deterministic by default (which means model outputs may differ from request to request). That being said, we offer some control towards deterministic outputs by giving you access to the [seed](https://developers.openai.com/api/docs/api-reference/chat/create#chat-create-seed) parameter and the [system_fingerprint](https://developers.openai.com/api/docs/api-reference/completions/object#completions/object-system_fingerprint) response field.7Chat Completions are non-deterministic by default (which means model outputs may differ from request to request). That being said, we offer some control towards deterministic outputs by giving you access to the [`seed`](https://developers.openai.com/api/docs/api-reference/chat/create#chat-create-seed) parameter and the [`system_fingerprint`](https://developers.openai.com/api/docs/api-reference/completions/object#completions/object-system_fingerprint) response field.

8 8 

9To receive (mostly) deterministic outputs across API calls, you can:9To receive (mostly) deterministic outputs across API calls, you can:

10 10 

11- Set the [seed](https://developers.openai.com/api/docs/api-reference/chat/create#chat-create-seed) parameter to any integer of your choice and use the same value across requests you'd like deterministic outputs for.11- Set the [seed](https://developers.openai.com/api/docs/api-reference/chat/create#chat-create-seed) parameter to any integer of your choice and use the same value across requests you'd like deterministic outputs for.

12- Ensure all other parameters (like `prompt` or `temperature`) are the exact same across requests.12- Ensure all other parameters (like `prompt` or `temperature`) are the exact same across requests.

13 13 

14Sometimes, determinism may be impacted due to necessary changes OpenAI makes to model configurations on our end. To help you keep track of these changes, we expose the [system_fingerprint](https://developers.openai.com/api/docs/api-reference/chat/object#chat/object-system_fingerprint) field. If this value is different, you may see different outputs due to changes we've made on our systems.14Sometimes, determinism may be impacted due to necessary changes OpenAI makes to model configurations on our end. To help you keep track of these changes, we expose the [`system_fingerprint`](https://developers.openai.com/api/docs/api-reference/chat/object#chat/object-system_fingerprint) field. If this value is different, you may see different outputs due to changes we've made on our systems.

15 15 

16<a16<a

17 href="https://cookbook.openai.com/examples/reproducible_outputs_with_the_seed_parameter"17 href="https://cookbook.openai.com/examples/reproducible_outputs_with_the_seed_parameter"

29 29 

30## Managing tokens30## Managing tokens

31 31 

32Language models read and write text in chunks called tokens. In English, a token can be as short as one character or as long as one word (e.g., `a` or ` apple`), and in some languages tokens can be even shorter than one character or even longer than one word.32Language models read and write text in chunks called tokens. In English, a token can be as short as one character or as long as one word (for example, `a` or ` apple`), and in some languages tokens can be even shorter than one character or even longer than one word.

33 33 

34As a rough rule of thumb, 1 token is approximately 4 characters or 0.75 words for English text.34As a rough rule of thumb, 1 token is approximately 4 characters or 0.75 words for English text.

35 35 

53 53 

54Both input and output tokens count toward these quantities. For example, if your API call used 10 tokens in the message input and you received 20 tokens in the message output, you would be billed for 30 tokens. Note however that for some models the price per token is different for tokens in the input vs. the output (see the [pricing](https://openai.com/api/pricing) page for more information).54Both input and output tokens count toward these quantities. For example, if your API call used 10 tokens in the message input and you received 20 tokens in the message output, you would be billed for 30 tokens. Note however that for some models the price per token is different for tokens in the input vs. the output (see the [pricing](https://openai.com/api/pricing) page for more information).

55 55 

56To see how many tokens are used by an API call, check the `usage` field in the API response (e.g., `response['usage']['total_tokens']`).56To see how many tokens are used by an API call, check the `usage` field in the API response (for example, `response['usage']['total_tokens']`).

57 57 

58Chat models like `gpt-3.5-turbo` and `gpt-4-turbo-preview` use tokens in the same way as the models available in the completions API, but because of their message-based formatting, it's more difficult to count how many tokens will be used by a conversation.58Chat models like `gpt-3.5-turbo` and `gpt-4-turbo-preview` use tokens in the same way as the models available in the completions API, but because of their message-based formatting, it's more difficult to count how many tokens will be used by a conversation.

59 59 

73 if model == "gpt-3.5-turbo-0613": # note: future models may deviate from this73 if model == "gpt-3.5-turbo-0613": # note: future models may deviate from this

74 num_tokens = 074 num_tokens = 0

75 for message in messages:75 for message in messages:

76 num_tokens += 4 # every message follows <im_start>{role/name}\n{content}<im_end>\n76 num_tokens += (

77 4 # every message follows <im_start>{role/name}\n{content}<im_end>\n

78 )

77 for key, value in message.items():79 for key, value in message.items():

78 num_tokens += len(encoding.encode(value))80 num_tokens += len(encoding.encode(value))

79 if key == "name": # if there's a name, the role is omitted81 if key == "name": # if there's a name, the role is omitted

80 num_tokens += -1 # role is always required and always 1 token82 num_tokens += -1 # role is always required and always 1 token

81 num_tokens += 2 # every reply is primed with <im_start>assistant83 num_tokens += 2 # every reply is primed with <im_start>assistant

82 return num_tokens84 return num_tokens

83 else:85 raise ValueError(

84 raise NotImplementedError(f"""num_tokens_from_messages() is not presently implemented for model {model}.""")86 f"num_tokens_from_messages() only supports gpt-3.5-turbo-0613, not {model}."

87 )

85```88```

86 89 

87 90 

89 92 

90```python93```python

91messages = [94messages = [

92 {"role": "system", "content": "You are a helpful, pattern-following assistant that translates corporate jargon into plain English."},95 {

93 {"role": "system", "name":"example_user", "content": "New synergies will help drive top-line growth."},96 "role": "system",

94 {"role": "system", "name": "example_assistant", "content": "Things working well together will increase revenue."},97 "content": "You are a helpful, pattern-following assistant that translates corporate jargon into plain English.",

95 {"role": "system", "name":"example_user", "content": "Let's circle back when we have more bandwidth to touch base on opportunities for increased leverage."},98 },

96 {"role": "system", "name": "example_assistant", "content": "Let's talk later when we're less busy about how to do better."},99 {

97 {"role": "user", "content": "This late pivot means we don't have time to boil the ocean for the client deliverable."},100 "role": "system",

101 "name": "example_user",

102 "content": "New synergies will help drive top-line growth.",

103 },

104 {

105 "role": "system",

106 "name": "example_assistant",

107 "content": "Things working well together will increase revenue.",

108 },

109 {

110 "role": "system",

111 "name": "example_user",

112 "content": "Let's circle back when we have more bandwidth to touch base on opportunities for increased leverage.",

113 },

114 {

115 "role": "system",

116 "name": "example_assistant",

117 "content": "Let's talk later when we're less busy about how to do better.",

118 },

119 {

120 "role": "user",

121 "content": "This late pivot means we don't have time to boil the ocean for the client deliverable.",

122 },

98]123]

99 124 

100model = "gpt-3.5-turbo-0613"125model = "gpt-3.5-turbo-0613"

117 temperature=0,143 temperature=0,

118)144)

119 145 

120print(f'{response.usage.prompt_tokens} prompt tokens used.')146print(f"{response.usage.prompt_tokens} prompt tokens used.")

121```147```

122 148 

123 149 

126 152 

127Each message passed to the API consumes the number of tokens in the content, role, and other fields, plus a few extra for behind-the-scenes formatting. This may change slightly in the future.153Each message passed to the API consumes the number of tokens in the content, role, and other fields, plus a few extra for behind-the-scenes formatting. This may change slightly in the future.

128 154 

129If a conversation has too many tokens to fit within a model’s maximum limit (e.g., more than 4097 tokens for `gpt-3.5-turbo` or more than 128k tokens for `gpt-4o`), you will have to truncate, omit, or otherwise shrink your text until it fits. Beware that if a message is removed from the messages input, the model will lose all knowledge of it.155If a conversation has too many tokens to fit within a model’s maximum limit (for example, more than 4097 tokens for `gpt-3.5-turbo` or more than 128k tokens for `gpt-4o`), you will have to truncate, omit, or otherwise shrink your text until it fits. Beware that if a message is removed from the messages input, the model will lose all knowledge of it.

130 156 

131Note that very long conversations are more likely to receive incomplete replies. For example, a `gpt-3.5-turbo` conversation that is 4090 tokens long will have its reply cut off after just 6 tokens.157Note that long conversations are more likely to receive incomplete replies. For example, a `gpt-3.5-turbo` conversation that is 4090 tokens long will have its reply cut off after just 6 tokens.

132 158 

133## Parameter details159## Parameter details

134 160 

141They work by directly modifying the logits (un-normalized log-probabilities) with an additive contribution.167They work by directly modifying the logits (un-normalized log-probabilities) with an additive contribution.

142 168 

143```python169```python

144mu[j] -> mu[j] - c[j] * alpha_frequency - float(c[j] > 0) * alpha_presence170mu[j] = mu[j] - c[j] * alpha_frequency - float(c[j] > 0) * alpha_presence

145```171```

146 172 

173 

147Where:174Where:

148 175 

149- `mu[j]` is the logits of the j-th token176- `mu[j]` is the logits of the j-th token

160 187 

161### Token log probabilities188### Token log probabilities

162 189 

163The [logprobs](https://developers.openai.com/api/docs/api-reference/chat/create#chat-create-logprobs) parameter found in the [Chat Completions API](https://developers.openai.com/api/docs/api-reference/chat/create) and [Legacy Completions API](https://developers.openai.com/api/docs/api-reference/completions), when requested, provides the log probabilities of each output token, and a limited number of the most likely tokens at each token position alongside their log probabilities. This can be useful in some cases to assess the confidence of the model in its output, or to examine alternative responses the model might have given.190The [`logprobs`](https://developers.openai.com/api/docs/api-reference/chat/create#chat-create-logprobs) parameter found in the [Chat Completions API](https://developers.openai.com/api/docs/api-reference/chat/create) and [Legacy Completions API](https://developers.openai.com/api/docs/api-reference/completions), when requested, provides the log probabilities of each output token, and a limited number of the most likely tokens at each token position alongside their log probabilities. This can be useful in some cases to assess the confidence of the model in its output, or to examine alternative responses the model might have given.

164 191 

165### Other parameters192### Other parameters

166 193 

193 )193 )

194 194 

195 async for event in stream.stream_events():195 async for event in stream.stream_events():

196 if (196 if event.type == "raw_response_event" and isinstance(

197 event.type == "raw_response_event"197 event.data, ResponseTextDeltaEvent

198 and isinstance(event.data, ResponseTextDeltaEvent)

199 ):198 ):

200 print(event.data.delta, end="", flush=True)199 print(event.data.delta, end="", flush=True)

201 200 

226agent = SandboxAgent(226agent = SandboxAgent(

227 name="Tax prep assistant",227 name="Tax prep assistant",

228 instructions="Use the mounted skill before preparing the return.",228 instructions="Use the mounted skill before preparing the return.",

229 capabilities=Capabilities.default() + [229 capabilities=Capabilities.default()

230 + [

230 Skills(from_=GitRepo(repo="owner/tax-prep-skills", ref="main")),231 Skills(from_=GitRepo(repo="owner/tax-prep-skills", ref="main")),

231 ],232 ],

232)233)

409from agents.run import RunConfig410from agents.run import RunConfig

410from agents.sandbox import SandboxRunConfig411from agents.sandbox import SandboxRunConfig

411from agents.sandbox.config import DEFAULT_PYTHON_SANDBOX_IMAGE412from agents.sandbox.config import DEFAULT_PYTHON_SANDBOX_IMAGE

412from agents.sandbox.sandboxes.docker import DockerSandboxClient, DockerSandboxClientOptions413from agents.sandbox.sandboxes.docker import (

414 DockerSandboxClient,

415 DockerSandboxClientOptions,

416)

413 417 

414docker_run_config = RunConfig(418docker_run_config = RunConfig(

415 sandbox=SandboxRunConfig(419 sandbox=SandboxRunConfig(

122 model="gpt-audio-1.5",122 model="gpt-audio-1.5",

123 modalities=["text", "audio"],123 modalities=["text", "audio"],

124 audio={"voice": "alloy", "format": "wav"},124 audio={"voice": "alloy", "format": "wav"},

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

126 {

127 "role": "user",

128 "content": "Is a golden retriever a good family dog?"

129 }

130 ]

131)126)

132 127 

133print(completion.choices[0])128print(completion.choices[0])

203response = requests.get(url)198response = requests.get(url)

204response.raise_for_status()199response.raise_for_status()

205wav_data = response.content200wav_data = response.content

206encoded_string = base64.b64encode(wav_data).decode('utf-8')201encoded_string = base64.b64encode(wav_data).decode("utf-8")

207 202 

208completion = client.chat.completions.create(203completion = client.chat.completions.create(

209 model="gpt-audio-1.5",204 model="gpt-audio-1.5",

213 {208 {

214 "role": "user",209 "role": "user",

215 "content": [210 "content": [

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

217 "type": "text",

218 "text": "What is in this recording?"

219 },

220 {212 {

221 "type": "input_audio",213 "type": "input_audio",

222 "input_audio": {214 "input_audio": {"data": encoded_string, "format": "wav"},

223 "data": encoded_string,

224 "format": "wav"

225 }

226 }

227 ]

228 },215 },

229 ]216 ],

217 },

218 ],

230)219)

231 220 

232print(completion.choices[0].message)221print(completion.choices[0].message)

123```123```

124 124 

125```python125```python

126import os

127 

126from openai import OpenAI128from openai import OpenAI

129 

130response_id = os.environ["OPENAI_RESPONSE_ID"]

127client = OpenAI()131client = OpenAI()

128 132 

129resp = client.responses.cancel("resp_123")133resp = client.responses.cancel(response_id)

130 134 

131print(resp.status)135print(resp.status)

132```136```

29- `/v1/chat/completions` ([Chat Completions API](https://developers.openai.com/api/docs/api-reference/chat))29- `/v1/chat/completions` ([Chat Completions API](https://developers.openai.com/api/docs/api-reference/chat))

30- `/v1/embeddings` ([Embeddings API](https://developers.openai.com/api/docs/api-reference/embeddings))30- `/v1/embeddings` ([Embeddings API](https://developers.openai.com/api/docs/api-reference/embeddings))

31- `/v1/completions` ([Completions API](https://developers.openai.com/api/docs/api-reference/completions))31- `/v1/completions` ([Completions API](https://developers.openai.com/api/docs/api-reference/completions))

32- `/v1/moderations` ([Moderations guide](https://developers.openai.com/api/docs/guides/moderation))32- `/v1/moderations` ([Moderation guide](https://developers.openai.com/api/docs/guides/moderation))

33- `/v1/images/generations` ([Images API](https://developers.openai.com/api/docs/api-reference/images))33- `/v1/images/generations` ([Images API](https://developers.openai.com/api/docs/api-reference/images))

34- `/v1/images/edits` ([Images API](https://developers.openai.com/api/docs/api-reference/images))34- `/v1/images/edits` ([Images API](https://developers.openai.com/api/docs/api-reference/images))

35- `/v1/videos` ([Video generation guide](https://developers.openai.com/api/docs/guides/video-generation))35- `/v1/videos` ([Video generation guide](https://developers.openai.com/api/docs/guides/video-generation))

52{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-3.5-turbo-0125", "messages": [{"role": "system", "content": "You are an unhelpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}52{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-3.5-turbo-0125", "messages": [{"role": "system", "content": "You are an unhelpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}

53```53```

54 54 

55#### Moderations input examples55#### Moderation input examples

56 56 

57Text-only request:57Text-only request:

58 58 

68}68}

69```69```

70 70 

71Multimodal request:71Request with text and image input:

72 72 

73```jsonl73```jsonl

74{74{

121client = OpenAI()122client = OpenAI()

122 123 

123batch_input_file = client.files.create(124batch_input_file = client.files.create(

124 file=open("batchinput.jsonl", "rb"),125 file=open("batchinput.jsonl", "rb"), purpose="batch"

125 purpose="batch"

126)126)

127 127 

128print(batch_input_file)128print(batch_input_file)

162```162```

163 163 

164```python164```python

165from openai import OpenAI165batch = client.batches.create(

166client = OpenAI()166 input_file_id=batch_input_file.id,

167 

168batch_input_file_id = batch_input_file.id

169client.batches.create(

170 input_file_id=batch_input_file_id,

171 endpoint="/v1/chat/completions",167 endpoint="/v1/chat/completions",

172 completion_window="24h",168 completion_window="24h",

173 metadata={169 metadata={"description": "nightly eval job"},

174 "description": "nightly eval job"

175 }

176)170)

171print(batch)

177```172```

178 173 

179```bash174```bash

197 192 

198This request will return a [Batch object](https://developers.openai.com/api/docs/api-reference/batch/object) with metadata about your batch:193This request will return a [Batch object](https://developers.openai.com/api/docs/api-reference/batch/object) with metadata about your batch:

199 194 

200```python195```json

201{196{

202 "id": "batch_abc123",197 "id": "batch_abc123",

203 "object": "batch",198 "object": "batch",

238```233```

239 234 

240```python235```python

241from openai import OpenAI236batch = client.batches.retrieve(batch.id)

242client = OpenAI()

243 

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

245print(batch)237print(batch)

246```238```

247 239 

287```279```

288 280 

289```python281```python

282import os

283 

290from openai import OpenAI284from openai import OpenAI

285 

286output_file_id = os.environ["OPENAI_BATCH_OUTPUT_FILE_ID"]

291client = OpenAI()287client = OpenAI()

292 288 

293file_response = client.files.content("file-xyz123")289file_response = client.files.content(output_file_id)

294print(file_response.text)290print(file_response.text)

295```291```

296 292 

337```333```

338 334 

339```python335```python

336import os

337 

340from openai import OpenAI338from openai import OpenAI

339 

340batch_id = os.environ["OPENAI_BATCH_ID"]

341client = OpenAI()341client = OpenAI()

342 342 

343client.batches.cancel("batch_abc123")343client.batches.cancel(batch_id)

344```344```

345 345 

346```bash346```bash

401Batch API rate limits are separate from existing per-model rate limits. The Batch API has three types of rate limits:402Batch API rate limits are separate from existing per-model rate limits. The Batch API has three types of rate limits:

402 403 

4031. **Per-batch limits:** A single batch may include up to 50,000 requests, and a batch input file can be up to 200 MB in size. Note that `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.4041. **Per-batch limits:** A single batch may include up to 50,000 requests, and a batch input file can be up to 200 MB in size. Note that `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.

4042. **Enqueued prompt tokens per model:** Each model has a maximum number of enqueued prompt tokens allowed for batch processing. You can find these limits on the [Platform Settings page](https://platform.openai.com/settings/organization/limits).4052. **Queued prompt tokens per model:** Each model has a maximum number of prompt tokens that can be queued for batch processing. You can find these limits on the [Platform Settings page](https://platform.openai.com/settings/organization/limits).

4053. **Batch creation rate limit:** You can create up to 2,000 batches per hour. If you need to submit more requests, increase the number of requests per batch.4063. **Batch creation rate limit:** You can create up to 2,000 batches per hour. If you need to submit more requests, increase the number of requests per batch.

406 407 

407There are no limits for output tokens for the Batch API today. Because Batch API rate limits are a new, separate pool, **using the Batch API will not consume tokens from your standard per-model rate limits**, thereby offering you a convenient way to increase the number of requests and processed tokens you can use when querying our API.408The Batch API currently has no output-token limit. Because Batch API rate limits are a new, separate pool, **using the Batch API will not consume tokens from your standard per-model rate limits**, thereby offering you a convenient way to increase the number of requests and processed tokens you can use when querying our API.

408 409 

409## Batch expiration410## Batch expiration

410 411 

39 39 

40### 2. Set up ChatKit in your product40### 2. Set up ChatKit in your product

41 41 

42To set up ChatKit, you'll create a ChatKit session and create a backend endpoint, pass in your workflow ID, exchange the client secret, add a script to embed ChatKit on your site.42To set up ChatKit, you'll create a ChatKit session and a server endpoint, pass in your workflow ID, exchange the client secret, and add a script to embed ChatKit on your site.

43 43 

44**Important Security Note:** When creating a ChatKit session, you must pass in a `user` parameter, which should be unique for each individual end user. It is your backend's responsibility44**Important Security Note:** When creating a ChatKit session, you must pass in a `user` parameter, which should be unique for each individual end user. Your server must

45to authenticate your application's users and pass a unique identifier for them in this parameter.45authenticate your application's users and pass a unique identifier for them in this parameter.

46 46 

471. On your server, generate a client token.471. On your server, generate a client token.

48 48 

49 This snippet spins up a FastAPI service whose sole job is to create a new ChatKit session via the [OpenAI Python SDK](https://github.com/openai/chatkit-python) and hand back the session's client secret:49 This snippet spins up a FastAPI service whose sole job is to create a new ChatKit session through the OpenAI API and hand back the session's client secret:

50 50 

51 server.py51 server.py

52 52 

53```python53```python

54from fastapi import FastAPI54import hmac

55from pydantic import BaseModel55import json

56from openai import OpenAI

57import os56import os

57from typing import Annotated

58 

59import requests

60from fastapi import Depends, FastAPI, HTTPException

61from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer

62from pydantic import BaseModel

63 

64 

65api_key = os.environ["OPENAI_API_KEY"]

66workflow_id = os.environ["OPENAI_CHATKIT_WORKFLOW_ID"]

67authenticated_users: dict[str, str] = json.loads(

68 os.environ["CHATKIT_AUTHENTICATED_USERS"]

69)

70bearer_auth = HTTPBearer(auto_error=False)

71 

72 

73def get_authenticated_user_id(

74 credentials: Annotated[

75 HTTPAuthorizationCredentials | None,

76 Depends(bearer_auth),

77 ],

78) -> str:

79 if credentials is not None:

80 for token, user_id in authenticated_users.items():

81 if hmac.compare_digest(credentials.credentials, token):

82 return user_id

83 raise HTTPException(status_code=401, detail="Invalid authentication token")

84 

85 

86class ChatKitSession(BaseModel):

87 client_secret: str

88 

58 89 

59app = FastAPI()90app = FastAPI()

60openai = OpenAI(api_key=os.environ["OPENAI_API_KEY"])91 

61 92 

62@app.post("/api/chatkit/session")93@app.post("/api/chatkit/session")

63def create_chatkit_session():94def create_chatkit_session(

64 session = openai.chatkit.sessions.create({95 user_id: Annotated[str, Depends(get_authenticated_user_id)],

65 # ...96):

66 })97 response = requests.post(

67 return { client_secret: session.client_secret }98 "https://api.openai.com/v1/chatkit/sessions",

99 headers={

100 "Authorization": f"Bearer {api_key}",

101 "Content-Type": "application/json",

102 "OpenAI-Beta": "chatkit_beta=v1",

103 },

104 json={

105 "workflow": {"id": workflow_id},

106 "user": user_id,

107 },

108 timeout=30,

109 )

110 response.raise_for_status()

111 session = ChatKitSession.model_validate(response.json())

112 return {"client_secret": session.client_secret}

68```113```

69 114 

70 115 

116 Before starting the service, set `OPENAI_API_KEY`, `OPENAI_CHATKIT_WORKFLOW_ID`, and `CHATKIT_AUTHENTICATED_USERS`. The last value is a JSON map from your application's bearer tokens to stable user IDs. In production, replace this environment-backed map with your application's authentication or session lookup.

117 

712. In your server-side code, pass in your workflow ID and secret key to the session endpoint.1182. In your server-side code, pass in your workflow ID and secret key to the session endpoint.

72 119 

73 The client secret is the credential that your ChatKit frontend uses to open or refresh the chat session. You don't store it; you immediately hand it off to the ChatKit client library.120 The client secret is the credential that your ChatKit frontend uses to open or refresh the chat session. You don't store it; you immediately hand it off to the ChatKit client library.

134```181```

135 182 

136 183 

1375. Render ChatKit in your UI. This code fetches the client secret from your server and mounts a live chat widget connected to your workflow.1845. Render ChatKit in your UI. Pass the React `MyChat` component a `getAppAuthToken` function that returns the current user's bearer token. If you use the JavaScript tab, make the same function available in the snippet's scope. This code sends that credential to your server, fetches the client secret, and mounts a live chat widget connected to your workflow.

138 185 

139 Your frontend code186 Your frontend code

140 187 

141```react188```react

142import { ChatKit, useChatKit } from '@openai/chatkit-react';189import { ChatKit, useChatKit } from '@openai/chatkit-react';

143 190 

144 export function MyChat() {191 export function MyChat({ getAppAuthToken }) {

145 const { control } = useChatKit({192 const { control } = useChatKit({

146 api: {193 api: {

147 async getClientSecret(existing) {194 async getClientSecret(existing) {

149 // implement session refresh196 // implement session refresh

150 }197 }

151 198 

199 const appAuthToken = await getAppAuthToken();

152 const res = await fetch('/api/chatkit/session', {200 const res = await fetch('/api/chatkit/session', {

153 method: 'POST',201 method: 'POST',

154 headers: {202 headers: {

203 'Authorization': 'Bearer ' + appAuthToken,

155 'Content-Type': 'application/json',204 'Content-Type': 'application/json',

156 },205 },

157 });206 });

177 226 

178chatkit.setOptions({227chatkit.setOptions({

179 api: {228 api: {

180 async getClientSecret(currentClientSecret) {229 async getClientSecret() {

181 if (!currentClientSecret) {230 const appAuthToken = await getAppAuthToken();

182 const res = await fetch("/api/chatkit/start", { method: "POST" });231 const res = await fetch("/api/chatkit/session", {

183 const { client_secret } = await res.json();

184 return client_secret;

185 }

186 const res = await fetch("/api/chatkit/refresh", {

187 method: "POST",232 method: "POST",

188 body: JSON.stringify({ currentClientSecret }),

189 headers: {233 headers: {

234 Authorization: `Bearer ${appAuthToken}`,

190 "Content-Type": "application/json",235 "Content-Type": "application/json",

191 },236 },

192 });237 });

238 if (!res.ok) {

239 throw new Error(`ChatKit session request failed: ${res.status}`);

240 }

193 const { client_secret } = await res.json();241 const { client_secret } = await res.json();

194 return client_secret;242 return client_secret;

195 },243 },

9Actions can be triggered by attaching an `ActionConfig` to any widget node that supports it. For example, you can respond to click events on Buttons. When a user clicks on this button, the action will be sent to your server where you can update the widget, run inference, stream new thread items, etc.9Actions can be triggered by attaching an `ActionConfig` to any widget node that supports it. For example, you can respond to click events on Buttons. When a user clicks on this button, the action will be sent to your server where you can update the widget, run inference, stream new thread items, etc.

10 10 

11```python11```python

12Button(12button = Button(

13 label="Example",13 label="Example",

14 onClickAction=ActionConfig(14 onClickAction=ActionConfig(

15 type="example",15 type="example",

16 payload={"id": 123},16 payload={"id": 123},

17 )17 ),

18)18)

19```19```

20 20 

34By default, actions are sent to your server. You can handle actions on your server by implementing the `action` method on `ChatKitServer`.35By default, actions are sent to your server. You can handle actions on your server by implementing the `action` method on `ChatKitServer`.

35 36 

36```python37```python

37class MyChatKitServer(ChatKitServer[RequestContext])38class MyChatKitServer(ChatKitServer[RequestContext]):

38 async def action(39 async def action(

39 self,40 self,

40 thread: ThreadMetadata,41 thread: ThreadMetadata,

43 context: RequestContext,44 context: RequestContext,

44 ) -> AsyncIterator[Event]:45 ) -> AsyncIterator[Event]:

45 if action.type == "example":46 if action.type == "example":

46 await do_thing(action.payload['id'])47 await do_thing(action.payload["id"])

47 48 

48 # often you'll want to add a HiddenContextItem so the model49 # Often you'll want to add a HiddenContextItem so the model

49 # can see that the user did something50 # can see that the user did something.

50 await self.store.add_thread_item(51 await self.store.add_thread_item(

51 thread.id,52 thread.id,

52 HiddenContextItem(53 HiddenContextItem(

53 id="item_123",54 id="item_123",

54 created_at=datetime.now(),55 created_at=datetime.now(),

55 content=(56 content="<USER_ACTION>The user did a thing</USER_ACTION>",

56 "<USER_ACTION>The user did a thing</USER_ACTION>"

57 ),

58 ),57 ),

59 context,58 context,

60 )59 )