0
# Responses API
1

2
The Responses API is OpenAI's primary interface for generating model responses. It provides a unified, powerful way to create text, image, and audio responses with support for function calling, tool use, computer use, file search, web search, and streaming. The Responses API replaces the older Chat Completions API as the recommended way to interact with OpenAI models.
3

4
## Package Information
5

6
- **Package Name**: openai
7
- **Resource Path**: `client.responses`
8
- **Version**: 6.9.1+
9
- **Language**: TypeScript
10
- **Primary Import**: `import { OpenAI } from 'openai'`
11

12
## Core Imports
13

14
```typescript
15
import { OpenAI } from "openai";
16

17
// Initialize client
18
const client = new OpenAI({
19
  apiKey: process.env.OPENAI_API_KEY,
20
});
21

22
// Access responses API
23
client.responses.create({ /* ... */ });
24
client.responses.retrieve("resp_id");
25
client.responses.delete("resp_id");
26
client.responses.cancel("resp_id");
27

28
// Sub-resources
29
client.responses.inputItems.list("resp_id");
30
client.responses.inputTokens.count({ /* ... */ });
31
```
32

33
## Basic Usage
34

35
```typescript
36
import { OpenAI } from "openai";
37

38
const client = new OpenAI();
39

40
// Simple text response
41
const response = await client.responses.create({
42
  model: "gpt-4o",
43
  input: "What is the capital of France?",
44
});
45

46
console.log(response.output_text);
47
// "The capital of France is Paris."
48

49
// Streaming response
50
const stream = await client.responses.create({
51
  model: "gpt-4o",
52
  input: "Write a poem about TypeScript",
53
  stream: true,
54
});
55

56
for await (const event of stream) {
57
  if (event.type === "response.text.delta") {
58
    process.stdout.write(event.delta);
59
  }
60
}
61

62
// Multi-turn conversation
63
const firstResponse = await client.responses.create({
64
  model: "gpt-4o",
65
  input: "My name is Alice",
66
});
67

68
const secondResponse = await client.responses.create({
69
  model: "gpt-4o",
70
  input: "What's my name?",
71
  previous_response_id: firstResponse.id,
72
});
73
// "Your name is Alice."
74
```
75

76
## Architecture
77

78
The Responses API is built around several key components:
79

80
- **Response Object**: The core response object containing model outputs, metadata, and usage information
81
- **Input System**: Flexible input handling supporting text, images, files, audio, and structured messages
82
- **Output System**: Multi-modal outputs including text, audio, tool calls, and reasoning
83
- **Streaming Engine**: Real-time server-sent events (SSE) for progressive response delivery
84
- **Tool System**: Built-in and custom tools for extending model capabilities
85
- **Conversation Management**: Automatic conversation state tracking and multi-turn dialogue
86
- **Parsing Helpers**: Automatic parsing of structured outputs with type safety
87

88
## Capabilities
89

90
### Response Creation
91

92
Creates a model response with support for text, images, tools, streaming, and more.
93

94
```typescript { .api }
95
/**
96
 * Creates a model response. Provide text or image inputs to generate text or JSON outputs.
97
 * Have the model call your own custom code or use built-in tools like web search or file search.
98
 *
99
 * @param body - Response creation parameters
100
 * @param options - Optional request options (headers, timeout, etc.)
101
 * @returns Promise<Response> or Promise<Stream<ResponseStreamEvent>> based on stream parameter
102
 */
103
function create(
104
  body: ResponseCreateParams,
105
  options?: RequestOptions
106
): APIPromise<Response> | APIPromise<Stream<ResponseStreamEvent>>;
107

108
interface ResponseCreateParams {
109
  /** Model ID like 'gpt-4o' or 'o3' */
110
  model?: string;
111

112
  /** Text, image, or file inputs to the model */
113
  input?: string | Array<ResponseInputItem> | null;
114

115
  /** System/developer message inserted into model context */
116
  instructions?: string | null;
117

118
  /** Whether to stream the response */
119
  stream?: boolean;
120

121
  /** Sampling temperature (0-2) */
122
  temperature?: number | null;
123

124
  /** Nucleus sampling parameter */
125
  top_p?: number | null;
126

127
  /** Maximum output tokens */
128
  max_output_tokens?: number | null;
129

130
  /** Tools the model may call */
131
  tools?: Array<Tool>;
132

133
  /** How to select which tool to use */
134
  tool_choice?: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | ToolChoiceFunction | ToolChoiceMcp | ToolChoiceCustom | ToolChoiceApplyPatch | ToolChoiceShell;
135

136
  /** Whether to allow parallel tool calls */
137
  parallel_tool_calls?: boolean | null;
138

139
  /** Previous response ID for multi-turn conversations */
140
  previous_response_id?: string | null;
141

142
  /** Conversation ID for automatic state management */
143
  conversation?: string | ResponseConversationParam | null;
144

145
  /** Text response configuration */
146
  text?: ResponseTextConfig | null;
147

148
  /** Reasoning configuration for reasoning models */
149
  reasoning?: Reasoning | null;
150

151
  /** Metadata key-value pairs */
152
  metadata?: Metadata | null;
153

154
  /** Truncation strategy ('auto' or 'disabled') */
155
  truncation?: "auto" | "disabled" | null;
156

157
  /** Run response in background */
158
  background?: boolean | null;
159

160
  /** Prompt cache key for optimization */
161
  prompt_cache_key?: string;
162

163
  /** Prompt cache retention policy */
164
  prompt_cache_retention?: "in-memory" | "24h" | null;
165

166
  /** Service tier (auto, default, flex, scale, priority) */
167
  service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null;
168

169
  /** Safety identifier for user tracking */
170
  safety_identifier?: string;
171

172
  /** Prompt template reference */
173
  prompt?: ResponsePrompt | null;
174

175
  /** Whether to store the generated model response for later retrieval via API */
176
  store?: boolean | null;
177

178
  /** Options for streaming responses. Only set this when you set stream: true */
179
  stream_options?: StreamOptions | null;
180

181
  /** Specify additional output data to include in the model response */
182
  include?: Array<ResponseIncludable> | null;
183
}
184

185
/**
186
 * Options for streaming responses. Only used when stream: true
187
 */
188
interface StreamOptions {
189
  /** When true, stream obfuscation will be enabled to normalize payload sizes as mitigation against side-channel attacks */
190
  include_obfuscation?: boolean;
191
}
192
```
193

194
**Usage Examples:**
195

196
```typescript
197
// Basic text response
198
const response = await client.responses.create({
199
  model: "gpt-4o",
200
  input: "Explain quantum computing in simple terms",
201
});
202

203
// Structured JSON output
204
const response = await client.responses.create({
205
  model: "gpt-4o",
206
  input: "Extract the person's name and email from: John Doe (john@example.com)",
207
  text: {
208
    format: {
209
      type: "json_schema",
210
      json_schema: {
211
        name: "PersonInfo",
212
        strict: true,
213
        schema: {
214
          type: "object",
215
          properties: {
216
            name: { type: "string" },
217
            email: { type: "string" },
218
          },
219
          required: ["name", "email"],
220
          additionalProperties: false,
221
        },
222
      },
223
    },
224
  },
225
});
226

227
// With system instructions
228
const response = await client.responses.create({
229
  model: "gpt-4o",
230
  instructions: "You are a helpful assistant that speaks like a pirate.",
231
  input: "Tell me about the weather",
232
});
233

234
// Image input
235
const response = await client.responses.create({
236
  model: "gpt-4o",
237
  input: [
238
    { type: "text", text: "What's in this image?" },
239
    {
240
      type: "image",
241
      image_url: { url: "https://example.com/image.jpg" }
242
    },
243
  ],
244
});
245

246
// Multi-turn conversation
247
const conv1 = await client.responses.create({
248
  model: "gpt-4o",
249
  input: "I'm planning a trip to Paris",
250
});
251

252
const conv2 = await client.responses.create({
253
  model: "gpt-4o",
254
  input: "What landmarks should I visit?",
255
  previous_response_id: conv1.id,
256
});
257

258
// With reasoning (o-series models)
259
const response = await client.responses.create({
260
  model: "o3-mini",
261
  input: "Solve this complex math problem: ...",
262
  reasoning: {
263
    effort: "high",
264
  },
265
});
266
```
267

268
### Response Retrieval
269

270
Retrieves a previously created model response.
271

272
```typescript { .api }
273
/**
274
 * Retrieves a model response with the given ID.
275
 * Can optionally stream the response if it's still in progress.
276
 *
277
 * @param responseID - The unique response ID (e.g., 'resp_abc123')
278
 * @param query - Optional query parameters
279
 * @param options - Optional request options
280
 * @returns Promise<Response> or Promise<Stream<ResponseStreamEvent>>
281
 */
282
function retrieve(
283
  responseID: string,
284
  query?: ResponseRetrieveParams,
285
  options?: RequestOptions
286
): APIPromise<Response> | APIPromise<Stream<ResponseStreamEvent>>;
287

288
interface ResponseRetrieveParams {
289
  /** Additional fields to include in response */
290
  include?: Array<ResponseIncludable>;
291

292
  /** Whether to stream the response */
293
  stream?: boolean;
294

295
  /**
296
   * When true, stream obfuscation will be enabled. Stream obfuscation adds random
297
   * characters to an obfuscation field on streaming delta events to normalize
298
   * payload sizes as a mitigation to certain side-channel attacks. Set to false
299
   * to optimize for bandwidth if you trust the network links.
300
   */
301
  include_obfuscation?: boolean;
302

303
  /**
304
   * The sequence number of the event after which to start streaming. Useful for
305
   * resuming a stream from a specific point.
306
   */
307
  starting_after?: number;
308
}
309

310
type ResponseIncludable =
311
  | "input_text"
312
  | "output_text"
313
  | "output[*].content[*].annotations[*].file_citation.quote"
314
  | "output[*].content[*].annotations[*].file_citation.file.content"
315
  | "web_search_call.action.sources"
316
  | "code_interpreter_call.outputs"
317
  | "computer_call_output.output.image_url"
318
  | "file_search_call.results"
319
  | "message.input_image.image_url"
320
  | "reasoning.encrypted_content";
321
```
322

323
**Usage Examples:**
324

325
```typescript
326
// Retrieve a response
327
const response = await client.responses.retrieve("resp_677efb5139a88190b512bc3fef8e535d");
328

329
console.log(response.status); // 'completed'
330
console.log(response.output_text); // Generated text
331

332
// Retrieve with additional fields
333
const response = await client.responses.retrieve(
334
  "resp_677efb5139a88190b512bc3fef8e535d",
335
  {
336
    include: ["input_text", "output_text"],
337
  }
338
);
339

340
// Stream an in-progress response
341
const stream = await client.responses.retrieve(
342
  "resp_677efb5139a88190b512bc3fef8e535d",
343
  { stream: true }
344
);
345

346
for await (const event of stream) {
347
  if (event.type === "response.text.delta") {
348
    process.stdout.write(event.delta);
349
  }
350
}
351
```
352

353
### Response Deletion
354

355
Deletes a model response permanently.
356

357
```typescript { .api }
358
/**
359
 * Deletes a model response with the given ID.
360
 * This operation is permanent and cannot be undone.
361
 *
362
 * @param responseID - The unique response ID
363
 * @param options - Optional request options
364
 * @returns Promise<void>
365
 */
366
function delete(
367
  responseID: string,
368
  options?: RequestOptions
369
): APIPromise<void>;
370
```
371

372
**Usage Examples:**
373

374
```typescript
375
// Delete a response
376
await client.responses.delete("resp_677efb5139a88190b512bc3fef8e535d");
377

378
// Delete with custom timeout
379
await client.responses.delete(
380
  "resp_677efb5139a88190b512bc3fef8e535d",
381
  { timeout: 30000 }
382
);
383
```
384

385
### Response Cancellation
386

387
Cancels an in-progress background response.
388

389
```typescript { .api }
390
/**
391
 * Cancels a model response with the given ID.
392
 * Only responses created with background: true can be cancelled.
393
 *
394
 * @param responseID - The unique response ID
395
 * @param options - Optional request options
396
 * @returns Promise<Response> - The cancelled response object
397
 */
398
function cancel(
399
  responseID: string,
400
  options?: RequestOptions
401
): APIPromise<Response>;
402
```
403

404
**Usage Examples:**
405

406
```typescript
407
// Start a background response
408
const response = await client.responses.create({
409
  model: "gpt-4o",
410
  input: "Write a very long essay",
411
  background: true,
412
});
413

414
// Cancel it
415
const cancelled = await client.responses.cancel(response.id);
416
console.log(cancelled.status); // 'cancelled'
417
```
418

419
### Streaming Responses
420

421
Creates a streaming response with helper methods for handling events.
422

423
```typescript { .api }
424
/**
425
 * Creates a model response stream with automatic parsing and helper methods.
426
 * Provides a higher-level interface than the raw streaming API.
427
 *
428
 * @param body - Response creation parameters with stream: true
429
 * @param options - Optional request options
430
 * @returns ResponseStream instance with helper methods
431
 */
432
function stream<ParsedT = any>(
433
  body: ResponseStreamParams,
434
  options?: RequestOptions
435
): ResponseStream<ParsedT>;
436

437
class ResponseStream<ParsedT> extends Stream<ResponseStreamEvent> {
438
  /**
439
   * Waits for the final response and returns it with parsed output
440
   * @returns Promise<ParsedResponse<ParsedT>> containing the full response and output_parsed field
441
   */
442
  finalResponse(): Promise<ParsedResponse<ParsedT>>;
443

444
  /** Event handlers */
445
  on(event: "text.delta", handler: (delta: string) => void): this;
446
  on(event: "text.done", handler: (text: string) => void): this;
447
  on(event: "tool_call.delta", handler: (call: any) => void): this;
448
  on(event: "tool_call.done", handler: (call: any) => void): this;
449
  on(event: "response.completed", handler: (response: Response) => void): this;
450
  on(event: "error", handler: (error: Error) => void): this;
451
}
452
```
453

454
**Usage Examples:**
455

456
```typescript
457
// Basic streaming
458
const stream = client.responses.stream({
459
  model: "gpt-4o",
460
  input: "Write a haiku about programming",
461
});
462

463
for await (const event of stream) {
464
  if (event.type === "response.text.delta") {
465
    process.stdout.write(event.delta);
466
  }
467
}
468

469
// Using event handlers
470
const stream = client.responses.stream({
471
  model: "gpt-4o",
472
  input: "Explain async/await",
473
})
474
  .on("text.delta", (delta) => {
475
    process.stdout.write(delta);
476
  })
477
  .on("text.done", (text) => {
478
    console.log("\n\nFinal text:", text);
479
  })
480
  .on("error", (error) => {
481
    console.error("Error:", error);
482
  });
483

484
await stream.finalResponse();
485

486
// Streaming with structured output
487
const stream = client.responses.stream({
488
  model: "gpt-4o",
489
  input: "Generate a user profile",
490
  text: {
491
    format: {
492
      type: "json_schema",
493
      json_schema: {
494
        name: "UserProfile",
495
        schema: {
496
          type: "object",
497
          properties: {
498
            name: { type: "string" },
499
            age: { type: "number" },
500
            hobbies: {
501
              type: "array",
502
              items: { type: "string" },
503
            },
504
          },
505
          required: ["name", "age"],
506
        },
507
      },
508
    },
509
  },
510
});
511

512
const finalResponse = await stream.finalResponse();
513
const parsed = finalResponse.output_parsed;
514
console.log(parsed); // { name: "...", age: ..., hobbies: [...] }
515
```
516

517
### Parsed Responses
518

519
Automatically parses structured outputs with type safety.
520

521
```typescript { .api }
522
/**
523
 * Creates a response and automatically parses structured output.
524
 * Works with Zod schemas for runtime type validation.
525
 *
526
 * @param body - Response creation parameters with structured output config
527
 * @param options - Optional request options
528
 * @returns Promise<ParsedResponse<ParsedT>> with typed parsed output
529
 */
530
function parse<ParsedT = any>(
531
  body: ResponseParseParams,
532
  options?: RequestOptions
533
): APIPromise<ParsedResponse<ParsedT>>;
534

535
interface ParsedResponse<ParsedT> extends Response {
536
  /** Original output items */
537
  output: Array<ParsedResponseOutputItem<ParsedT>>;
538

539
  /** Parsed structured output (null if parsing failed) */
540
  output_parsed: ParsedT | null;
541
}
542
```
543

544
**Usage Examples:**
545

546
```typescript
547
import { zodResponseFormat } from "openai/helpers/zod";
548
import { z } from "zod";
549

550
// Define Zod schema
551
const CalendarEventSchema = z.object({
552
  name: z.string(),
553
  date: z.string(),
554
  participants: z.array(z.string()),
555
});
556

557
// Create response with auto-parsing
558
const response = await client.responses.parse({
559
  model: "gpt-4o",
560
  input: "Create a calendar event for team meeting on Jan 15th with Alice, Bob, and Charlie",
561
  text: {
562
    format: zodResponseFormat(CalendarEventSchema, "CalendarEvent"),
563
  },
564
});
565

566
// output_parsed is fully typed
567
const event = response.output_parsed;
568
if (event) {
569
  console.log(event.name); // Type: string
570
  console.log(event.date); // Type: string
571
  console.log(event.participants); // Type: string[]
572
}
573
```
574

575
### Input Items Listing
576

577
Lists input items used to generate a response.
578

579
```typescript { .api }
580
/**
581
 * Returns a list of input items for a given response.
582
 * Supports cursor-based pagination for large input sets.
583
 *
584
 * @param responseID - The unique response ID
585
 * @param query - Optional pagination and filtering parameters
586
 * @param options - Optional request options
587
 * @returns PagePromise for iterating through input items
588
 */
589
function inputItems.list(
590
  responseID: string,
591
  query?: InputItemListParams,
592
  options?: RequestOptions
593
): PagePromise<ResponseItemsPage, ResponseItem>;
594

595
interface InputItemListParams extends CursorPageParams {
596
  /** Additional fields to include */
597
  include?: Array<ResponseIncludable>;
598

599
  /** Order to return items ('asc' or 'desc') */
600
  order?: "asc" | "desc";
601

602
  /** Cursor for pagination */
603
  after?: string;
604

605
  /** Number of items per page (1-100) */
606
  limit?: number;
607
}
608
```
609

610
**Usage Examples:**
611

612
```typescript
613
// List all input items (auto-pagination)
614
for await (const item of client.responses.inputItems.list("resp_abc123")) {
615
  console.log(item.type, item);
616
}
617

618
// Manual pagination
619
const page = await client.responses.inputItems.list("resp_abc123", {
620
  limit: 10,
621
  order: "asc",
622
});
623

624
console.log(page.data); // Array of items
625
if (page.has_more) {
626
  const nextPage = await page.getNextPage();
627
}
628

629
// With additional fields
630
for await (const item of client.responses.inputItems.list(
631
  "resp_abc123",
632
  { include: ["input_text"] }
633
)) {
634
  console.log(item);
635
}
636
```
637

638
### Input Token Counting
639

640
Counts tokens for input items before creating a response.
641

642
```typescript { .api }
643
/**
644
 * Get input token counts for a potential response.
645
 * Useful for estimating costs and ensuring inputs fit within context windows.
646
 *
647
 * @param body - Same parameters as response creation
648
 * @param options - Optional request options
649
 * @returns Promise<InputTokenCountResponse> with token count
650
 */
651
function inputTokens.count(
652
  body?: InputTokenCountParams,
653
  options?: RequestOptions
654
): APIPromise<InputTokenCountResponse>;
655

656
interface InputTokenCountResponse {
657
  /** Number of input tokens */
658
  input_tokens: number;
659

660
  /** Object type identifier */
661
  object: "response.input_tokens";
662
}
663

664
interface InputTokenCountParams {
665
  /** Model ID to count tokens for */
666
  model?: string | null;
667

668
  /** Input items to count */
669
  input?: string | Array<ResponseInputItem> | null;
670

671
  /** Instructions to count */
672
  instructions?: string | null;
673

674
  /** Conversation ID for context */
675
  conversation?: string | ResponseConversationParam | null;
676

677
  /** Previous response ID for context */
678
  previous_response_id?: string | null;
679

680
  /** Tools that might be used */
681
  tools?: Array<Tool> | null;
682

683
  /** Tool choice configuration */
684
  tool_choice?: any | null;
685

686
  /** Text configuration */
687
  text?: { format?: ResponseFormatTextConfig } | null;
688

689
  /** Reasoning configuration */
690
  reasoning?: Reasoning | null;
691

692
  /** Parallel tool calls setting */
693
  parallel_tool_calls?: boolean | null;
694

695
  /** Truncation strategy */
696
  truncation?: "auto" | "disabled";
697
}
698
```
699

700
**Usage Examples:**
701

702
```typescript
703
// Count tokens for a simple input
704
const count = await client.responses.inputTokens.count({
705
  model: "gpt-4o",
706
  input: "What is the meaning of life?",
707
});
708

709
console.log(count.input_tokens); // e.g., 8
710

711
// Count with complex input
712
const count = await client.responses.inputTokens.count({
713
  model: "gpt-4o",
714
  instructions: "You are a helpful assistant.",
715
  input: [
716
    { type: "text", text: "Analyze this document:" },
717
    { type: "file", file_id: "file-abc123" },
718
  ],
719
  tools: [
720
    {
721
      type: "function",
722
      name: "get_weather",
723
      parameters: { type: "object", properties: {} },
724
      strict: true,
725
    },
726
  ],
727
});
728

729
console.log(`Token count: ${count.input_tokens}`);
730

731
// Count for multi-turn conversation
732
const count = await client.responses.inputTokens.count({
733
  model: "gpt-4o",
734
  input: "What did we discuss earlier?",
735
  previous_response_id: "resp_previous123",
736
});
737
```
738

739
## Type Definitions
740

741
### Core Response Types
742

743
```typescript { .api }
744
/**
745
 * A model response object containing inputs, outputs, metadata, and usage information.
746
 */
747
interface Response {
748
  /** Unique identifier for this Response (e.g., 'resp_abc123') */
749
  id: string;
750

751
  /** Unix timestamp (seconds) of creation */
752
  created_at: number;
753

754
  /** Object type, always 'response' */
755
  object: "response";
756

757
  /** Model ID used (e.g., 'gpt-4o') */
758
  model: ResponsesModel;
759

760
  /** Response generation status */
761
  status?: ResponseStatus;
762

763
  /** Array of content items generated by the model */
764
  output: Array<ResponseOutputItem>;
765

766
  /** Convenience property: concatenated text output */
767
  output_text: string;
768

769
  /** System/developer message in model context */
770
  instructions: string | Array<ResponseInputItem> | null;
771

772
  /** Temperature setting (0-2) */
773
  temperature: number | null;
774

775
  /** Top-p nucleus sampling parameter */
776
  top_p: number | null;
777

778
  /** Maximum output tokens limit */
779
  max_output_tokens?: number | null;
780

781
  /** Tools available to the model */
782
  tools: Array<Tool>;
783

784
  /** Tool selection strategy */
785
  tool_choice: ToolChoiceOptions | ToolChoiceAllowed | ToolChoiceTypes | ToolChoiceFunction | ToolChoiceMcp | ToolChoiceCustom | ToolChoiceApplyPatch | ToolChoiceShell;
786

787
  /** Whether parallel tool calls are allowed */
788
  parallel_tool_calls: boolean;
789

790
  /** Previous response ID for multi-turn conversations */
791
  previous_response_id?: string | null;
792

793
  /** Conversation this response belongs to */
794
  conversation?: Response.Conversation | null;
795

796
  /** Text response configuration */
797
  text?: ResponseTextConfig;
798

799
  /** Reasoning configuration for reasoning models */
800
  reasoning?: Reasoning | null;
801

802
  /** Metadata key-value pairs (max 16 pairs) */
803
  metadata: Metadata | null;
804

805
  /** Truncation strategy used */
806
  truncation?: "auto" | "disabled" | null;
807

808
  /** Whether response ran in background */
809
  background?: boolean | null;
810

811
  /** Token usage statistics */
812
  usage?: ResponseUsage;
813

814
  /** Error information if generation failed */
815
  error: ResponseError | null;
816

817
  /** Details about incomplete responses */
818
  incomplete_details: Response.IncompleteDetails | null;
819

820
  /** Prompt template reference */
821
  prompt?: ResponsePrompt | null;
822

823
  /** Prompt cache key */
824
  prompt_cache_key?: string;
825

826
  /** Prompt cache retention policy */
827
  prompt_cache_retention?: "in-memory" | "24h" | null;
828

829
  /** Service tier used */
830
  service_tier?: "auto" | "default" | "flex" | "scale" | "priority" | null;
831

832
  /** Safety identifier */
833
  safety_identifier?: string;
834

835
  /** @deprecated Use prompt_cache_key instead */
836
  user?: string;
837
}
838

839
namespace Response {
840
  /** Details about why a response is incomplete */
841
  interface IncompleteDetails {
842
    reason?: "max_output_tokens" | "content_filter";
843
  }
844

845
  /** Conversation reference */
846
  interface Conversation {
847
    /** Conversation ID */
848
    id: string;
849
  }
850
}
851

852
/**
853
 * Response generation status values
854
 */
855
type ResponseStatus =
856
  | "completed"      // Successfully completed
857
  | "failed"         // Failed with error
858
  | "in_progress"    // Currently generating
859
  | "cancelled"      // Cancelled by user
860
  | "queued"         // Queued for processing
861
  | "incomplete";    // Incomplete due to max tokens or filter
862

863
/**
864
 * Token usage information for a response
865
 */
866
interface ResponseUsage {
867
  /** Number of tokens in input */
868
  input_tokens: number;
869

870
  /** Number of tokens in output */
871
  output_tokens: number;
872

873
  /** Total tokens (input + output) */
874
  total_tokens: number;
875

876
  /** Detailed output token breakdown */
877
  output_tokens_details?: ResponseUsage.OutputTokensDetails;
878
}
879

880
namespace ResponseUsage {
881
  interface OutputTokensDetails {
882
    /** Tokens used for reasoning (o-series models) */
883
    reasoning_tokens?: number;
884

885
    /** Tokens in text output */
886
    text_tokens?: number;
887

888
    /** Tokens in audio output */
889
    audio_tokens?: number;
890
  }
891
}
892

893
/**
894
 * Error information when response generation fails
895
 */
896
interface ResponseError {
897
  /** Error code */
898
  code: string;
899

900
  /** Human-readable error message */
901
  message: string;
902

903
  /** Additional error details */
904
  param?: string | null;
905

906
  /** Error type */
907
  type?: string;
908
}
909

910
/**
911
 * Text response configuration options
912
 */
913
interface ResponseTextConfig {
914
  /** Output format specification */
915
  format?: ResponseFormatTextConfig;
916

917
  /** Verbosity level for output */
918
  verbosity?: "low" | "medium" | "high" | null;
919
}
920

921
/**
922
 * Response format configuration for text outputs
923
 */
924
type ResponseFormatTextConfig =
925
  | { type: "text" }  // Plain text (default)
926
  | { type: "json_object" }  // Legacy JSON mode
927
  | ResponseFormatTextJSONSchemaConfig  // Structured Outputs
928
  | { type: "text_grammar"; text_grammar: { grammar: string; root_rule?: string } }  // Grammar-constrained
929
  | { type: "text_python"; text_python?: {} };  // Python code generation
930

931
/**
932
 * JSON Schema structured output configuration
933
 */
934
interface ResponseFormatTextJSONSchemaConfig {
935
  type: "json_schema";
936
  json_schema: {
937
    /** Schema name */
938
    name: string;
939

940
    /** JSON Schema definition */
941
    schema?: Record<string, unknown>;
942

943
    /** Whether to enforce strict validation */
944
    strict?: boolean | null;
945

946
    /** Schema description */
947
    description?: string;
948
  };
949
}
950

951
/**
952
 * Prompt template reference
953
 */
954
interface ResponsePrompt {
955
  /** Template ID */
956
  id: string;
957

958
  /** Template variables */
959
  variables?: Record<string, string>;
960
}
961

962
/**
963
 * Conversation parameter for automatic state management
964
 */
965
interface ResponseConversationParam {
966
  /** Conversation ID to add response to */
967
  id: string;
968
}
969

970
/**
971
 * Additional fields that can be included in responses
972
 */
973
type ResponseIncludable =
974
  | "input_text"  // Include concatenated input text
975
  | "output_text"  // Include concatenated output text
976
  | "output[*].content[*].annotations[*].file_citation.quote"  // Include file citation quotes
977
  | "output[*].content[*].annotations[*].file_citation.file.content"  // Include file content
978
  | "web_search_call.action.sources"  // Include sources from web search tool call
979
  | "code_interpreter_call.outputs"  // Include outputs from python code execution
980
  | "computer_call_output.output.image_url"  // Include image URLs from computer call output
981
  | "file_search_call.results"  // Include search results from file search tool call
982
  | "message.input_image.image_url"  // Include image URLs from input message
983
  | "reasoning.encrypted_content";  // Include encrypted reasoning tokens
984
```
985

986
### Input Types
987

988
```typescript { .api }
989
/**
990
 * Input to the model - can be a simple string or array of structured items
991
 */
992
type ResponseInput = Array<ResponseInputItem>;
993

994
/**
995
 * Individual input item - message or tool output
996
 */
997
type ResponseInputItem =
998
  | ResponseInputMessageItem
999
  | EasyInputMessage
1000
  | ResponseFunctionToolCallItem
1001
  | ResponseFunctionToolCallOutputItem
1002
  | ResponseFunctionShellToolCall
1003
  | ResponseFunctionShellToolCallOutput
1004
  | ResponseApplyPatchToolCall
1005
  | ResponseApplyPatchToolCallOutput
1006
  | ResponseComputerToolCallOutputItem
1007
  | ResponseCodeInterpreterToolCall
1008
  | ResponseCustomToolCall
1009
  | ResponseCustomToolCallOutput
1010
  | ResponseFileSearchToolCall
1011
  | ResponseFunctionWebSearch
1012
  | ResponseOutputItem.ImageGenerationCall
1013
  | ResponseOutputItem.LocalShellCall
1014
  | ResponseOutputItem.McpCall
1015
  | ResponseOutputItem.McpListTools
1016
  | ResponseOutputItem.McpApprovalRequest;
1017

1018
/**
1019
 * Message input with role and content
1020
 */
1021
interface ResponseInputMessageItem {
1022
  /** Message content - text, images, files, or audio */
1023
  content: string | ResponseInputMessageContentList;
1024

1025
  /** Message role */
1026
  role: "user" | "assistant" | "system" | "developer";
1027

1028
  /** Item type */
1029
  type: "message";
1030

1031
  /** Item status when returned via API */
1032
  status?: "in_progress" | "completed" | "incomplete";
1033
}
1034

1035
/**
1036
 * Simplified message input format
1037
 */
1038
interface EasyInputMessage {
1039
  /** Message content */
1040
  content: string | ResponseInputMessageContentList;
1041

1042
  /** Message role */
1043
  role: "user" | "assistant" | "system" | "developer";
1044

1045
  /** Optional type field */
1046
  type?: "message";
1047
}
1048

1049
/**
1050
 * Message content list for multi-modal inputs
1051
 */
1052
type ResponseInputMessageContentList = Array<ResponseInputContent>;
1053

1054
/**
1055
 * Content types for message inputs
1056
 */
1057
type ResponseInputContent =
1058
  | ResponseInputText
1059
  | ResponseInputImage
1060
  | ResponseInputFile;
1061

1062
/**
1063
 * Text content input
1064
 */
1065
interface ResponseInputText {
1066
  /** Content type */
1067
  type: "input_text";
1068

1069
  /** The text content */
1070
  text: string;
1071
}
1072

1073
/**
1074
 * Image content input
1075
 */
1076
interface ResponseInputImage {
1077
  /** Content type */
1078
  type: "input_image";
1079

1080
  /** Image source - URL or file ID */
1081
  image_url?: { url: string; detail?: "auto" | "low" | "high" } | null;
1082
  file_id?: string | null;
1083
}
1084

1085
/**
1086
 * File content input
1087
 */
1088
interface ResponseInputFile {
1089
  /** Content type */
1090
  type: "input_file";
1091

1092
  /** File ID from uploads */
1093
  file_id: string;
1094

1095
  /** Optional detail level */
1096
  detail?: "auto" | "low" | "high";
1097
}
1098

1099
/**
1100
 * Audio input
1101
 */
1102
interface ResponseInputAudio {
1103
  /** Content type */
1104
  type: "input_audio";
1105

1106
  /** Audio format */
1107
  format: "wav" | "mp3";
1108

1109
  /** Base64-encoded audio data */
1110
  data?: string | null;
1111

1112
  /** Transcript of the audio */
1113
  transcript?: string | null;
1114
}
1115

1116
/**
1117
 * Text content with inline annotations
1118
 */
1119
interface ResponseInputTextContent {
1120
  /** Content type */
1121
  type: "text";
1122

1123
  /** The text */
1124
  text: string;
1125

1126
  /** Inline annotations (citations, file paths) */
1127
  annotations?: Array<ResponseInputTextContent.Annotation>;
1128
}
1129

1130
namespace ResponseInputTextContent {
1131
  interface Annotation {
1132
    /** Annotation type */
1133
    type: "file_citation" | "file_path";
1134

1135
    /** Annotation details */
1136
    file_citation?: {
1137
      file_id: string;
1138
      quote?: string;
1139
    };
1140
    file_path?: {
1141
      file_id: string;
1142
    };
1143
  }
1144
}
1145

1146
/**
1147
 * Image content with URL or file
1148
 */
1149
interface ResponseInputImageContent {
1150
  /** Content type */
1151
  type: "image";
1152

1153
  /** Image URL */
1154
  image_url?: { url: string; detail?: "auto" | "low" | "high" };
1155

1156
  /** File ID for uploaded image */
1157
  file_id?: string;
1158
}
1159

1160
/**
1161
 * File content reference
1162
 */
1163
interface ResponseInputFileContent {
1164
  /** Content type */
1165
  type: "file";
1166

1167
  /** File ID */
1168
  file_id: string;
1169

1170
  /** Detail level for processing */
1171
  detail?: "auto" | "low" | "high";
1172
}
1173
```
1174

1175
### Output Types
1176

1177
```typescript { .api }
1178
/**
1179
 * Union of all possible output item types
1180
 */
1181
type ResponseOutputItem =
1182
  | ResponseOutputMessage
1183
  | ResponseFunctionToolCall
1184
  | ResponseCustomToolCall
1185
  | ResponseFileSearchToolCall
1186
  | ResponseFunctionWebSearch
1187
  | ResponseComputerToolCall
1188
  | ResponseReasoningItem
1189
  | ResponseCodeInterpreterToolCall
1190
  | ResponseApplyPatchToolCall
1191
  | ResponseApplyPatchToolCallOutput
1192
  | ResponseFunctionShellToolCall
1193
  | ResponseFunctionShellToolCallOutput
1194
  | ResponseOutputItem.ImageGenerationCall
1195
  | ResponseOutputItem.LocalShellCall
1196
  | ResponseOutputItem.McpCall
1197
  | ResponseOutputItem.McpListTools
1198
  | ResponseOutputItem.McpApprovalRequest;
1199

1200
/**
1201
 * Message output from the model
1202
 */
1203
interface ResponseOutputMessage {
1204
  /** Unique ID of the message */
1205
  id: string;
1206

1207
  /** Message type */
1208
  type: "message";
1209

1210
  /** Message role (always 'assistant') */
1211
  role: "assistant";
1212

1213
  /** Message status */
1214
  status: "in_progress" | "completed" | "incomplete";
1215

1216
  /** Message content items */
1217
  content: Array<ResponseOutputText | ResponseOutputRefusal | ResponseOutputAudio | ResponseContent.ReasoningTextContent>;
1218

1219
  /** Entity that created this message */
1220
  created_by?: string;
1221
}
1222

1223
/**
1224
 * Text output content
1225
 */
1226
interface ResponseOutputText {
1227
  /** Content type */
1228
  type: "text";
1229

1230
  /** The generated text */
1231
  text: string;
1232

1233
  /** Inline annotations (file citations) */
1234
  annotations?: Array<ResponseOutputText.Annotation>;
1235
}
1236

1237
namespace ResponseOutputText {
1238
  /** File citation annotation */
1239
  interface Annotation {
1240
    type: "file_citation";
1241
    text: string;
1242
    file_citation: {
1243
      file_id: string;
1244
      quote?: string;
1245
    };
1246
    start_index: number;
1247
    end_index: number;
1248
  }
1249
}
1250

1251
/**
1252
 * Refusal output when model declines to answer
1253
 */
1254
interface ResponseOutputRefusal {
1255
  /** Content type */
1256
  type: "refusal";
1257

1258
  /** The refusal message */
1259
  refusal: string;
1260
}
1261

1262
/**
1263
 * Audio output content
1264
 */
1265
interface ResponseOutputAudio {
1266
  /** Content type */
1267
  type: "audio";
1268

1269
  /** Audio ID */
1270
  id: string;
1271

1272
  /** Audio data (Base64) */
1273
  data?: string | null;
1274

1275
  /** Audio transcript */
1276
  transcript?: string | null;
1277

1278
  /** Expiration timestamp */
1279
  expires_at?: number | null;
1280
}
1281

1282
/**
1283
 * Reasoning output from o-series models
1284
 */
1285
interface ResponseReasoningItem {
1286
  /** Unique ID */
1287
  id: string;
1288

1289
  /** Item type */
1290
  type: "reasoning";
1291

1292
  /** Reasoning status */
1293
  status: "in_progress" | "completed";
1294

1295
  /** Reasoning content */
1296
  content: Array<{
1297
    type: "reasoning_text";
1298
    reasoning_text: string;
1299
  }>;
1300

1301
  /** Summary of reasoning */
1302
  summary?: {
1303
    type: "reasoning_summary";
1304
    reasoning_summary: string;
1305
  };
1306
}
1307

1308
/**
1309
 * Generic response item (union type for input/output)
1310
 */
1311
type ResponseItem =
1312
  | ResponseInputMessageItem
1313
  | ResponseOutputMessage
1314
  | ResponseFunctionToolCall
1315
  | ResponseFunctionToolCallOutputItem
1316
  | ResponseCustomToolCall
1317
  | ResponseCustomToolCallOutput
1318
  | ResponseFileSearchToolCall
1319
  | ResponseFunctionWebSearch
1320
  | ResponseComputerToolCall
1321
  | ResponseComputerToolCallOutputItem
1322
  | ResponseCodeInterpreterToolCall
1323
  | ResponseReasoningItem
1324
  | ResponseApplyPatchToolCall
1325
  | ResponseApplyPatchToolCallOutput
1326
  | ResponseFunctionShellToolCall
1327
  | ResponseFunctionShellToolCallOutput
1328
  | ResponseOutputItem.ImageGenerationCall
1329
  | ResponseOutputItem.LocalShellCall
1330
  | ResponseOutputItem.McpCall
1331
  | ResponseOutputItem.McpListTools
1332
  | ResponseOutputItem.McpApprovalRequest;
1333
```
1334

1335
### Tool Types
1336

1337
```typescript { .api }
1338
/**
1339
 * Union of all tool types available in Responses API
1340
 */
1341
type Tool =
1342
  | FunctionTool
1343
  | CustomTool
1344
  | FileSearchTool
1345
  | WebSearchTool
1346
  | WebSearchPreviewTool
1347
  | ComputerTool
1348
  | CodeInterpreterTool
1349
  | ApplyPatchTool
1350
  | FunctionShellTool
1351
  | McpTool
1352
  | ImageGenerationTool
1353
  | LocalShellTool;
1354

1355
/**
1356
 * Function calling tool definition
1357
 */
1358
interface FunctionTool {
1359
  /** Tool type */
1360
  type: "function";
1361

1362
  /** Function name */
1363
  name: string;
1364

1365
  /** Function description for model */
1366
  description?: string | null;
1367

1368
  /** JSON Schema for parameters */
1369
  parameters: Record<string, unknown> | null;
1370

1371
  /** Whether to enforce strict validation */
1372
  strict: boolean | null;
1373
}
1374

1375
/**
1376
 * Custom tool with specialized input format
1377
 */
1378
interface CustomTool {
1379
  /** Tool type */
1380
  type: "custom";
1381

1382
  /** Tool name */
1383
  name: string;
1384

1385
  /** Tool description */
1386
  description?: string;
1387

1388
  /** Input format specification */
1389
  format?: CustomToolInputFormat;
1390
}
1391

1392
/**
1393
 * File search tool for querying vector stores
1394
 */
1395
interface FileSearchTool {
1396
  /** Tool type */
1397
  type: "file_search";
1398

1399
  /** Vector store IDs to search */
1400
  vector_store_ids: Array<string>;
1401

1402
  /** Maximum number of results (1-50) */
1403
  max_num_results?: number;
1404

1405
  /** Search filters */
1406
  filters?: ComparisonFilter | CompoundFilter | null;
1407

1408
  /** Ranking options */
1409
  ranking_options?: FileSearchTool.RankingOptions;
1410
}
1411

1412
namespace FileSearchTool {
1413
  interface RankingOptions {
1414
    /** Ranker to use */
1415
    ranker?: "auto" | "default-2024-11-15";
1416

1417
    /** Score threshold (0-1) */
1418
    score_threshold?: number;
1419

1420
    /** Hybrid search weights */
1421
    hybrid_search?: {
1422
      embedding_weight: number;
1423
      text_weight: number;
1424
    };
1425
  }
1426
}
1427

1428
/**
1429
 * Web search tool for internet queries
1430
 */
1431
interface WebSearchTool {
1432
  /** Tool type */
1433
  type: "web_search";
1434
}
1435

1436
/**
1437
 * Web search tool with preview features and location support.
1438
 * Allows the model to search the web with configurable context size and user location.
1439
 */
1440
interface WebSearchPreviewTool {
1441
  /** Tool type - web_search_preview or web_search_preview_2025_03_11 */
1442
  type: "web_search_preview" | "web_search_preview_2025_03_11";
1443

1444
  /**
1445
   * High level guidance for the amount of context window space to use for search.
1446
   * Options: 'low', 'medium', 'high'. Default: 'medium'.
1447
   */
1448
  search_context_size?: "low" | "medium" | "high";
1449

1450
  /** The user's location for localized search results */
1451
  user_location?: {
1452
    /** Location type - always 'approximate' */
1453
    type: "approximate";
1454
    /** City of the user (e.g., 'San Francisco') */
1455
    city?: string | null;
1456
    /** Two-letter ISO country code (e.g., 'US') */
1457
    country?: string | null;
1458
    /** Region of the user (e.g., 'California') */
1459
    region?: string | null;
1460
    /** IANA timezone (e.g., 'America/Los_Angeles') */
1461
    timezone?: string | null;
1462
  } | null;
1463
}
1464

1465
/**
1466
 * Computer use tool for virtual computer control
1467
 */
1468
interface ComputerTool {
1469
  /** Tool type */
1470
  type: "computer_use_preview";
1471

1472
  /** Display width in pixels */
1473
  display_width: number;
1474

1475
  /** Display height in pixels */
1476
  display_height: number;
1477

1478
  /** Environment type */
1479
  environment: "windows" | "mac" | "linux" | "ubuntu" | "browser";
1480
}
1481

1482
/**
1483
 * Code interpreter tool for running Python code
1484
 */
1485
interface CodeInterpreterTool {
1486
  /** Tool type */
1487
  type: "code_interpreter";
1488

1489
  /** The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs */
1490
  container: string | CodeInterpreterToolAuto;
1491
}
1492

1493
/**
1494
 * Configuration for a code interpreter container
1495
 */
1496
interface CodeInterpreterToolAuto {
1497
  /** Always 'auto' */
1498
  type: "auto";
1499

1500
  /** Optional list of uploaded files to make available to your code */
1501
  file_ids?: Array<string>;
1502

1503
  /** Memory limit for the container */
1504
  memory_limit?: "1g" | "4g" | "16g" | "64g" | null;
1505
}
1506

1507
/**
1508
 * Apply patch tool for file operations
1509
 */
1510
interface ApplyPatchTool {
1511
  /** Tool type */
1512
  type: "apply_patch";
1513
}
1514

1515
/**
1516
 * Shell execution tool
1517
 */
1518
interface FunctionShellTool {
1519
  /** Tool type */
1520
  type: "shell";
1521
}
1522

1523
/**
1524
 * MCP (Model Context Protocol) tool for accessing remote MCP servers
1525
 */
1526
interface McpTool {
1527
  /** Tool type */
1528
  type: "mcp";
1529

1530
  /** A label for this MCP server, used to identify it in tool calls */
1531
  server_label: string;
1532

1533
  /** List of allowed tool names or a filter object */
1534
  allowed_tools?: Array<string> | McpToolFilter | null;
1535

1536
  /** OAuth access token for authenticating with a remote MCP server */
1537
  authorization?: string;
1538

1539
  /** Service connector identifier (e.g., 'connector_dropbox', 'connector_gmail') */
1540
  connector_id?:
1541
    | "connector_dropbox"
1542
    | "connector_gmail"
1543
    | "connector_googlecalendar"
1544
    | "connector_googledrive"
1545
    | "connector_microsoftteams"
1546
    | "connector_outlookcalendar"
1547
    | "connector_outlookemail"
1548
    | "connector_sharepoint";
1549

1550
  /** Optional HTTP headers to send to the MCP server */
1551
  headers?: { [key: string]: string } | null;
1552

1553
  /** Specify which of the MCP server's tools require approval */
1554
  require_approval?: McpToolApprovalFilter | "always" | "never" | null;
1555

1556
  /** Optional description of the MCP server */
1557
  server_description?: string;
1558

1559
  /** The URL for the MCP server. One of server_url or connector_id must be provided */
1560
  server_url?: string;
1561
}
1562

1563
/**
1564
 * Filter object to specify which MCP tools are allowed
1565
 */
1566
interface McpToolFilter {
1567
  /** Whether tool modifies data or is read-only */
1568
  read_only?: boolean;
1569

1570
  /** List of allowed tool names */
1571
  tool_names?: Array<string>;
1572
}
1573

1574
/**
1575
 * Filter for MCP tool approval requirements
1576
 */
1577
interface McpToolApprovalFilter {
1578
  /** Tools that always require approval */
1579
  always?: McpToolFilterSpec;
1580

1581
  /** Tools that never require approval */
1582
  never?: McpToolFilterSpec;
1583
}
1584

1585
/**
1586
 * Filter specification for MCP tool approval
1587
 */
1588
interface McpToolFilterSpec {
1589
  /** Whether tool modifies data or is read-only */
1590
  read_only?: boolean;
1591

1592
  /** List of tool names */
1593
  tool_names?: Array<string>;
1594
}
1595

1596
/**
1597
 * Image generation tool using models like gpt-image-1
1598
 */
1599
interface ImageGenerationTool {
1600
  /** Tool type */
1601
  type: "image_generation";
1602

1603
  /** Background type for the generated image */
1604
  background?: "transparent" | "opaque" | "auto";
1605

1606
  /** Control how much effort the model will exert to match input image features */
1607
  input_fidelity?: "high" | "low" | null;
1608

1609
  /** Optional mask for inpainting */
1610
  input_image_mask?: {
1611
    image_url?: string;
1612
    file_id?: string;
1613
  };
1614

1615
  /** The image generation model to use */
1616
  model?: "gpt-image-1" | "gpt-image-1-mini";
1617

1618
  /** Moderation level for the generated image */
1619
  moderation?: "auto" | "low";
1620

1621
  /** Compression level for the output image (0-100) */
1622
  output_compression?: number;
1623

1624
  /** The output format of the generated image */
1625
  output_format?: "png" | "webp" | "jpeg";
1626

1627
  /** Number of partial images to generate in streaming mode (0-3) */
1628
  partial_images?: number;
1629

1630
  /** The quality of the generated image */
1631
  quality?: "low" | "medium" | "high" | "auto";
1632

1633
  /** The size of the generated image */
1634
  size?: "1024x1024" | "1024x1536" | "1536x1024" | "auto";
1635

1636
  /** The style of the generated image */
1637
  style?: "natural" | "vivid";
1638
}
1639

1640
/**
1641
 * Local shell execution tool
1642
 */
1643
interface LocalShellTool {
1644
  /** Tool type */
1645
  type: "local_shell";
1646
}
1647

1648
/**
1649
 * Tool choice configuration
1650
 */
1651
type ToolChoiceOptions =
1652
  | "auto"      // Model decides
1653
  | "required"  // Must use a tool
1654
  | "none";     // No tools
1655

1656
type ToolChoiceAllowed = "allowed";  // Tools allowed but not required
1657

1658
type ToolChoiceTypes =
1659
  | "function"
1660
  | "file_search"
1661
  | "web_search"
1662
  | "computer_use_preview"
1663
  | "code_interpreter"
1664
  | "apply_patch"
1665
  | "shell"
1666
  | "custom"
1667
  | "mcp";
1668

1669
/**
1670
 * Specific function tool choice
1671
 */
1672
interface ToolChoiceFunction {
1673
  type: "function";
1674
  function: { name: string };
1675
}
1676

1677
/**
1678
 * Specific custom tool choice
1679
 */
1680
interface ToolChoiceCustom {
1681
  type: "custom";
1682
  custom: { name: string };
1683
}
1684

1685
/**
1686
 * Specific MCP tool choice
1687
 */
1688
interface ToolChoiceMcp {
1689
  type: "mcp";
1690
  mcp: {
1691
    server_name: string;
1692
    tool_name?: string;
1693
  };
1694
}
1695

1696
/**
1697
 * Specific apply_patch tool choice
1698
 */
1699
interface ToolChoiceApplyPatch {
1700
  type: "apply_patch";
1701
}
1702

1703
/**
1704
 * Specific shell tool choice
1705
 */
1706
interface ToolChoiceShell {
1707
  type: "shell";
1708
}
1709
```
1710

1711
### Tool Call Output Types
1712

1713
```typescript { .api }
1714
/**
1715
 * Function tool call from model
1716
 */
1717
interface ResponseFunctionToolCall {
1718
  /** Unique ID */
1719
  id: string;
1720

1721
  /** Item type */
1722
  type: "function_call";
1723

1724
  /** Function name */
1725
  name: string;
1726

1727
  /** Function arguments (JSON string) */
1728
  arguments: string;
1729

1730
  /** Unique call ID */
1731
  call_id: string;
1732

1733
  /** Call status */
1734
  status: "in_progress" | "completed";
1735

1736
  /** Creator entity ID */
1737
  created_by?: string;
1738
}
1739

1740
/**
1741
 * Function tool call output
1742
 */
1743
interface ResponseFunctionToolCallOutputItem {
1744
  /** Unique ID */
1745
  id: string;
1746

1747
  /** Item type */
1748
  type: "function_call_output";
1749

1750
  /** Corresponding call ID */
1751
  call_id: string;
1752

1753
  /** Function output */
1754
  output: string | Array<ResponseFunctionCallOutputItem>;
1755

1756
  /** Creator entity ID */
1757
  created_by?: string;
1758
}
1759

1760
/**
1761
 * Function call output item types
1762
 */
1763
type ResponseFunctionCallOutputItem =
1764
  | { type: "text"; text: string }
1765
  | { type: "image"; image_url?: { url: string }; file_id?: string }
1766
  | { type: "file"; file_id: string };
1767

1768
/**
1769
 * Custom tool call
1770
 */
1771
interface ResponseCustomToolCall {
1772
  /** Unique ID */
1773
  id: string;
1774

1775
  /** Item type */
1776
  type: "custom_call";
1777

1778
  /** Tool name */
1779
  name: string;
1780

1781
  /** Tool input */
1782
  input: string;
1783

1784
  /** Unique call ID */
1785
  call_id: string;
1786

1787
  /** Call status */
1788
  status: "in_progress" | "completed";
1789

1790
  /** Creator entity ID */
1791
  created_by?: string;
1792
}
1793

1794
/**
1795
 * Custom tool call output
1796
 */
1797
interface ResponseCustomToolCallOutput {
1798
  /** Unique ID */
1799
  id: string;
1800

1801
  /** Item type */
1802
  type: "custom_call_output";
1803

1804
  /** Corresponding call ID */
1805
  call_id: string;
1806

1807
  /** Tool output */
1808
  output: string | null;
1809

1810
  /** Creator entity ID */
1811
  created_by?: string;
1812
}
1813

1814
/**
1815
 * File search tool call
1816
 */
1817
interface ResponseFileSearchToolCall {
1818
  /** Unique ID */
1819
  id: string;
1820

1821
  /** Item type */
1822
  type: "file_search_call";
1823

1824
  /** Unique call ID */
1825
  call_id: string;
1826

1827
  /** Search results */
1828
  results: Array<ResponseFileSearchToolCall.Result> | null;
1829

1830
  /** Call status */
1831
  status: "in_progress" | "completed" | "searching";
1832

1833
  /** Creator entity ID */
1834
  created_by?: string;
1835
}
1836

1837
namespace ResponseFileSearchToolCall {
1838
  interface Result {
1839
    /** File ID */
1840
    file_id: string;
1841

1842
    /** File name */
1843
    file_name?: string;
1844

1845
    /** Relevance score */
1846
    score?: number;
1847

1848
    /** Matching content snippets */
1849
    content?: Array<{ type: "text"; text: string }>;
1850
  }
1851
}
1852

1853
/**
1854
 * Web search tool call
1855
 */
1856
interface ResponseFunctionWebSearch {
1857
  /** Unique ID */
1858
  id: string;
1859

1860
  /** Item type */
1861
  type: "web_search_call";
1862

1863
  /** Search query */
1864
  query: string;
1865

1866
  /** Unique call ID */
1867
  call_id: string;
1868

1869
  /** Search results */
1870
  results: Array<ResponseFunctionWebSearch.Result> | null;
1871

1872
  /** Call status */
1873
  status: "in_progress" | "completed" | "searching";
1874

1875
  /** Creator entity ID */
1876
  created_by?: string;
1877
}
1878

1879
namespace ResponseFunctionWebSearch {
1880
  interface Result {
1881
    /** Result URL */
1882
    url: string;
1883

1884
    /** Page title */
1885
    title?: string;
1886

1887
    /** Content snippet */
1888
    snippet?: string;
1889
  }
1890
}
1891

1892
/**
1893
 * Computer use tool call
1894
 */
1895
interface ResponseComputerToolCall {
1896
  /** Unique ID */
1897
  id: string;
1898

1899
  /** Item type */
1900
  type: "computer_call";
1901

1902
  /** Unique call ID */
1903
  call_id: string;
1904

1905
  /** Computer action */
1906
  action:
1907
    | { type: "click"; x: number; y: number; button: "left" | "right" | "wheel" | "back" | "forward" }
1908
    | { type: "double_click"; x: number; y: number }
1909
    | { type: "drag"; path: Array<{ x: number; y: number }> }
1910
    | { type: "keypress"; keys: Array<string> }
1911
    | { type: "move"; x: number; y: number }
1912
    | { type: "screenshot" }
1913
    | { type: "scroll"; x: number; y: number; scroll_x: number; scroll_y: number }
1914
    | { type: "type"; text: string }
1915
    | { type: "wait" };
1916

1917
  /** Call status */
1918
  status: "in_progress" | "completed" | "incomplete";
1919

1920
  /** Pending safety checks */
1921
  pending_safety_checks: Array<{
1922
    id: string;
1923
    code?: string | null;
1924
    message?: string | null;
1925
  }>;
1926
}
1927

1928
/**
1929
 * Computer use tool output
1930
 */
1931
interface ResponseComputerToolCallOutputItem {
1932
  /** Unique ID */
1933
  id: string;
1934

1935
  /** Item type */
1936
  type: "computer_call_output";
1937

1938
  /** Corresponding call ID */
1939
  call_id: string;
1940

1941
  /** Screenshot output */
1942
  output: ResponseComputerToolCallOutputScreenshot;
1943

1944
  /** Call status */
1945
  status?: "in_progress" | "completed" | "incomplete";
1946

1947
  /** Acknowledged safety checks */
1948
  acknowledged_safety_checks?: Array<{
1949
    id: string;
1950
    code?: string | null;
1951
    message?: string | null;
1952
  }>;
1953
}
1954

1955
/**
1956
 * Computer screenshot output
1957
 */
1958
interface ResponseComputerToolCallOutputScreenshot {
1959
  /** Content type */
1960
  type: "computer_screenshot";
1961

1962
  /** File ID of screenshot */
1963
  file_id?: string;
1964

1965
  /** Image URL */
1966
  image_url?: string;
1967
}
1968

1969
/**
1970
 * Code interpreter tool call
1971
 */
1972
interface ResponseCodeInterpreterToolCall {
1973
  /** Unique ID */
1974
  id: string;
1975

1976
  /** Item type */
1977
  type: "code_interpreter_call";
1978

1979
  /** Python code */
1980
  code: string | null;
1981

1982
  /** Container ID */
1983
  container_id: string;
1984

1985
  /** Code outputs */
1986
  outputs: Array<
1987
    | { type: "logs"; logs: string }
1988
    | { type: "image"; url: string }
1989
  > | null;
1990

1991
  /** Call status */
1992
  status: "in_progress" | "completed" | "incomplete" | "interpreting" | "failed";
1993
}
1994

1995
/**
1996
 * Apply patch tool call
1997
 */
1998
interface ResponseApplyPatchToolCall {
1999
  /** Unique ID */
2000
  id: string;
2001

2002
  /** Item type */
2003
  type: "apply_patch_call";
2004

2005
  /** Unique call ID */
2006
  call_id: string;
2007

2008
  /** File operation */
2009
  operation:
2010
    | { type: "create_file"; path: string; diff: string }
2011
    | { type: "delete_file"; path: string }
2012
    | { type: "update_file"; path: string; diff: string };
2013

2014
  /** Call status */
2015
  status: "in_progress" | "completed";
2016

2017
  /** Creator entity ID */
2018
  created_by?: string;
2019
}
2020

2021
/**
2022
 * Apply patch output
2023
 */
2024
interface ResponseApplyPatchToolCallOutput {
2025
  /** Unique ID */
2026
  id: string;
2027

2028
  /** Item type */
2029
  type: "apply_patch_call_output";
2030

2031
  /** Corresponding call ID */
2032
  call_id: string;
2033

2034
  /** Operation output */
2035
  output?: string | null;
2036

2037
  /** Output status */
2038
  status: "completed" | "failed";
2039

2040
  /** Creator entity ID */
2041
  created_by?: string;
2042
}
2043

2044
/**
2045
 * Shell tool call
2046
 */
2047
interface ResponseFunctionShellToolCall {
2048
  /** Unique ID */
2049
  id: string;
2050

2051
  /** Item type */
2052
  type: "shell_call";
2053

2054
  /** Shell command */
2055
  command: string;
2056

2057
  /** Unique call ID */
2058
  call_id: string;
2059

2060
  /** Call status */
2061
  status: "in_progress" | "completed";
2062

2063
  /** Creator entity ID */
2064
  created_by?: string;
2065
}
2066

2067
/**
2068
 * Shell tool output
2069
 */
2070
interface ResponseFunctionShellToolCallOutput {
2071
  /** Unique ID */
2072
  id: string;
2073

2074
  /** Item type */
2075
  type: "shell_call_output";
2076

2077
  /** Corresponding call ID */
2078
  call_id: string;
2079

2080
  /** Shell output */
2081
  output: Array<ResponseFunctionShellCallOutputContent>;
2082

2083
  /** Creator entity ID */
2084
  created_by?: string;
2085
}
2086

2087
/**
2088
 * Shell output content
2089
 */
2090
interface ResponseFunctionShellCallOutputContent {
2091
  /** Content type */
2092
  type: "text" | "image";
2093

2094
  /** Text content */
2095
  text?: string;
2096

2097
  /** Image URL */
2098
  image_url?: { url: string };
2099

2100
  /** File ID */
2101
  file_id?: string;
2102
}
2103
```
2104

2105
### Streaming Event Types
2106

2107
```typescript { .api }
2108
/**
2109
 * Union of all streaming event types
2110
 */
2111
type ResponseStreamEvent =
2112
  | ResponseCreatedEvent
2113
  | ResponseQueuedEvent
2114
  | ResponseInProgressEvent
2115
  | ResponseCompletedEvent
2116
  | ResponseFailedEvent
2117
  | ResponseIncompleteEvent
2118
  | ResponseErrorEvent
2119
  | ResponseOutputItemAddedEvent
2120
  | ResponseOutputItemDoneEvent
2121
  | ResponseContentPartAddedEvent
2122
  | ResponseContentPartDoneEvent
2123
  | ResponseTextDeltaEvent
2124
  | ResponseTextDoneEvent
2125
  | ResponseRefusalDeltaEvent
2126
  | ResponseRefusalDoneEvent
2127
  | ResponseAudioDeltaEvent
2128
  | ResponseAudioDoneEvent
2129
  | ResponseAudioTranscriptDeltaEvent
2130
  | ResponseAudioTranscriptDoneEvent
2131
  | ResponseFunctionCallArgumentsDeltaEvent
2132
  | ResponseFunctionCallArgumentsDoneEvent
2133
  | ResponseCustomToolCallInputDeltaEvent
2134
  | ResponseCustomToolCallInputDoneEvent
2135
  | ResponseFileSearchCallInProgressEvent
2136
  | ResponseFileSearchCallSearchingEvent
2137
  | ResponseFileSearchCallCompletedEvent
2138
  | ResponseWebSearchCallInProgressEvent
2139
  | ResponseWebSearchCallSearchingEvent
2140
  | ResponseWebSearchCallCompletedEvent
2141
  | ResponseCodeInterpreterCallInProgressEvent
2142
  | ResponseCodeInterpreterCallInterpretingEvent
2143
  | ResponseCodeInterpreterCallCompletedEvent
2144
  | ResponseCodeInterpreterCallCodeDeltaEvent
2145
  | ResponseCodeInterpreterCallCodeDoneEvent
2146
  | ResponseImageGenCallInProgressEvent
2147
  | ResponseImageGenCallGeneratingEvent
2148
  | ResponseImageGenCallPartialImageEvent
2149
  | ResponseImageGenCallCompletedEvent
2150
  | ResponseReasoningTextDeltaEvent
2151
  | ResponseReasoningTextDoneEvent
2152
  | ResponseReasoningSummaryPartAddedEvent
2153
  | ResponseReasoningSummaryPartDoneEvent
2154
  | ResponseReasoningSummaryTextDeltaEvent
2155
  | ResponseReasoningSummaryTextDoneEvent
2156
  | ResponseOutputTextAnnotationAddedEvent
2157
  | ResponseMcpCallInProgressEvent
2158
  | ResponseMcpCallArgumentsDeltaEvent
2159
  | ResponseMcpCallArgumentsDoneEvent
2160
  | ResponseMcpCallCompletedEvent
2161
  | ResponseMcpCallFailedEvent
2162
  | ResponseMcpListToolsInProgressEvent
2163
  | ResponseMcpListToolsCompletedEvent
2164
  | ResponseMcpListToolsFailedEvent;
2165

2166
/**
2167
 * Response lifecycle events
2168
 */
2169

2170
/** Emitted when response is created */
2171
interface ResponseCreatedEvent {
2172
  type: "response.created";
2173
  sequence_number: number;
2174
  response: Response;
2175
}
2176

2177
/** Emitted when response is queued */
2178
interface ResponseQueuedEvent {
2179
  type: "response.queued";
2180
  sequence_number: number;
2181
  response: Response;
2182
}
2183

2184
/** Emitted when response starts processing */
2185
interface ResponseInProgressEvent {
2186
  type: "response.in_progress";
2187
  sequence_number: number;
2188
  response: Response;
2189
}
2190

2191
/** Emitted when response completes successfully */
2192
interface ResponseCompletedEvent {
2193
  type: "response.completed";
2194
  sequence_number: number;
2195
  response: Response;
2196
}
2197

2198
/** Emitted when response fails */
2199
interface ResponseFailedEvent {
2200
  type: "response.failed";
2201
  sequence_number: number;
2202
  response: Response;
2203
  error: ResponseError;
2204
}
2205

2206
/** Emitted when response is incomplete */
2207
interface ResponseIncompleteEvent {
2208
  type: "response.incomplete";
2209
  sequence_number: number;
2210
  response: Response;
2211
}
2212

2213
/** Emitted on error */
2214
interface ResponseErrorEvent {
2215
  type: "error";
2216
  sequence_number: number;
2217
  error: ResponseError;
2218
}
2219

2220
/**
2221
 * Output item events
2222
 */
2223

2224
/** Emitted when new output item is added */
2225
interface ResponseOutputItemAddedEvent {
2226
  type: "response.output_item.added";
2227
  sequence_number: number;
2228
  item_id: string;
2229
  output_index: number;
2230
  item: ResponseOutputItem;
2231
}
2232

2233
/** Emitted when output item is complete */
2234
interface ResponseOutputItemDoneEvent {
2235
  type: "response.output_item.done";
2236
  sequence_number: number;
2237
  item_id: string;
2238
  output_index: number;
2239
  item: ResponseOutputItem;
2240
}
2241

2242
/**
2243
 * Content part events
2244
 */
2245

2246
/** Emitted when content part is added */
2247
interface ResponseContentPartAddedEvent {
2248
  type: "response.content_part.added";
2249
  sequence_number: number;
2250
  item_id: string;
2251
  output_index: number;
2252
  content_index: number;
2253
  part: ResponseContent;
2254
}
2255

2256
/** Emitted when content part is complete */
2257
interface ResponseContentPartDoneEvent {
2258
  type: "response.content_part.done";
2259
  sequence_number: number;
2260
  item_id: string;
2261
  output_index: number;
2262
  content_index: number;
2263
  part: ResponseContent;
2264
}
2265

2266
/**
2267
 * Text streaming events
2268
 */
2269

2270
/** Emitted for each text delta */
2271
interface ResponseTextDeltaEvent {
2272
  type: "response.text.delta";
2273
  sequence_number: number;
2274
  item_id: string;
2275
  output_index: number;
2276
  content_index: number;
2277
  delta: string;
2278
}
2279

2280
/** Emitted when text is complete */
2281
interface ResponseTextDoneEvent {
2282
  type: "response.text.done";
2283
  sequence_number: number;
2284
  item_id: string;
2285
  output_index: number;
2286
  content_index: number;
2287
  text: string;
2288
}
2289

2290
/**
2291
 * Refusal streaming events
2292
 */
2293

2294
/** Emitted for each refusal delta */
2295
interface ResponseRefusalDeltaEvent {
2296
  type: "response.refusal.delta";
2297
  sequence_number: number;
2298
  item_id: string;
2299
  output_index: number;
2300
  content_index: number;
2301
  delta: string;
2302
}
2303

2304
/** Emitted when refusal is complete */
2305
interface ResponseRefusalDoneEvent {
2306
  type: "response.refusal.done";
2307
  sequence_number: number;
2308
  item_id: string;
2309
  output_index: number;
2310
  content_index: number;
2311
  refusal: string;
2312
}
2313

2314
/**
2315
 * Audio streaming events
2316
 */
2317

2318
/** Emitted for each audio data chunk */
2319
interface ResponseAudioDeltaEvent {
2320
  type: "response.audio.delta";
2321
  sequence_number: number;
2322
  delta: string;  // Base64-encoded audio bytes
2323
}
2324

2325
/** Emitted when audio is complete */
2326
interface ResponseAudioDoneEvent {
2327
  type: "response.audio.done";
2328
  sequence_number: number;
2329
}
2330

2331
/** Emitted for each audio transcript delta */
2332
interface ResponseAudioTranscriptDeltaEvent {
2333
  type: "response.audio.transcript.delta";
2334
  sequence_number: number;
2335
  delta: string;
2336
}
2337

2338
/** Emitted when audio transcript is complete */
2339
interface ResponseAudioTranscriptDoneEvent {
2340
  type: "response.audio.transcript.done";
2341
  sequence_number: number;
2342
}
2343

2344
/**
2345
 * Function call streaming events
2346
 */
2347

2348
/** Emitted for each function arguments delta */
2349
interface ResponseFunctionCallArgumentsDeltaEvent {
2350
  type: "response.function_call_arguments.delta";
2351
  sequence_number: number;
2352
  item_id: string;
2353
  output_index: number;
2354
  delta: string;
2355
}
2356

2357
/** Emitted when function arguments are complete */
2358
interface ResponseFunctionCallArgumentsDoneEvent {
2359
  type: "response.function_call_arguments.done";
2360
  sequence_number: number;
2361
  item_id: string;
2362
  output_index: number;
2363
  arguments: string;
2364
  name: string;
2365
  call_id: string;
2366
}
2367

2368
/**
2369
 * Custom tool call streaming events
2370
 */
2371

2372
/** Emitted for each custom tool input delta */
2373
interface ResponseCustomToolCallInputDeltaEvent {
2374
  type: "response.custom_call_input.delta";
2375
  sequence_number: number;
2376
  item_id: string;
2377
  output_index: number;
2378
  delta: string;
2379
}
2380

2381
/** Emitted when custom tool input is complete */
2382
interface ResponseCustomToolCallInputDoneEvent {
2383
  type: "response.custom_call_input.done";
2384
  sequence_number: number;
2385
  item_id: string;
2386
  output_index: number;
2387
  input: string;
2388
  name: string;
2389
  call_id: string;
2390
}
2391

2392
/**
2393
 * File search streaming events
2394
 */
2395

2396
/** Emitted when file search starts */
2397
interface ResponseFileSearchCallInProgressEvent {
2398
  type: "response.file_search_call.in_progress";
2399
  sequence_number: number;
2400
  item_id: string;
2401
  output_index: number;
2402
}
2403

2404
/** Emitted when file search is actively searching */
2405
interface ResponseFileSearchCallSearchingEvent {
2406
  type: "response.file_search_call.searching";
2407
  sequence_number: number;
2408
  item_id: string;
2409
  output_index: number;
2410
}
2411

2412
/** Emitted when file search completes */
2413
interface ResponseFileSearchCallCompletedEvent {
2414
  type: "response.file_search_call.completed";
2415
  sequence_number: number;
2416
  item_id: string;
2417
  output_index: number;
2418
  results: Array<any>;
2419
}
2420

2421
/**
2422
 * Web search streaming events
2423
 */
2424

2425
/** Emitted when web search starts */
2426
interface ResponseWebSearchCallInProgressEvent {
2427
  type: "response.web_search_call.in_progress";
2428
  sequence_number: number;
2429
  item_id: string;
2430
  output_index: number;
2431
}
2432

2433
/** Emitted when web search is actively searching */
2434
interface ResponseWebSearchCallSearchingEvent {
2435
  type: "response.web_search_call.searching";
2436
  sequence_number: number;
2437
  item_id: string;
2438
  output_index: number;
2439
  query: string;
2440
}
2441

2442
/** Emitted when web search completes */
2443
interface ResponseWebSearchCallCompletedEvent {
2444
  type: "response.web_search_call.completed";
2445
  sequence_number: number;
2446
  item_id: string;
2447
  output_index: number;
2448
  results: Array<any>;
2449
}
2450

2451
/**
2452
 * Code interpreter streaming events
2453
 */
2454

2455
/** Emitted when code interpreter starts */
2456
interface ResponseCodeInterpreterCallInProgressEvent {
2457
  type: "response.code_interpreter_call.in_progress";
2458
  sequence_number: number;
2459
  item_id: string;
2460
  output_index: number;
2461
}
2462

2463
/** Emitted when code is being interpreted */
2464
interface ResponseCodeInterpreterCallInterpretingEvent {
2465
  type: "response.code_interpreter_call.interpreting";
2466
  sequence_number: number;
2467
  item_id: string;
2468
  output_index: number;
2469
}
2470

2471
/** Emitted when code interpreter completes */
2472
interface ResponseCodeInterpreterCallCompletedEvent {
2473
  type: "response.code_interpreter_call.completed";
2474
  sequence_number: number;
2475
  item_id: string;
2476
  output_index: number;
2477
}
2478

2479
/** Emitted for each code delta */
2480
interface ResponseCodeInterpreterCallCodeDeltaEvent {
2481
  type: "response.code_interpreter_call_code.delta";
2482
  sequence_number: number;
2483
  item_id: string;
2484
  output_index: number;
2485
  delta: string;
2486
}
2487

2488
/** Emitted when code is complete */
2489
interface ResponseCodeInterpreterCallCodeDoneEvent {
2490
  type: "response.code_interpreter_call_code.done";
2491
  sequence_number: number;
2492
  item_id: string;
2493
  output_index: number;
2494
  code: string;
2495
}
2496

2497
/**
2498
 * Image generation streaming events
2499
 */
2500

2501
/** Emitted when image generation starts */
2502
interface ResponseImageGenCallInProgressEvent {
2503
  type: "response.image_gen_call.in_progress";
2504
  sequence_number: number;
2505
  item_id: string;
2506
  output_index: number;
2507
}
2508

2509
/** Emitted when image is being generated */
2510
interface ResponseImageGenCallGeneratingEvent {
2511
  type: "response.image_gen_call.generating";
2512
  sequence_number: number;
2513
  item_id: string;
2514
  output_index: number;
2515
}
2516

2517
/** Emitted for partial image data */
2518
interface ResponseImageGenCallPartialImageEvent {
2519
  type: "response.image_gen_call.partial_image";
2520
  sequence_number: number;
2521
  item_id: string;
2522
  output_index: number;
2523
  image_data: string;  // Partial Base64 image
2524
}
2525

2526
/** Emitted when image generation completes */
2527
interface ResponseImageGenCallCompletedEvent {
2528
  type: "response.image_gen_call.completed";
2529
  sequence_number: number;
2530
  item_id: string;
2531
  output_index: number;
2532
}
2533

2534
/**
2535
 * Reasoning streaming events (o-series models)
2536
 */
2537

2538
/** Emitted for each reasoning text delta */
2539
interface ResponseReasoningTextDeltaEvent {
2540
  type: "response.reasoning.text.delta";
2541
  sequence_number: number;
2542
  item_id: string;
2543
  output_index: number;
2544
  content_index: number;
2545
  delta: string;
2546
}
2547

2548
/** Emitted when reasoning text is complete */
2549
interface ResponseReasoningTextDoneEvent {
2550
  type: "response.reasoning.text.done";
2551
  sequence_number: number;
2552
  item_id: string;
2553
  output_index: number;
2554
  content_index: number;
2555
  text: string;
2556
}
2557

2558
/** Emitted when reasoning summary part is added */
2559
interface ResponseReasoningSummaryPartAddedEvent {
2560
  type: "response.reasoning.summary_part.added";
2561
  sequence_number: number;
2562
  item_id: string;
2563
  output_index: number;
2564
}
2565

2566
/** Emitted when reasoning summary part is complete */
2567
interface ResponseReasoningSummaryPartDoneEvent {
2568
  type: "response.reasoning.summary_part.done";
2569
  sequence_number: number;
2570
  item_id: string;
2571
  output_index: number;
2572
}
2573

2574
/** Emitted for each reasoning summary text delta */
2575
interface ResponseReasoningSummaryTextDeltaEvent {
2576
  type: "response.reasoning.summary.text.delta";
2577
  sequence_number: number;
2578
  item_id: string;
2579
  output_index: number;
2580
  delta: string;
2581
}
2582

2583
/** Emitted when reasoning summary text is complete */
2584
interface ResponseReasoningSummaryTextDoneEvent {
2585
  type: "response.reasoning.summary.text.done";
2586
  sequence_number: number;
2587
  item_id: string;
2588
  output_index: number;
2589
  text: string;
2590
}
2591

2592
/**
2593
 * Annotation events
2594
 */
2595

2596
/** Emitted when output text annotation is added */
2597
interface ResponseOutputTextAnnotationAddedEvent {
2598
  type: "response.output_text.annotation.added";
2599
  sequence_number: number;
2600
  item_id: string;
2601
  output_index: number;
2602
  content_index: number;
2603
  annotation: ResponseOutputText.Annotation;
2604
}
2605

2606
/**
2607
 * MCP streaming events
2608
 */
2609

2610
/** Emitted when MCP call starts */
2611
interface ResponseMcpCallInProgressEvent {
2612
  type: "response.mcp_call.in_progress";
2613
  sequence_number: number;
2614
  item_id: string;
2615
  output_index: number;
2616
}
2617

2618
/** Emitted for each MCP arguments delta */
2619
interface ResponseMcpCallArgumentsDeltaEvent {
2620
  type: "response.mcp_call_arguments.delta";
2621
  sequence_number: number;
2622
  item_id: string;
2623
  output_index: number;
2624
  delta: string;
2625
}
2626

2627
/** Emitted when MCP arguments are complete */
2628
interface ResponseMcpCallArgumentsDoneEvent {
2629
  type: "response.mcp_call_arguments.done";
2630
  sequence_number: number;
2631
  item_id: string;
2632
  output_index: number;
2633
  arguments: string;
2634
}
2635

2636
/** Emitted when MCP call completes */
2637
interface ResponseMcpCallCompletedEvent {
2638
  type: "response.mcp_call.completed";
2639
  sequence_number: number;
2640
  item_id: string;
2641
  output_index: number;
2642
}
2643

2644
/** Emitted when MCP call fails */
2645
interface ResponseMcpCallFailedEvent {
2646
  type: "response.mcp_call.failed";
2647
  sequence_number: number;
2648
  item_id: string;
2649
  output_index: number;
2650
  error: ResponseError;
2651
}
2652

2653
/** Emitted when MCP list tools starts */
2654
interface ResponseMcpListToolsInProgressEvent {
2655
  type: "response.mcp_list_tools.in_progress";
2656
  sequence_number: number;
2657
  item_id: string;
2658
  output_index: number;
2659
}
2660

2661
/** Emitted when MCP list tools completes */
2662
interface ResponseMcpListToolsCompletedEvent {
2663
  type: "response.mcp_list_tools.completed";
2664
  sequence_number: number;
2665
  item_id: string;
2666
  output_index: number;
2667
}
2668

2669
/** Emitted when MCP list tools fails */
2670
interface ResponseMcpListToolsFailedEvent {
2671
  type: "response.mcp_list_tools.failed";
2672
  sequence_number: number;
2673
  item_id: string;
2674
  output_index: number;
2675
  error: ResponseError;
2676
}
2677
```
2678

2679
## Usage Examples
2680

2681
### Basic Text Response
2682

2683
```typescript
2684
import { OpenAI } from "openai";
2685

2686
const client = new OpenAI();
2687

2688
// Simple question answering
2689
const response = await client.responses.create({
2690
  model: "gpt-4o",
2691
  input: "What is the speed of light?",
2692
});
2693

2694
console.log(response.output_text);
2695
// "The speed of light in a vacuum is approximately 299,792,458 meters per second..."
2696

2697
// With system instructions
2698
const response2 = await client.responses.create({
2699
  model: "gpt-4o",
2700
  instructions: "You are a physics professor explaining concepts to undergraduates.",
2701
  input: "What is quantum entanglement?",
2702
});
2703

2704
// Multi-part input
2705
const response3 = await client.responses.create({
2706
  model: "gpt-4o",
2707
  input: [
2708
    { type: "text", text: "Compare these two approaches:" },
2709
    { type: "text", text: "Approach A: Use recursion" },
2710
    { type: "text", text: "Approach B: Use iteration" },
2711
  ],
2712
});
2713
```
2714

2715
### Streaming Responses
2716

2717
```typescript
2718
// Basic streaming
2719
const stream = await client.responses.create({
2720
  model: "gpt-4o",
2721
  input: "Write a short story about a robot",
2722
  stream: true,
2723
});
2724

2725
for await (const event of stream) {
2726
  if (event.type === "response.text.delta") {
2727
    process.stdout.write(event.delta);
2728
  } else if (event.type === "response.completed") {
2729
    console.log("\n\nTokens used:", event.response.usage?.total_tokens);
2730
  }
2731
}
2732

2733
// Using the stream helper
2734
const stream2 = client.responses.stream({
2735
  model: "gpt-4o",
2736
  input: "Explain TypeScript generics",
2737
});
2738

2739
// Collect full text
2740
let fullText = "";
2741
for await (const event of stream2) {
2742
  if (event.type === "response.text.delta") {
2743
    fullText += event.delta;
2744
  }
2745
}
2746

2747
// Or use helper methods
2748
const finalResponse = await stream2.finalResponse();
2749
console.log(finalResponse.output_text);
2750
```
2751

2752
### Structured Output (JSON)
2753

2754
```typescript
2755
import { zodResponseFormat } from "openai/helpers/zod";
2756
import { z } from "zod";
2757

2758
// Define schema
2759
const RecipeSchema = z.object({
2760
  name: z.string(),
2761
  ingredients: z.array(z.object({
2762
    item: z.string(),
2763
    amount: z.string(),
2764
  })),
2765
  instructions: z.array(z.string()),
2766
  prepTime: z.number(),
2767
  cookTime: z.number(),
2768
});
2769

2770
// Generate structured output
2771
const response = await client.responses.create({
2772
  model: "gpt-4o",
2773
  input: "Give me a recipe for chocolate chip cookies",
2774
  text: {
2775
    format: zodResponseFormat(RecipeSchema, "Recipe"),
2776
  },
2777
});
2778

2779
// Parse output
2780
const recipe = JSON.parse(response.output_text);
2781
console.log(recipe.name); // "Chocolate Chip Cookies"
2782
console.log(recipe.ingredients[0]); // { item: "...", amount: "..." }
2783

2784
// Or use parse for automatic validation
2785
const response2 = await client.responses.parse({
2786
  model: "gpt-4o",
2787
  input: "Generate a recipe for pasta",
2788
  text: {
2789
    format: zodResponseFormat(RecipeSchema, "Recipe"),
2790
  },
2791
});
2792

2793
// Fully typed and validated
2794
const recipe2 = response2.output_parsed;
2795
if (recipe2) {
2796
  console.log(recipe2.cookTime); // Type: number
2797
}
2798
```
2799

2800
### Function Calling
2801

2802
```typescript
2803
// Define functions
2804
const tools = [
2805
  {
2806
    type: "function" as const,
2807
    name: "get_weather",
2808
    description: "Get the current weather in a location",
2809
    parameters: {
2810
      type: "object",
2811
      properties: {
2812
        location: {
2813
          type: "string",
2814
          description: "City and state, e.g., San Francisco, CA",
2815
        },
2816
        unit: {
2817
          type: "string",
2818
          enum: ["celsius", "fahrenheit"],
2819
        },
2820
      },
2821
      required: ["location"],
2822
    },
2823
    strict: true,
2824
  },
2825
];
2826

2827
// First request
2828
const response1 = await client.responses.create({
2829
  model: "gpt-4o",
2830
  input: "What's the weather like in Boston?",
2831
  tools,
2832
});
2833

2834
// Check for tool calls
2835
const toolCall = response1.output.find(
2836
  (item) => item.type === "function_call"
2837
);
2838

2839
if (toolCall && toolCall.type === "function_call") {
2840
  console.log("Function:", toolCall.name);
2841
  console.log("Arguments:", toolCall.arguments);
2842

2843
  // Call your function
2844
  const weatherData = await getWeather(JSON.parse(toolCall.arguments));
2845

2846
  // Send back results
2847
  const response2 = await client.responses.create({
2848
    model: "gpt-4o",
2849
    input: [
2850
      ...response1.output,
2851
      {
2852
        type: "function_call_output",
2853
        call_id: toolCall.call_id,
2854
        output: JSON.stringify(weatherData),
2855
      },
2856
    ],
2857
    tools,
2858
  });
2859

2860
  console.log(response2.output_text);
2861
}
2862

2863
// Or use streaming
2864
const stream = await client.responses.create({
2865
  model: "gpt-4o",
2866
  input: "What's the weather in Paris and London?",
2867
  tools,
2868
  stream: true,
2869
  parallel_tool_calls: true,
2870
});
2871

2872
for await (const event of stream) {
2873
  if (event.type === "response.function_call_arguments.done") {
2874
    console.log("Tool call:", event.name, event.arguments);
2875
  }
2876
}
2877
```
2878

2879
### Computer Use
2880

2881
```typescript
2882
// Set up computer tool
2883
const response = await client.responses.create({
2884
  model: "gpt-4o",
2885
  input: "Click the submit button on the form",
2886
  tools: [
2887
    {
2888
      type: "computer_use_preview",
2889
      display_width: 1920,
2890
      display_height: 1080,
2891
      environment: "browser",
2892
    },
2893
  ],
2894
  stream: true,
2895
});
2896

2897
// Handle computer actions
2898
for await (const event of stream) {
2899
  if (event.type === "response.output_item.added") {
2900
    const item = event.item;
2901
    if (item.type === "computer_call") {
2902
      console.log("Computer action:", item.action);
2903

2904
      // Execute action in your environment
2905
      if (item.action.type === "click") {
2906
        await executeClick(item.action.x, item.action.y);
2907
      } else if (item.action.type === "type") {
2908
        await executeType(item.action.text);
2909
      } else if (item.action.type === "screenshot") {
2910
        const screenshot = await takeScreenshot();
2911

2912
        // Send screenshot back
2913
        await client.responses.create({
2914
          model: "gpt-4o",
2915
          input: [
2916
            ...response.output,
2917
            {
2918
              type: "computer_call_output",
2919
              call_id: item.call_id,
2920
              output: {
2921
                type: "computer_screenshot",
2922
                image_url: screenshot,
2923
              },
2924
            },
2925
          ],
2926
          tools: response.tools,
2927
        });
2928
      }
2929
    }
2930
  }
2931
}
2932
```
2933

2934
### File Search
2935

2936
```typescript
2937
// Upload files to vector store first
2938
const vectorStore = await client.vectorStores.create({
2939
  name: "Product Documentation",
2940
});
2941

2942
await client.vectorStores.files.upload(
2943
  vectorStore.id,
2944
  await toFile(fs.readFileSync("docs.pdf"), "docs.pdf")
2945
);
2946

2947
// Query with file search
2948
const response = await client.responses.create({
2949
  model: "gpt-4o",
2950
  input: "How do I configure SSL certificates?",
2951
  tools: [
2952
    {
2953
      type: "file_search",
2954
      vector_store_ids: [vectorStore.id],
2955
      max_num_results: 5,
2956
      ranking_options: {
2957
        ranker: "auto",
2958
        score_threshold: 0.7,
2959
      },
2960
    },
2961
  ],
2962
});
2963

2964
// Check file search results
2965
const fileSearch = response.output.find(
2966
  (item) => item.type === "file_search_call"
2967
);
2968

2969
if (fileSearch && fileSearch.type === "file_search_call" && fileSearch.results) {
2970
  console.log("Found", fileSearch.results.length, "relevant documents");
2971
  fileSearch.results.forEach((result) => {
2972
    console.log(`- ${result.file_name} (score: ${result.score})`);
2973
  });
2974
}
2975

2976
console.log("\nAnswer:", response.output_text);
2977
```
2978

2979
### Web Search
2980

2981
```typescript
2982
// Simple web search
2983
const response = await client.responses.create({
2984
  model: "gpt-4o",
2985
  input: "What are the latest developments in quantum computing?",
2986
  tools: [{ type: "web_search" }],
2987
});
2988

2989
// Check web search results
2990
const webSearch = response.output.find(
2991
  (item) => item.type === "web_search_call"
2992
);
2993

2994
if (webSearch && webSearch.type === "web_search_call" && webSearch.results) {
2995
  console.log("Search query:", webSearch.query);
2996
  console.log("\nResults:");
2997
  webSearch.results.forEach((result) => {
2998
    console.log(`- ${result.title}`);
2999
    console.log(`  ${result.url}`);
3000
    console.log(`  ${result.snippet}\n`);
3001
  });
3002
}
3003

3004
console.log("\nSummary:", response.output_text);
3005

3006
// Streaming web search
3007
const stream = await client.responses.create({
3008
  model: "gpt-4o",
3009
  input: "Compare the latest iPhone and Samsung flagship phones",
3010
  tools: [{ type: "web_search" }],
3011
  stream: true,
3012
});
3013

3014
for await (const event of stream) {
3015
  if (event.type === "response.web_search_call.searching") {
3016
    console.log("Searching:", event.query);
3017
  } else if (event.type === "response.web_search_call.completed") {
3018
    console.log("Search completed with", event.results.length, "results");
3019
  } else if (event.type === "response.text.delta") {
3020
    process.stdout.write(event.delta);
3021
  }
3022
}
3023
```
3024

3025
### Multi-Turn Conversations
3026

3027
```typescript
3028
// Method 1: Using previous_response_id
3029
const response1 = await client.responses.create({
3030
  model: "gpt-4o",
3031
  input: "My favorite color is blue",
3032
});
3033

3034
const response2 = await client.responses.create({
3035
  model: "gpt-4o",
3036
  input: "What's my favorite color?",
3037
  previous_response_id: response1.id,
3038
});
3039

3040
console.log(response2.output_text); // "Your favorite color is blue."
3041

3042
// Method 2: Using conversation
3043
const conversation = await client.conversations.create({
3044
  metadata: { topic: "preferences" },
3045
});
3046

3047
const response3 = await client.responses.create({
3048
  model: "gpt-4o",
3049
  input: "I love pizza",
3050
  conversation: conversation.id,
3051
});
3052

3053
const response4 = await client.responses.create({
3054
  model: "gpt-4o",
3055
  input: "What food do I love?",
3056
  conversation: conversation.id,
3057
});
3058

3059
// Method 3: Manual input management
3060
const messages = [];
3061

3062
messages.push({
3063
  type: "message" as const,
3064
  role: "user" as const,
3065
  content: "I'm planning a vacation",
3066
});
3067

3068
const r1 = await client.responses.create({
3069
  model: "gpt-4o",
3070
  input: messages,
3071
});
3072

3073
messages.push(...r1.output);
3074
messages.push({
3075
  type: "message" as const,
3076
  role: "user" as const,
3077
  content: "I want to go somewhere warm",
3078
});
3079

3080
const r2 = await client.responses.create({
3081
  model: "gpt-4o",
3082
  input: messages,
3083
});
3084
```
3085

3086
### Reasoning Models (o-series)
3087

3088
```typescript
3089
// Basic reasoning
3090
const response = await client.responses.create({
3091
  model: "o3-mini",
3092
  input: "Solve: If a train travels 120 km in 2 hours, then stops for 30 minutes, then travels another 180 km in 3 hours, what is the average speed for the entire journey?",
3093
  reasoning: {
3094
    effort: "high",
3095
  },
3096
});
3097

3098
// Check reasoning content
3099
const reasoning = response.output.find(
3100
  (item) => item.type === "reasoning"
3101
);
3102

3103
if (reasoning && reasoning.type === "reasoning") {
3104
  console.log("Reasoning steps:");
3105
  reasoning.content.forEach((part) => {
3106
    if (part.type === "reasoning_text") {
3107
      console.log("-", part.reasoning_text);
3108
    }
3109
  });
3110

3111
  if (reasoning.summary) {
3112
    console.log("\nSummary:", reasoning.summary.reasoning_summary);
3113
  }
3114
}
3115

3116
console.log("\nFinal answer:", response.output_text);
3117

3118
// Streaming reasoning
3119
const stream = await client.responses.create({
3120
  model: "o1",
3121
  input: "Prove that the square root of 2 is irrational",
3122
  reasoning: { effort: "medium" },
3123
  stream: true,
3124
});
3125

3126
console.log("Reasoning process:");
3127
for await (const event of stream) {
3128
  if (event.type === "response.reasoning.text.delta") {
3129
    process.stdout.write(event.delta);
3130
  } else if (event.type === "response.reasoning.summary.text.done") {
3131
    console.log("\n\nReasoning summary:", event.text);
3132
  } else if (event.type === "response.text.delta") {
3133
    process.stdout.write(event.delta);
3134
  }
3135
}
3136
```
3137

3138
### Background Responses
3139

3140
```typescript
3141
// Start a long-running response in background
3142
const response = await client.responses.create({
3143
  model: "gpt-4o",
3144
  input: "Write a comprehensive guide to TypeScript, covering all major features with examples",
3145
  max_output_tokens: 10000,
3146
  background: true,
3147
});
3148

3149
console.log("Response ID:", response.id);
3150
console.log("Status:", response.status); // 'queued' or 'in_progress'
3151

3152
// Poll for completion
3153
async function waitForResponse(responseId: string) {
3154
  while (true) {
3155
    const current = await client.responses.retrieve(responseId);
3156

3157
    if (current.status === "completed") {
3158
      return current;
3159
    } else if (current.status === "failed") {
3160
      throw new Error(`Response failed: ${current.error?.message}`);
3161
    }
3162

3163
    console.log("Status:", current.status);
3164
    await new Promise((resolve) => setTimeout(resolve, 2000));
3165
  }
3166
}
3167

3168
const completed = await waitForResponse(response.id);
3169
console.log("Completed! Output length:", completed.output_text.length);
3170

3171
// Or cancel if needed
3172
await client.responses.cancel(response.id);
3173
```
3174

3175
### Image Input
3176

3177
```typescript
3178
// With image URL
3179
const response = await client.responses.create({
3180
  model: "gpt-4o",
3181
  input: [
3182
    { type: "text", text: "What objects are in this image?" },
3183
    {
3184
      type: "image",
3185
      image_url: {
3186
        url: "https://example.com/image.jpg",
3187
        detail: "high",
3188
      },
3189
    },
3190
  ],
3191
});
3192

3193
// With uploaded file
3194
const file = await client.files.create({
3195
  file: await toFile(fs.readFileSync("photo.jpg"), "photo.jpg"),
3196
  purpose: "vision",
3197
});
3198

3199
const response2 = await client.responses.create({
3200
  model: "gpt-4o",
3201
  input: [
3202
    { type: "text", text: "Describe this image in detail" },
3203
    { type: "image", file_id: file.id },
3204
  ],
3205
});
3206

3207
// Multiple images
3208
const response3 = await client.responses.create({
3209
  model: "gpt-4o",
3210
  input: [
3211
    { type: "text", text: "Compare these two images" },
3212
    { type: "image", image_url: { url: "https://example.com/image1.jpg" } },
3213
    { type: "image", image_url: { url: "https://example.com/image2.jpg" } },
3214
  ],
3215
});
3216
```
3217

3218
### Custom Tools
3219

3220
```typescript
3221
// Define custom tool
3222
const response = await client.responses.create({
3223
  model: "gpt-4o",
3224
  input: "Process this data: [1, 2, 3, 4, 5]",
3225
  tools: [
3226
    {
3227
      type: "custom",
3228
      name: "data_processor",
3229
      description: "Processes numerical data with custom format",
3230
      format: {
3231
        type: "text_grammar",
3232
        text_grammar: {
3233
          grammar: `
3234
            root ::= "PROCESS" ws data ws "END"
3235
            data ::= "[" ws number (ws "," ws number)* ws "]"
3236
            number ::= [0-9]+
3237
            ws ::= [ \t\n]*
3238
          `,
3239
          root_rule: "root",
3240
        },
3241
      },
3242
    },
3243
  ],
3244
  stream: true,
3245
});
3246

3247
// Handle custom tool calls
3248
for await (const event of stream) {
3249
  if (event.type === "response.custom_call_input.done") {
3250
    console.log("Custom tool input:", event.input);
3251

3252
    // Process with your custom logic
3253
    const result = processData(event.input);
3254

3255
    // Send output back
3256
    const response2 = await client.responses.create({
3257
      model: "gpt-4o",
3258
      input: [
3259
        ...response.output,
3260
        {
3261
          type: "custom_call_output",
3262
          call_id: event.call_id,
3263
          output: result,
3264
        },
3265
      ],
3266
      tools: response.tools,
3267
    });
3268
  }
3269
}
3270
```
3271

3272
### Token Counting
3273

3274
```typescript
3275
// Count tokens before sending
3276
const count = await client.responses.inputTokens.count({
3277
  model: "gpt-4o",
3278
  input: "This is my input text",
3279
  instructions: "You are a helpful assistant",
3280
  tools: [
3281
    {
3282
      type: "function",
3283
      name: "my_function",
3284
      parameters: { type: "object", properties: {} },
3285
      strict: true,
3286
    },
3287
  ],
3288
});
3289

3290
console.log("Input tokens:", count.input_tokens);
3291

3292
// Estimate cost
3293
const costPer1kTokens = 0.03; // gpt-4o pricing
3294
const estimatedCost = (count.input_tokens / 1000) * costPer1kTokens;
3295
console.log("Estimated input cost: $" + estimatedCost.toFixed(4));
3296

3297
// Check if input fits in context window
3298
const maxContextTokens = 128000; // gpt-4o context window
3299
if (count.input_tokens > maxContextTokens) {
3300
  console.log("Input exceeds context window!");
3301
}
3302
```
3303

3304
### Error Handling
3305

3306
```typescript
3307
try {
3308
  const response = await client.responses.create({
3309
    model: "gpt-4o",
3310
    input: "Hello",
3311
  });
3312
} catch (error) {
3313
  if (error instanceof OpenAI.APIError) {
3314
    console.error("API Error:", error.message);
3315
    console.error("Status:", error.status);
3316
    console.error("Code:", error.code);
3317
    console.error("Type:", error.type);
3318
  } else if (error instanceof OpenAI.RateLimitError) {
3319
    console.error("Rate limit exceeded");
3320
  } else if (error instanceof OpenAI.AuthenticationError) {
3321
    console.error("Authentication failed");
3322
  } else {
3323
    console.error("Unexpected error:", error);
3324
  }
3325
}
3326

3327
// Handle streaming errors
3328
const stream = await client.responses.create({
3329
  model: "gpt-4o",
3330
  input: "Test",
3331
  stream: true,
3332
});
3333

3334
try {
3335
  for await (const event of stream) {
3336
    if (event.type === "error") {
3337
      console.error("Stream error:", event.error);
3338
    } else if (event.type === "response.failed") {
3339
      console.error("Response failed:", event.error);
3340
    }
3341
  }
3342
} catch (error) {
3343
  console.error("Stream exception:", error);
3344
}
3345

3346
// Check response for errors
3347
const response = await client.responses.create({
3348
  model: "gpt-4o",
3349
  input: "...",
3350
});
3351

3352
if (response.status === "failed" && response.error) {
3353
  console.error("Response error:", response.error.message);
3354
}
3355

3356
if (response.status === "incomplete" && response.incomplete_details) {
3357
  console.warn("Response incomplete:", response.incomplete_details.reason);
3358
}
3359
```
3360

3361
## Best Practices
3362

3363
### 1. Use Streaming for Long Responses
3364

3365
Streaming provides better user experience and allows handling partial results:
3366

3367
```typescript
3368
const stream = client.responses.stream({
3369
  model: "gpt-4o",
3370
  input: "Write a long article...",
3371
});
3372

3373
for await (const event of stream) {
3374
  if (event.type === "response.text.delta") {
3375
    // Display text as it arrives
3376
    displayToUser(event.delta);
3377
  }
3378
}
3379
```
3380

3381
### 2. Handle Tool Calls Properly
3382

3383
Always check tool call status and handle errors:
3384

3385
```typescript
3386
const response = await client.responses.create({
3387
  model: "gpt-4o",
3388
  input: "...",
3389
  tools: myTools,
3390
});
3391

3392
for (const item of response.output) {
3393
  if (item.type === "function_call" && item.status === "completed") {
3394
    try {
3395
      const result = await executeFunction(item.name, item.arguments);
3396
      // Send result back to model
3397
    } catch (error) {
3398
      // Send error back
3399
      const errorOutput = {
3400
        type: "function_call_output" as const,
3401
        call_id: item.call_id,
3402
        output: JSON.stringify({ error: error.message }),
3403
      };
3404
    }
3405
  }
3406
}
3407
```
3408

3409
### 3. Use Structured Outputs for Predictable Data
3410

3411
Structured outputs ensure the model returns valid JSON:
3412

3413
```typescript
3414
const response = await client.responses.parse({
3415
  model: "gpt-4o",
3416
  input: "Extract data...",
3417
  text: {
3418
    format: zodResponseFormat(MySchema, "ExtractedData"),
3419
  },
3420
});
3421

3422
// output_parsed is guaranteed to match schema or be null
3423
if (response.output_parsed) {
3424
  // Safely use typed data
3425
  processData(response.output_parsed);
3426
}
3427
```
3428

3429
### 4. Manage Conversation State
3430

3431
Choose the right approach for your use case:
3432

3433
```typescript
3434
// Simple multi-turn: use previous_response_id
3435
const r1 = await client.responses.create({ input: "First message" });
3436
const r2 = await client.responses.create({
3437
  input: "Follow-up",
3438
  previous_response_id: r1.id,
3439
});
3440

3441
// Complex multi-turn: use conversations
3442
const conv = await client.conversations.create();
3443
await client.responses.create({
3444
  input: "Message 1",
3445
  conversation: conv.id,
3446
});
3447
await client.responses.create({
3448
  input: "Message 2",
3449
  conversation: conv.id,
3450
});
3451

3452
// Full control: manual input array
3453
const inputs = [];
3454
inputs.push({ type: "message", role: "user", content: "Hi" });
3455
const r = await client.responses.create({ input: inputs });
3456
inputs.push(...r.output);
3457
```
3458

3459
### 5. Monitor Token Usage
3460

3461
Track usage to manage costs:
3462

3463
```typescript
3464
const response = await client.responses.create({
3465
  model: "gpt-4o",
3466
  input: "...",
3467
});
3468

3469
console.log("Tokens used:", response.usage);
3470
// {
3471
//   input_tokens: 50,
3472
//   output_tokens: 200,
3473
//   total_tokens: 250,
3474
//   output_tokens_details: {
3475
//     text_tokens: 200,
3476
//     reasoning_tokens: 0
3477
//   }
3478
// }
3479
```
3480

3481
### 6. Set Appropriate Timeouts
3482

3483
Use timeouts for long-running requests:
3484

3485
```typescript
3486
const response = await client.responses.create(
3487
  {
3488
    model: "gpt-4o",
3489
    input: "Complex task...",
3490
  },
3491
  {
3492
    timeout: 120000, // 2 minutes
3493
  }
3494
);
3495
```
3496

3497
### 7. Use Metadata for Tracking
3498

3499
Add metadata for debugging and analytics:
3500

3501
```typescript
3502
const response = await client.responses.create({
3503
  model: "gpt-4o",
3504
  input: "...",
3505
  metadata: {
3506
    user_id: "user_123",
3507
    session_id: "sess_456",
3508
    request_type: "chat",
3509
    version: "1.0",
3510
  },
3511
});
3512
```
3513

3514
### 8. Implement Proper Error Handling
3515

3516
Handle different error types appropriately:
3517

3518
```typescript
3519
async function safeCreate(params: ResponseCreateParams) {
3520
  try {
3521
    return await client.responses.create(params);
3522
  } catch (error) {
3523
    if (error instanceof OpenAI.RateLimitError) {
3524
      // Wait and retry
3525
      await wait(60000);
3526
      return await client.responses.create(params);
3527
    } else if (error instanceof OpenAI.APIConnectionError) {
3528
      // Network issue, retry with exponential backoff
3529
      return await retryWithBackoff(() => client.responses.create(params));
3530
    } else {
3531
      // Other errors, log and rethrow
3532
      logger.error("Response creation failed", error);
3533
      throw error;
3534
    }
3535
  }
3536
}
3537
```
3538

3539
## Migration from Chat Completions API
3540

3541
The Responses API replaces the Chat Completions API with a more powerful and flexible interface. Here's how to migrate:
3542

3543
### Basic Message
3544

3545
**Chat Completions:**
3546
```typescript
3547
const completion = await client.chat.completions.create({
3548
  model: "gpt-4o",
3549
  messages: [{ role: "user", content: "Hello" }],
3550
});
3551

3552
console.log(completion.choices[0].message.content);
3553
```
3554

3555
**Responses API:**
3556
```typescript
3557
const response = await client.responses.create({
3558
  model: "gpt-4o",
3559
  input: "Hello",
3560
});
3561

3562
console.log(response.output_text);
3563
```
3564

3565
### System Message
3566

3567
**Chat Completions:**
3568
```typescript
3569
const completion = await client.chat.completions.create({
3570
  model: "gpt-4o",
3571
  messages: [
3572
    { role: "system", content: "You are helpful" },
3573
    { role: "user", content: "Hello" },
3574
  ],
3575
});
3576
```
3577

3578
**Responses API:**
3579
```typescript
3580
const response = await client.responses.create({
3581
  model: "gpt-4o",
3582
  instructions: "You are helpful",
3583
  input: "Hello",
3584
});
3585
```
3586

3587
### Multi-Turn Conversation
3588

3589
**Chat Completions:**
3590
```typescript
3591
const messages = [
3592
  { role: "user", content: "My name is Alice" },
3593
  { role: "assistant", content: "Hello Alice!" },
3594
  { role: "user", content: "What's my name?" },
3595
];
3596

3597
const completion = await client.chat.completions.create({
3598
  model: "gpt-4o",
3599
  messages,
3600
});
3601
```
3602

3603
**Responses API:**
3604
```typescript
3605
const response1 = await client.responses.create({
3606
  model: "gpt-4o",
3607
  input: "My name is Alice",
3608
});
3609

3610
const response2 = await client.responses.create({
3611
  model: "gpt-4o",
3612
  input: "What's my name?",
3613
  previous_response_id: response1.id,
3614
});
3615
```
3616

3617
### Function Calling
3618

3619
**Chat Completions:**
3620
```typescript
3621
const completion = await client.chat.completions.create({
3622
  model: "gpt-4o",
3623
  messages: [{ role: "user", content: "What's the weather?" }],
3624
  tools: [
3625
    {
3626
      type: "function",
3627
      function: {
3628
        name: "get_weather",
3629
        parameters: { /* ... */ },
3630
      },
3631
    },
3632
  ],
3633
});
3634

3635
const toolCall = completion.choices[0].message.tool_calls?.[0];
3636
```
3637

3638
**Responses API:**
3639
```typescript
3640
const response = await client.responses.create({
3641
  model: "gpt-4o",
3642
  input: "What's the weather?",
3643
  tools: [
3644
    {
3645
      type: "function",
3646
      name: "get_weather",
3647
      parameters: { /* ... */ },
3648
      strict: true,
3649
    },
3650
  ],
3651
});
3652

3653
const toolCall = response.output.find(item => item.type === "function_call");
3654
```
3655

3656
### Streaming
3657

3658
**Chat Completions:**
3659
```typescript
3660
const stream = await client.chat.completions.create({
3661
  model: "gpt-4o",
3662
  messages: [{ role: "user", content: "Hello" }],
3663
  stream: true,
3664
});
3665

3666
for await (const chunk of stream) {
3667
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
3668
}
3669
```
3670

3671
**Responses API:**
3672
```typescript
3673
const stream = await client.responses.create({
3674
  model: "gpt-4o",
3675
  input: "Hello",
3676
  stream: true,
3677
});
3678

3679
for await (const event of stream) {
3680
  if (event.type === "response.text.delta") {
3681
    process.stdout.write(event.delta);
3682
  }
3683
}
3684
```
3685

3686
## Common Issues and Solutions
3687

3688
### Issue: Response is incomplete
3689

3690
**Problem:** Response status is "incomplete" with `incomplete_details.reason`.
3691

3692
**Solutions:**
3693
```typescript
3694
// Increase max tokens
3695
const response = await client.responses.create({
3696
  model: "gpt-4o",
3697
  input: "...",
3698
  max_output_tokens: 4096, // Increase limit
3699
});
3700

3701
// Or use truncation
3702
const response2 = await client.responses.create({
3703
  model: "gpt-4o",
3704
  input: longInput,
3705
  truncation: "auto", // Auto-truncate input if needed
3706
});
3707
```
3708

3709
### Issue: Tool calls not working
3710

3711
**Problem:** Model doesn't call tools or calls wrong tool.
3712

3713
**Solutions:**
3714
```typescript
3715
// Be more specific in tool descriptions
3716
const tools = [
3717
  {
3718
    type: "function",
3719
    name: "get_weather",
3720
    description: "Get current weather. Use this when user asks about weather conditions, temperature, or forecast.",
3721
    parameters: { /* ... */ },
3722
    strict: true,
3723
  },
3724
];
3725

3726
// Force tool use
3727
const response = await client.responses.create({
3728
  model: "gpt-4o",
3729
  input: "What's the weather?",
3730
  tools,
3731
  tool_choice: "required", // Must use a tool
3732
});
3733

3734
// Or specify exact tool
3735
const response2 = await client.responses.create({
3736
  model: "gpt-4o",
3737
  input: "...",
3738
  tools,
3739
  tool_choice: {
3740
    type: "function",
3741
    function: { name: "get_weather" },
3742
  },
3743
});
3744
```
3745

3746
### Issue: Token count too high
3747

3748
**Problem:** Input exceeds model's context window.
3749

3750
**Solutions:**
3751
```typescript
3752
// Count tokens first
3753
const count = await client.responses.inputTokens.count({
3754
  model: "gpt-4o",
3755
  input: largeInput,
3756
});
3757

3758
if (count.input_tokens > 128000) {
3759
  // Truncate or summarize input
3760
  const summarized = await summarizeInput(largeInput);
3761

3762
  // Or use auto-truncation
3763
  const response = await client.responses.create({
3764
    model: "gpt-4o",
3765
    input: largeInput,
3766
    truncation: "auto",
3767
  });
3768
}
3769
```
3770

3771
### Issue: Streaming stops unexpectedly
3772

3773
**Problem:** Stream ends without completion event.
3774

3775
**Solutions:**
3776
```typescript
3777
// Implement error handling and reconnection
3778
async function streamWithRetry(params: ResponseCreateParams) {
3779
  let retries = 0;
3780
  const maxRetries = 3;
3781

3782
  while (retries < maxRetries) {
3783
    try {
3784
      const stream = await client.responses.create({
3785
        ...params,
3786
        stream: true,
3787
      });
3788

3789
      for await (const event of stream) {
3790
        if (event.type === "response.completed") {
3791
          return event.response;
3792
        } else if (event.type === "error") {
3793
          throw new Error(event.error.message);
3794
        }
3795
        // Process event
3796
      }
3797
    } catch (error) {
3798
      retries++;
3799
      if (retries >= maxRetries) throw error;
3800
      await wait(1000 * retries); // Exponential backoff
3801
    }
3802
  }
3803
}
3804
```
3805

3806
---
3807

3808
## Related Resources
3809

3810
- [OpenAI Platform Documentation](https://platform.openai.com/docs)
3811
- [Responses API Guide](https://platform.openai.com/docs/guides/responses)
3812
- [Function Calling Guide](https://platform.openai.com/docs/guides/function-calling)
3813
- [Structured Outputs Guide](https://platform.openai.com/docs/guides/structured-outputs)
3814
- [Tool Use Guides](https://platform.openai.com/docs/guides/tools)
3815