Reference 2026-06-10 15:48 UTC to 2026-06-12 00:01 UTC

1## Create speech

2 

3`$ openai audio:speech create`

4 

5**post** `/audio/speech`

6 

7Generates audio from the input text.

8 

9Returns the audio file content, or a stream of audio events.

10 

11### Parameters

12 

13- `--input: string`

14 

15 The text to generate audio for. The maximum length is 4096 characters.

16 

17- `--model: string or SpeechModel`

18 

19 One of the available [TTS models](https://platform.openai.com/docs/models#tts): `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`, or `gpt-4o-mini-tts-2025-12-15`.

20 

21- `--voice: string or "alloy" or "ash" or "ballad" or 7 more or object { id }`

22 

23 The voice to use when generating the audio. Supported built-in voices are `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage`, `shimmer`, `verse`, `marin`, and `cedar`. You may also provide a custom voice object with an `id`, for example `{ "id": "voice_1234" }`. Previews of the voices are available in the [Text to speech guide](https://platform.openai.com/docs/guides/text-to-speech#voice-options).

24 

25- `--instructions: optional string`

26 

27 Control the voice of your generated audio with additional instructions. Does not work with `tts-1` or `tts-1-hd`.

28 

29- `--response-format: optional "mp3" or "opus" or "aac" or 3 more`

30 

31 The format to audio in. Supported formats are `mp3`, `opus`, `aac`, `flac`, `wav`, and `pcm`.

32 

33- `--speed: optional number`

34 

35 The speed of the generated audio. Select a value from `0.25` to `4.0`. `1.0` is the default.

36 

37- `--stream-format: optional "sse" or "audio"`

38 

39 The format to stream the audio in. Supported formats are `sse` and `audio`. `sse` is not supported for `tts-1` or `tts-1-hd`.

40 

41### Returns

42 

43- `unnamed_schema_2: file path`

44 

45### Example

46 

47```cli

48openai audio:speech create \

49 --api-key 'My API Key' \

50 --input input \

51 --model tts-1 \

52 --voice alloy

53```

1## Create client secret

2 

3`$ openai realtime:client-secrets create`

4 

5**post** `/realtime/client_secrets`

6 

7Create a Realtime client secret with an associated session configuration.

8 

9Client secrets are short-lived tokens that can be passed to a client app,

10such as a web frontend or mobile client, which grants access to the Realtime API without

11leaking your main API key. You can configure a custom TTL for each client secret.

12 

13You can also attach session configuration options to the client secret, which will be

14applied to any sessions created using that client secret, but these can also be overridden

15by the client connection.

16 

17[Learn more about authentication with client secrets over WebRTC](https://platform.openai.com/docs/guides/realtime-webrtc).

18 

19Returns the created client secret and the effective session object. The client secret is a string that looks like `ek_1234`.

20 

21### Parameters

22 

23- `--expires-after: optional object { anchor, seconds }`

24 

25 Configuration for the client secret expiration. Expiration refers to the time after which

26 a client secret will no longer be valid for creating sessions. The session itself may

27 continue after that time once started. A secret can be used to create multiple sessions

28 until it expires.

29 

30- `--session: optional RealtimeSessionCreateRequest or RealtimeTranscriptionSessionCreateRequest`

31 

32 Session configuration to use for the client secret. Choose either a realtime

33 session or a transcription session.

34 

35### Returns

36 

37- `ClientSecretNewResponse: object { expires_at, session, value }`

38 

39 Response from creating a session and client secret for the Realtime API.

40 

41 - `expires_at: number`

42 

43 Expiration timestamp for the client secret, in seconds since epoch.

44 

45 - `session: RealtimeSessionCreateResponse or RealtimeTranscriptionSessionCreateResponse`

46 

47 The session configuration for either a realtime or transcription session.

48 

49 - `realtime_session_create_response: object { id, object, type, 13 more }`

50 

51 A Realtime session configuration object.

52 

53 - `id: string`

54 

55 Unique identifier for the session that looks like `sess_1234567890abcdef`.

56 

57 - `object: "realtime.session"`

58 

59 The object type. Always `realtime.session`.

60 

61 - `type: "realtime"`

62 

63 The type of session to create. Always `realtime` for the Realtime API.

64 

65 - `audio: optional object { input, output }`

66 

67 Configuration for input and output audio.

68 

69 - `input: optional object { format, noise_reduction, transcription, turn_detection }`

70 

71 - `format: optional object { rate, type } or object { type } or object { type }`

72 

73 The format of the input audio.

74 

75 - `audio/pcm: object { rate, type }`

76 

77 The PCM audio format. Only a 24kHz sample rate is supported.

78 

79 - `rate: optional 24000`

80 

81 The sample rate of the audio. Always `24000`.

82 

83 - `24000`

84 

85 - `type: optional "audio/pcm"`

86 

87 The audio format. Always `audio/pcm`.

88 

89 - `"audio/pcm"`

90 

91 - `audio/pcmu: object { type }`

92 

93 The G.711 μ-law format.

94 

95 - `type: optional "audio/pcmu"`

96 

97 The audio format. Always `audio/pcmu`.

98 

99 - `"audio/pcmu"`

100 

101 - `audio/pcma: object { type }`

102 

103 The G.711 A-law format.

104 

105 - `type: optional "audio/pcma"`

106 

107 The audio format. Always `audio/pcma`.

108 

109 - `"audio/pcma"`

110 

111 - `noise_reduction: optional object { type }`

112 

113 Configuration for input audio noise reduction. This can be set to `null` to turn off.

114 Noise reduction filters audio added to the input audio buffer before it is sent to VAD and the model.

115 Filtering the audio can improve VAD and turn detection accuracy (reducing false positives) and model performance by improving perception of the input audio.

116 

117 - `type: optional "near_field" or "far_field"`

118 

119 Type of noise reduction. `near_field` is for close-talking microphones such as headphones, `far_field` is for far-field microphones such as laptop or conference room microphones.

120 

121 - `"near_field"`

122 

123 - `"far_field"`

124 

125 - `transcription: optional object { delay, language, model, prompt }`

126 

127 - `delay: optional "minimal" or "low" or "medium" or 2 more`

128 

129 Controls how long the model waits before emitting transcription text.

130 Higher values can improve transcription accuracy at the cost of latency.

131 Only supported with `gpt-realtime-whisper` in GA Realtime sessions.

132 

133 - `"minimal"`

134 

135 - `"low"`

136 

137 - `"medium"`

138 

139 - `"high"`

140 

141 - `"xhigh"`

142 

143 - `language: optional string`

144 

145 The language of the input audio. Supplying the input language in

146 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format

147 will improve accuracy and latency.

148 

149 - `model: optional string or "whisper-1" or "gpt-4o-mini-transcribe" or "gpt-4o-mini-transcribe-2025-12-15" or 3 more`

150 

151 The model to use for transcription. Current options are `whisper-1`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`, and `gpt-realtime-whisper`. Use `gpt-4o-transcribe-diarize` when you need diarization with speaker labels.

152 

153 - `"whisper-1"`

154 

155 - `"gpt-4o-mini-transcribe"`

156 

157 - `"gpt-4o-mini-transcribe-2025-12-15"`

158 

159 - `"gpt-4o-transcribe"`

160 

161 - `"gpt-4o-transcribe-diarize"`

162 

163 - `"gpt-realtime-whisper"`

164 

165 - `prompt: optional string`

166 

167 An optional text to guide the model's style or continue a previous audio

168 segment.

169 For `whisper-1`, the [prompt is a list of keywords](https://platform.openai.com/docs/guides/speech-to-text#prompting).

170 For `gpt-4o-transcribe` models (excluding `gpt-4o-transcribe-diarize`), the prompt is a free text string, for example "expect words related to technology".

171 Prompt is not supported with `gpt-realtime-whisper` in GA Realtime sessions.

172 

173 - `turn_detection: optional object { type, create_response, idle_timeout_ms, 4 more } or object { type, create_response, eagerness, interrupt_response }`

174 

175 Configuration for turn detection, ether Server VAD or Semantic VAD. This can be set to `null` to turn off, in which case the client must manually trigger model response.

176 

177 Server VAD means that the model will detect the start and end of speech based on audio volume and respond at the end of user speech.

178 

179 Semantic VAD is more advanced and uses a turn detection model (in conjunction with VAD) to semantically estimate whether the user has finished speaking, then dynamically sets a timeout based on this probability. For example, if user audio trails off with "uhhm", the model will score a low probability of turn end and wait longer for the user to continue speaking. This can be useful for more natural conversations, but may have a higher latency.

180 

181 For `gpt-realtime-whisper` transcription sessions, turn detection must be

182 set to `null`; VAD is not supported.

183 

184 - `server_vad: object { type, create_response, idle_timeout_ms, 4 more }`

185 

186 Server-side voice activity detection (VAD) which flips on when user speech is detected and off after a period of silence.

187 

188 - `type: "server_vad"`

189 

190 Type of turn detection, `server_vad` to turn on simple Server VAD.

191 

192 - `create_response: optional boolean`

193 

194 Whether or not to automatically generate a response when a VAD stop event occurs. If `interrupt_response` is set to `false` this may fail to create a response if the model is already responding.

195 

196 If both `create_response` and `interrupt_response` are set to `false`, the model will never respond automatically but VAD events will still be emitted.

197 

198 - `idle_timeout_ms: optional number`

199 

200 Optional timeout after which a model response will be triggered automatically. This is

201 useful for situations in which a long pause from the user is unexpected, such as a phone

202 call. The model will effectively prompt the user to continue the conversation based

203 on the current context.

204 

205 The timeout value will be applied after the last model response's audio has finished playing,

206 i.e. it's set to the `response.done` time plus audio playback duration.

207 

208 An `input_audio_buffer.timeout_triggered` event (plus events

209 associated with the Response) will be emitted when the timeout is reached.

210 Idle timeout is currently only supported for `server_vad` mode.

211 

212 - `interrupt_response: optional boolean`

213 

214 Whether or not to automatically interrupt (cancel) any ongoing response with output to the default

215 conversation (i.e. `conversation` of `auto`) when a VAD start event occurs. If `true` then the response will be cancelled, otherwise it will continue until complete.

216 

217 If both `create_response` and `interrupt_response` are set to `false`, the model will never respond automatically but VAD events will still be emitted.

218 

219 - `prefix_padding_ms: optional number`

220 

221 Used only for `server_vad` mode. Amount of audio to include before the VAD detected speech (in

222 milliseconds). Defaults to 300ms.

223 

224 - `silence_duration_ms: optional number`

225 

226 Used only for `server_vad` mode. Duration of silence to detect speech stop (in milliseconds). Defaults

227 to 500ms. With shorter values the model will respond more quickly,

228 but may jump in on short pauses from the user.

229 

230 - `threshold: optional number`

231 

232 Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A

233 higher threshold will require louder audio to activate the model, and

234 thus might perform better in noisy environments.

235 

236 - `semantic_vad: object { type, create_response, eagerness, interrupt_response }`

237 

238 Server-side semantic turn detection which uses a model to determine when the user has finished speaking.

239 

240 - `type: "semantic_vad"`

241 

242 Type of turn detection, `semantic_vad` to turn on Semantic VAD.

243 

244 - `create_response: optional boolean`

245 

246 Whether or not to automatically generate a response when a VAD stop event occurs.

247 

248 - `eagerness: optional "low" or "medium" or "high" or "auto"`

249 

250 Used only for `semantic_vad` mode. The eagerness of the model to respond. `low` will wait longer for the user to continue speaking, `high` will respond more quickly. `auto` is the default and is equivalent to `medium`. `low`, `medium`, and `high` have max timeouts of 8s, 4s, and 2s respectively.

251 

252 - `"low"`

253 

254 - `"medium"`

255 

256 - `"high"`

257 

258 - `"auto"`

259 

260 - `interrupt_response: optional boolean`

261 

262 Whether or not to automatically interrupt any ongoing response with output to the default

263 conversation (i.e. `conversation` of `auto`) when a VAD start event occurs.

264 

265 - `output: optional object { format, speed, voice }`

266 

267 - `format: optional object { rate, type } or object { type } or object { type }`

268 

269 The format of the output audio.

270 

271 - `audio/pcm: object { rate, type }`

272 

273 The PCM audio format. Only a 24kHz sample rate is supported.

274 

275 - `audio/pcmu: object { type }`

276 

277 The G.711 μ-law format.

278 

279 - `audio/pcma: object { type }`

280 

281 The G.711 A-law format.

282 

283 - `speed: optional number`

284 

285 The speed of the model's spoken response as a multiple of the original speed.

286 1.0 is the default speed. 0.25 is the minimum speed. 1.5 is the maximum speed. This value can only be changed in between model turns, not while a response is in progress.

287 

288 This parameter is a post-processing adjustment to the audio after it is generated, it's

289 also possible to prompt the model to speak faster or slower.

290 

291 - `voice: optional string or "alloy" or "ash" or "ballad" or 7 more`

292 

293 The voice the model uses to respond. Voice cannot be changed during the

294 session once the model has responded with audio at least once. Current

295 voice options are `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`,

296 `shimmer`, `verse`, `marin`, and `cedar`. We recommend `marin` and `cedar` for

297 best quality.

298 

299 - `"alloy"`

300 

301 - `"ash"`

302 

303 - `"ballad"`

304 

305 - `"coral"`

306 

307 - `"echo"`

308 

309 - `"sage"`

310 

311 - `"shimmer"`

312 

313 - `"verse"`

314 

315 - `"marin"`

316 

317 - `"cedar"`

318 

319 - `expires_at: optional number`

320 

321 Expiration timestamp for the session, in seconds since epoch.

322 

323 - `include: optional array of "item.input_audio_transcription.logprobs"`

324 

325 Additional fields to include in server outputs.

326 

327 `item.input_audio_transcription.logprobs`: Include logprobs for input audio transcription.

328 

329 - `"item.input_audio_transcription.logprobs"`

330 

331 - `instructions: optional string`

332 

333 The default system instructions (i.e. system message) prepended to model calls. This field allows the client to guide the model on desired responses. The model can be instructed on response content and format, (e.g. "be extremely succinct", "act friendly", "here are examples of good responses") and on audio behavior (e.g. "talk quickly", "inject emotion into your voice", "laugh frequently"). The instructions are not guaranteed to be followed by the model, but they provide guidance to the model on the desired behavior.

334 

335 Note that the server sets default instructions which will be used if this field is not set and are visible in the `session.created` event at the start of the session.

336 

337 - `max_output_tokens: optional number or "inf"`

338 

339 Maximum number of output tokens for a single assistant response,

340 inclusive of tool calls. Provide an integer between 1 and 4096 to

341 limit output tokens, or `inf` for the maximum available tokens for a

342 given model. Defaults to `inf`.

343 

344 - `union_member_0: number`

345 

346 - `union_member_1: "inf"`

347 

348 - `model: optional string or "gpt-realtime" or "gpt-realtime-1.5" or "gpt-realtime-2" or 14 more`

349 

350 The Realtime model used for this session.

351 

352 - `"gpt-realtime"`

353 

354 - `"gpt-realtime-1.5"`

355 

356 - `"gpt-realtime-2"`

357 

358 - `"gpt-realtime-2025-08-28"`

359 

360 - `"gpt-4o-realtime-preview"`

361 

362 - `"gpt-4o-realtime-preview-2024-10-01"`

363 

364 - `"gpt-4o-realtime-preview-2024-12-17"`

365 

366 - `"gpt-4o-realtime-preview-2025-06-03"`

367 

368 - `"gpt-4o-mini-realtime-preview"`

369 

370 - `"gpt-4o-mini-realtime-preview-2024-12-17"`

371 

372 - `"gpt-realtime-mini"`

373 

374 - `"gpt-realtime-mini-2025-10-06"`

375 

376 - `"gpt-realtime-mini-2025-12-15"`

377 

378 - `"gpt-audio-1.5"`

379 

380 - `"gpt-audio-mini"`

381 

382 - `"gpt-audio-mini-2025-10-06"`

383 

384 - `"gpt-audio-mini-2025-12-15"`

385 

386 - `output_modalities: optional array of "text" or "audio"`

387 

388 The set of modalities the model can respond with. It defaults to `["audio"]`, indicating

389 that the model will respond with audio plus a transcript. `["text"]` can be used to make

390 the model respond with text only. It is not possible to request both `text` and `audio` at the same time.

391 

392 - `"text"`

393 

394 - `"audio"`

395 

396 - `prompt: optional object { id, variables, version }`

397 

398 Reference to a prompt template and its variables.

399 [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).

400 

401 - `id: string`

402 

403 The unique identifier of the prompt template to use.

404 

405 - `variables: optional map[string or ResponseInputText or ResponseInputImage or ResponseInputFile]`

406 

407 Optional map of values to substitute in for variables in your

408 prompt. The substitution values can either be strings, or other

409 Response input types like images or files.

410 

411 - `union_member_0: string`

412 

413 - `response_input_text: object { text, type }`

414 

415 A text input to the model.

416 

417 - `text: string`

418 

419 The text input to the model.

420 

421 - `type: "input_text"`

422 

423 The type of the input item. Always `input_text`.

424 

425 - `response_input_image: object { detail, type, file_id, image_url }`

426 

427 An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision).

428 

429 - `detail: "low" or "high" or "auto" or "original"`

430 

431 The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`.

432 

433 - `"low"`

434 

435 - `"high"`

436 

437 - `"auto"`

438 

439 - `"original"`

440 

441 - `type: "input_image"`

442 

443 The type of the input item. Always `input_image`.

444 

445 - `file_id: optional string`

446 

447 The ID of the file to be sent to the model.

448 

449 - `image_url: optional string`

450 

451 The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.

452 

453 - `response_input_file: object { type, detail, file_data, 3 more }`

454 

455 A file input to the model.

456 

457 - `type: "input_file"`

458 

459 The type of the input item. Always `input_file`.

460 

461 - `detail: optional "low" or "high"`

462 

463 The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`.

464 

465 - `"low"`

466 

467 - `"high"`

468 

469 - `file_data: optional string`

470 

471 The content of the file to be sent to the model.

472 

473 - `file_id: optional string`

474 

475 The ID of the file to be sent to the model.

476 

477 - `file_url: optional string`

478 

479 The URL of the file to be sent to the model.

480 

481 - `filename: optional string`

482 

483 The name of the file to be sent to the model.

484 

485 - `version: optional string`

486 

487 Optional version of the prompt template.

488 

489 - `reasoning: optional object { effort }`

490 

491 Configuration for reasoning-capable Realtime models such as `gpt-realtime-2`.

492 

493 - `effort: optional "minimal" or "low" or "medium" or 2 more`

494 

495 Constrains effort on reasoning for reasoning-capable Realtime models such as

496 `gpt-realtime-2`.

497 

498 - `"minimal"`

499 

500 - `"low"`

501 

502 - `"medium"`

503 

504 - `"high"`

505 

506 - `"xhigh"`

507 

508 - `tool_choice: optional ToolChoiceOptions or ToolChoiceFunction or ToolChoiceMcp`

509 

510 How the model chooses tools. Provide one of the string modes or force a specific

511 function/MCP tool.

512 

513 - `tool_choice_options: "none" or "auto" or "required"`

514 

515 Controls which (if any) tool is called by the model.

516 

517 `none` means the model will not call any tool and instead generates a message.

518 

519 `auto` means the model can pick between generating a message or calling one or

520 more tools.

521 

522 `required` means the model must call one or more tools.

523 

524 - `"none"`

525 

526 - `"auto"`

527 

528 - `"required"`

529 

530 - `tool_choice_function: object { name, type }`

531 

532 Use this option to force the model to call a specific function.

533 

534 - `name: string`

535 

536 The name of the function to call.

537 

538 - `type: "function"`

539 

540 For function calling, the type is always `function`.

541 

542 - `tool_choice_mcp: object { server_label, type, name }`

543 

544 Use this option to force the model to call a specific tool on a remote MCP server.

545 

546 - `server_label: string`

547 

548 The label of the MCP server to use.

549 

550 - `type: "mcp"`

551 

552 For MCP tools, the type is always `mcp`.

553 

554 - `name: optional string`

555 

556 The name of the tool to call on the server.

557 

558 - `tools: optional array of RealtimeFunctionTool or object { server_label, type, allowed_tools, 7 more }`

559 

560 Tools available to the model.

561 

562 - `realtime_function_tool: object { description, name, parameters, type }`

563 

564 - `description: optional string`

565 

566 The description of the function, including guidance on when and how

567 to call it, and guidance about what to tell the user when calling

568 (if anything).

569 

570 - `name: optional string`

571 

572 The name of the function.

573 

574 - `parameters: optional unknown`

575 

576 Parameters of the function in JSON Schema.

577 

578 - `type: optional "function"`

579 

580 The type of the tool, i.e. `function`.

581 

582 - `"function"`

583 

584 - `MCP tool: object { server_label, type, allowed_tools, 7 more }`

585 

586 Give the model access to additional tools via remote Model Context Protocol

587 (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp).

588 

589 - `server_label: string`

590 

591 A label for this MCP server, used to identify it in tool calls.

592 

593 - `type: "mcp"`

594 

595 The type of the MCP tool. Always `mcp`.

596 

597 - `allowed_tools: optional array of string or object { read_only, tool_names }`

598 

599 List of allowed tool names or a filter object.

600 

601 - `MCP allowed tools: array of string`

602 

603 A string array of allowed tool names

604 

605 - `MCP tool filter: object { read_only, tool_names }`

606 

607 A filter object to specify which tools are allowed.

608 

609 - `read_only: optional boolean`

610 

611 Indicates whether or not a tool modifies data or is read-only. If an

612 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

613 it will match this filter.

614 

615 - `tool_names: optional array of string`

616 

617 List of allowed tool names.

618 

619 - `authorization: optional string`

620 

621 An OAuth access token that can be used with a remote MCP server, either

622 with a custom MCP server URL or a service connector. Your application

623 must handle the OAuth authorization flow and provide the token here.

624 

625 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more`

626 

627 Identifier for service connectors, like those available in ChatGPT. One of

628 `server_url` or `connector_id` must be provided. Learn more about service

629 connectors [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors).

630 

631 Currently supported `connector_id` values are:

632 

633 - Dropbox: `connector_dropbox`

634 - Gmail: `connector_gmail`

635 - Google Calendar: `connector_googlecalendar`

636 - Google Drive: `connector_googledrive`

637 - Microsoft Teams: `connector_microsoftteams`

638 - Outlook Calendar: `connector_outlookcalendar`

639 - Outlook Email: `connector_outlookemail`

640 - SharePoint: `connector_sharepoint`

641 

642 - `"connector_dropbox"`

643 

644 - `"connector_gmail"`

645 

646 - `"connector_googlecalendar"`

647 

648 - `"connector_googledrive"`

649 

650 - `"connector_microsoftteams"`

651 

652 - `"connector_outlookcalendar"`

653 

654 - `"connector_outlookemail"`

655 

656 - `"connector_sharepoint"`

657 

658 - `defer_loading: optional boolean`

659 

660 Whether this MCP tool is deferred and discovered via tool search.

661 

662 - `headers: optional map[string]`

663 

664 Optional HTTP headers to send to the MCP server. Use for authentication

665 or other purposes.

666 

667 - `require_approval: optional object { always, never } or "always" or "never"`

668 

669 Specify which of the MCP server's tools require approval.

670 

671 - `MCP tool approval filter: object { always, never }`

672 

673 Specify which of the MCP server's tools require approval. Can be

674 `always`, `never`, or a filter object associated with tools

675 that require approval.

676 

677 - `always: optional object { read_only, tool_names }`

678 

679 A filter object to specify which tools are allowed.

680 

681 - `read_only: optional boolean`

682 

683 Indicates whether or not a tool modifies data or is read-only. If an

684 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

685 it will match this filter.

686 

687 - `tool_names: optional array of string`

688 

689 List of allowed tool names.

690 

691 - `never: optional object { read_only, tool_names }`

692 

693 A filter object to specify which tools are allowed.

694 

695 - `read_only: optional boolean`

696 

697 Indicates whether or not a tool modifies data or is read-only. If an

698 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

699 it will match this filter.

700 

701 - `tool_names: optional array of string`

702 

703 List of allowed tool names.

704 

705 - `MCP tool approval setting: "always" or "never"`

706 

707 Specify a single approval policy for all tools. One of `always` or

708 `never`. When set to `always`, all tools will require approval. When

709 set to `never`, all tools will not require approval.

710 

711 - `"always"`

712 

713 - `"never"`

714 

715 - `server_description: optional string`

716 

717 Optional description of the MCP server, used to provide more context.

718 

719 - `server_url: optional string`

720 

721 The URL for the MCP server. One of `server_url` or `connector_id` must be

722 provided.

723 

724 - `tracing: optional "auto" or object { group_id, metadata, workflow_name }`

725 

726 Realtime API can write session traces to the [Traces Dashboard](https://platform.openai.com/logs?api=traces). Set to null to disable tracing. Once

727 tracing is enabled for a session, the configuration cannot be modified.

728 

729 `auto` will create a trace for the session with default values for the

730 workflow name, group id, and metadata.

731 

732 - `auto: "auto"`

733 

734 Enables tracing and sets default values for tracing configuration options. Always `auto`.

735 

736 - `Tracing Configuration: object { group_id, metadata, workflow_name }`

737 

738 Granular configuration for tracing.

739 

740 - `group_id: optional string`

741 

742 The group id to attach to this trace to enable filtering and

743 grouping in the Traces Dashboard.

744 

745 - `metadata: optional unknown`

746 

747 The arbitrary metadata to attach to this trace to enable

748 filtering in the Traces Dashboard.

749 

750 - `workflow_name: optional string`

751 

752 The name of the workflow to attach to this trace. This is used to

753 name the trace in the Traces Dashboard.

754 

755 - `truncation: optional "auto" or "disabled" or RealtimeTruncationRetentionRatio`

756 

757 When the number of tokens in a conversation exceeds the model's input token limit, the conversation be truncated, meaning messages (starting from the oldest) will not be included in the model's context. A 32k context model with 4,096 max output tokens can only include 28,224 tokens in the context before truncation occurs.

758 

759 Clients can configure truncation behavior to truncate with a lower max token limit, which is an effective way to control token usage and cost.

760 

761 Truncation will reduce the number of cached tokens on the next turn (busting the cache), since messages are dropped from the beginning of the context. However, clients can also configure truncation to retain messages up to a fraction of the maximum context size, which will reduce the need for future truncations and thus improve the cache rate.

762 

763 Truncation can be disabled entirely, which means the server will never truncate but would instead return an error if the conversation exceeds the model's input token limit.

764 

765 - `RealtimeTruncationStrategy: "auto" or "disabled"`

766 

767 The truncation strategy to use for the session. `auto` is the default truncation strategy. `disabled` will disable truncation and emit errors when the conversation exceeds the input token limit.

768 

769 - `"auto"`

770 

771 - `"disabled"`

772 

773 - `realtime_truncation_retention_ratio: object { retention_ratio, type, token_limits }`

774 

775 Retain a fraction of the conversation tokens when the conversation exceeds the input token limit. This allows you to amortize truncations across multiple turns, which can help improve cached token usage.

776 

777 - `retention_ratio: number`

778 

779 Fraction of post-instruction conversation tokens to retain (`0.0` - `1.0`) when the conversation exceeds the input token limit. Setting this to `0.8` means that messages will be dropped until 80% of the maximum allowed tokens are used. This helps reduce the frequency of truncations and improve cache rates.

780 

781 - `type: "retention_ratio"`

782 

783 Use retention ratio truncation.

784 

785 - `token_limits: optional object { post_instructions }`

786 

787 Optional custom token limits for this truncation strategy. If not provided, the model's default token limits will be used.

788 

789 - `post_instructions: optional number`

790 

791 Maximum tokens allowed in the conversation after instructions (which including tool definitions). For example, setting this to 5,000 would mean that truncation would occur when the conversation exceeds 5,000 tokens after instructions. This cannot be higher than the model's context window size minus the maximum output tokens.

792 

793 - `realtime_transcription_session_create_response: object { id, object, type, 3 more }`

794 

795 A Realtime transcription session configuration object.

796 

797 - `id: string`

798 

799 Unique identifier for the session that looks like `sess_1234567890abcdef`.

800 

801 - `object: string`

802 

803 The object type. Always `realtime.transcription_session`.

804 

805 - `type: "transcription"`

806 

807 The type of session. Always `transcription` for transcription sessions.

808 

809 - `audio: optional object { input }`

810 

811 Configuration for input audio for the session.

812 

813 - `input: optional object { format, noise_reduction, transcription, turn_detection }`

814 

815 - `format: optional object { rate, type } or object { type } or object { type }`

816 

817 The PCM audio format. Only a 24kHz sample rate is supported.

818 

819 - `audio/pcm: object { rate, type }`

820 

821 The PCM audio format. Only a 24kHz sample rate is supported.

822 

823 - `audio/pcmu: object { type }`

824 

825 The G.711 μ-law format.

826 

827 - `audio/pcma: object { type }`

828 

829 The G.711 A-law format.

830 

831 - `noise_reduction: optional object { type }`

832 

833 Configuration for input audio noise reduction.

834 

835 - `type: optional "near_field" or "far_field"`

836 

837 Type of noise reduction. `near_field` is for close-talking microphones such as headphones, `far_field` is for far-field microphones such as laptop or conference room microphones.

838 

839 - `"near_field"`

840 

841 - `"far_field"`

842 

843 - `transcription: optional object { delay, language, model, prompt }`

844 

845 - `delay: optional "minimal" or "low" or "medium" or 2 more`

846 

847 Controls how long the model waits before emitting transcription text.

848 Higher values can improve transcription accuracy at the cost of latency.

849 Only supported with `gpt-realtime-whisper` in GA Realtime sessions.

850 

851 - `language: optional string`

852 

853 The language of the input audio. Supplying the input language in

854 [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format

855 will improve accuracy and latency.

856 

857 - `model: optional string or "whisper-1" or "gpt-4o-mini-transcribe" or "gpt-4o-mini-transcribe-2025-12-15" or 3 more`

858 

859 The model to use for transcription. Current options are `whisper-1`, `gpt-4o-mini-transcribe`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-transcribe`, `gpt-4o-transcribe-diarize`, and `gpt-realtime-whisper`. Use `gpt-4o-transcribe-diarize` when you need diarization with speaker labels.

860 

861 - `prompt: optional string`

862 

863 An optional text to guide the model's style or continue a previous audio

864 segment.

865 For `whisper-1`, the [prompt is a list of keywords](https://platform.openai.com/docs/guides/speech-to-text#prompting).

866 For `gpt-4o-transcribe` models (excluding `gpt-4o-transcribe-diarize`), the prompt is a free text string, for example "expect words related to technology".

867 Prompt is not supported with `gpt-realtime-whisper` in GA Realtime sessions.

868 

869 - `turn_detection: optional object { prefix_padding_ms, silence_duration_ms, threshold, type }`

870 

871 Configuration for turn detection. Can be set to `null` to turn off. Server

872 VAD means that the model will detect the start and end of speech based on

873 audio volume and respond at the end of user speech. For `gpt-realtime-whisper`, this must be `null`; VAD is not supported.

874 

875 - `prefix_padding_ms: optional number`

876 

877 Amount of audio to include before the VAD detected speech (in

878 milliseconds). Defaults to 300ms.

879 

880 - `silence_duration_ms: optional number`

881 

882 Duration of silence to detect speech stop (in milliseconds). Defaults

883 to 500ms. With shorter values the model will respond more quickly,

884 but may jump in on short pauses from the user.

885 

886 - `threshold: optional number`

887 

888 Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A

889 higher threshold will require louder audio to activate the model, and

890 thus might perform better in noisy environments.

891 

892 - `type: optional string`

893 

894 Type of turn detection, only `server_vad` is currently supported.

895 

896 - `expires_at: optional number`

897 

898 Expiration timestamp for the session, in seconds since epoch.

899 

900 - `include: optional array of "item.input_audio_transcription.logprobs"`

901 

902 Additional fields to include in server outputs.

903 

904 - `item.input_audio_transcription.logprobs`: Include logprobs for input audio transcription.

905 

906 - `"item.input_audio_transcription.logprobs"`

907 

908 - `value: string`

909 

910 The generated client secret value.

911 

912### Example

913 

914```cli

915openai realtime:client-secrets create \

916 --api-key 'My API Key'

917```

918 

919#### Response

920 

921```json

922{

923 "expires_at": 0,

924 "session": {

925 "id": "id",

926 "object": "realtime.session",

927 "type": "realtime",

928 "audio": {

929 "input": {

930 "format": {

931 "rate": 24000,

932 "type": "audio/pcm"

933 },

934 "noise_reduction": {

935 "type": "near_field"

936 },

937 "transcription": {

938 "delay": "minimal",

939 "language": "language",

940 "model": "whisper-1",

941 "prompt": "prompt"

942 },

943 "turn_detection": {

944 "type": "server_vad",

945 "create_response": true,

946 "idle_timeout_ms": 5000,

947 "interrupt_response": true,

948 "prefix_padding_ms": 0,

949 "silence_duration_ms": 0,

950 "threshold": 0

951 }

952 },

953 "output": {

954 "format": {

955 "rate": 24000,

956 "type": "audio/pcm"

957 },

958 "speed": 0.25,

959 "voice": "ash"

960 }

961 },

962 "expires_at": 0,

963 "include": [

964 "item.input_audio_transcription.logprobs"

965 ],

966 "instructions": "instructions",

967 "max_output_tokens": "inf",

968 "model": "gpt-realtime",

969 "output_modalities": [

970 "text"

971 ],

972 "prompt": {

973 "id": "id",

974 "variables": {

975 "foo": "string"

976 },

977 "version": "version"

978 },

979 "reasoning": {

980 "effort": "minimal"

981 },

982 "tool_choice": "none",

983 "tools": [

984 {

985 "description": "description",

986 "name": "name",

987 "parameters": {},

988 "type": "function"

989 }

990 ],

991 "tracing": "auto",

992 "truncation": "auto"

993 },

994 "value": "value"

995}

996```

1## Create video

2 

3`$ openai videos create`

4 

5**post** `/videos`

6 

7Create a new video generation job from a prompt and optional reference assets.

8 

9### Parameters

10 

11- `--prompt: string`

12 

13 Text prompt that describes the video to generate.

14 

15- `--input-reference: optional string or ImageInputReferenceParam`

16 

17 Optional reference asset upload or reference object that guides generation.

18 

19- `--model: optional string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`

20 

21 The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to `sora-2`.

22 

23- `--seconds: optional "4" or "8" or "12"`

24 

25 Clip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds.

26 

27- `--size: optional "720x1280" or "1280x720" or "1024x1792" or "1792x1024"`

28 

29 Output resolution formatted as width x height (allowed values: 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280.

30 

31### Returns

32 

33- `video: object { id, completed_at, created_at, 10 more }`

34 

35 Structured information describing a generated video job.

36 

37 - `id: string`

38 

39 Unique identifier for the video job.

40 

41 - `completed_at: number`

42 

43 Unix timestamp (seconds) for when the job completed, if finished.

44 

45 - `created_at: number`

46 

47 Unix timestamp (seconds) for when the job was created.

48 

49 - `error: object { code, message }`

50 

51 Error payload that explains why generation failed, if applicable.

52 

53 - `code: string`

54 

55 A machine-readable error code that was returned.

56 

57 - `message: string`

58 

59 A human-readable description of the error that was returned.

60 

61 - `expires_at: number`

62 

63 Unix timestamp (seconds) for when the downloadable assets expire, if set.

64 

65 - `model: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`

66 

67 The video generation model that produced the job.

68 

69 - `"sora-2"`

70 

71 - `"sora-2-pro"`

72 

73 - `"sora-2-2025-10-06"`

74 

75 - `"sora-2-pro-2025-10-06"`

76 

77 - `"sora-2-2025-12-08"`

78 

79 - `object: "video"`

80 

81 The object type, which is always `video`.

82 

83 - `progress: number`

84 

85 Approximate completion percentage for the generation task.

86 

87 - `prompt: string`

88 

89 The prompt that was used to generate the video.

90 

91 - `remixed_from_video_id: string`

92 

93 Identifier of the source video if this video is a remix.

94 

95 - `seconds: string or VideoSeconds`

96 

97 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.

98 

99 - `"4"`

100 

101 - `"8"`

102 

103 - `"12"`

104 

105 - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"`

106 

107 The resolution of the generated video.

108 

109 - `"720x1280"`

110 

111 - `"1280x720"`

112 

113 - `"1024x1792"`

114 

115 - `"1792x1024"`

116 

117 - `status: "queued" or "in_progress" or "completed" or "failed"`

118 

119 Current lifecycle status of the video job.

120 

121 - `"queued"`

122 

123 - `"in_progress"`

124 

125 - `"completed"`

126 

127 - `"failed"`

128 

129### Example

130 

131```cli

132openai videos create \

133 --api-key 'My API Key' \

134 --prompt x

135```

136 

137#### Response

138 

139```json

140{

141 "id": "id",

142 "completed_at": 0,

143 "created_at": 0,

144 "error": {

145 "code": "code",

146 "message": "message"

147 },

148 "expires_at": 0,

149 "model": "sora-2",

150 "object": "video",

151 "progress": 0,

152 "prompt": "prompt",

153 "remixed_from_video_id": "remixed_from_video_id",

154 "seconds": "4",

155 "size": "720x1280",

156 "status": "queued"

157}

158```

1## Create a new video generation job by editing a source video or existing generated video.

2 

3`$ openai videos edit`

4 

5**post** `/videos/edits`

6 

7Create a new video generation job by editing a source video or existing generated video.

8 

9### Parameters

10 

11- `--prompt: string`

12 

13 Text prompt that describes how to edit the source video.

14 

15- `--video: string or object { id }`

16 

17 Reference to the completed video to edit.

18 

19### Returns

20 

21- `video: object { id, completed_at, created_at, 10 more }`

22 

23 Structured information describing a generated video job.

24 

25 - `id: string`

26 

27 Unique identifier for the video job.

28 

29 - `completed_at: number`

30 

31 Unix timestamp (seconds) for when the job completed, if finished.

32 

33 - `created_at: number`

34 

35 Unix timestamp (seconds) for when the job was created.

36 

37 - `error: object { code, message }`

38 

39 Error payload that explains why generation failed, if applicable.

40 

41 - `code: string`

42 

43 A machine-readable error code that was returned.

44 

45 - `message: string`

46 

47 A human-readable description of the error that was returned.

48 

49 - `expires_at: number`

50 

51 Unix timestamp (seconds) for when the downloadable assets expire, if set.

52 

53 - `model: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`

54 

55 The video generation model that produced the job.

56 

57 - `"sora-2"`

58 

59 - `"sora-2-pro"`

60 

61 - `"sora-2-2025-10-06"`

62 

63 - `"sora-2-pro-2025-10-06"`

64 

65 - `"sora-2-2025-12-08"`

66 

67 - `object: "video"`

68 

69 The object type, which is always `video`.

70 

71 - `progress: number`

72 

73 Approximate completion percentage for the generation task.

74 

75 - `prompt: string`

76 

77 The prompt that was used to generate the video.

78 

79 - `remixed_from_video_id: string`

80 

81 Identifier of the source video if this video is a remix.

82 

83 - `seconds: string or VideoSeconds`

84 

85 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.

86 

87 - `"4"`

88 

89 - `"8"`

90 

91 - `"12"`

92 

93 - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"`

94 

95 The resolution of the generated video.

96 

97 - `"720x1280"`

98 

99 - `"1280x720"`

100 

101 - `"1024x1792"`

102 

103 - `"1792x1024"`

104 

105 - `status: "queued" or "in_progress" or "completed" or "failed"`

106 

107 Current lifecycle status of the video job.

108 

109 - `"queued"`

110 

111 - `"in_progress"`

112 

113 - `"completed"`

114 

115 - `"failed"`

116 

117### Example

118 

119```cli

120openai videos edit \

121 --api-key 'My API Key' \

122 --prompt x \

123 --video 'Example data'

124```

125 

126#### Response

127 

128```json

129{

130 "id": "id",

131 "completed_at": 0,

132 "created_at": 0,

133 "error": {

134 "code": "code",

135 "message": "message"

136 },

137 "expires_at": 0,

138 "model": "sora-2",

139 "object": "video",

140 "progress": 0,

141 "prompt": "prompt",

142 "remixed_from_video_id": "remixed_from_video_id",

143 "seconds": "4",

144 "size": "720x1280",

145 "status": "queued"

146}

147```

1## Create an extension of a completed video.

2 

3`$ openai videos extend`

4 

5**post** `/videos/extensions`

6 

7Create an extension of a completed video.

8 

9### Parameters

10 

11- `--prompt: string`

12 

13 Updated text prompt that directs the extension generation.

14 

15- `--seconds: "4" or "8" or "12"`

16 

17 Length of the newly generated extension segment in seconds (allowed values: 4, 8, 12, 16, 20).

18 

19- `--video: string or object { id }`

20 

21 Reference to the completed video to extend.

22 

23### Returns

24 

25- `video: object { id, completed_at, created_at, 10 more }`

26 

27 Structured information describing a generated video job.

28 

29 - `id: string`

30 

31 Unique identifier for the video job.

32 

33 - `completed_at: number`

34 

35 Unix timestamp (seconds) for when the job completed, if finished.

36 

37 - `created_at: number`

38 

39 Unix timestamp (seconds) for when the job was created.

40 

41 - `error: object { code, message }`

42 

43 Error payload that explains why generation failed, if applicable.

44 

45 - `code: string`

46 

47 A machine-readable error code that was returned.

48 

49 - `message: string`

50 

51 A human-readable description of the error that was returned.

52 

53 - `expires_at: number`

54 

55 Unix timestamp (seconds) for when the downloadable assets expire, if set.

56 

57 - `model: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`

58 

59 The video generation model that produced the job.

60 

61 - `"sora-2"`

62 

63 - `"sora-2-pro"`

64 

65 - `"sora-2-2025-10-06"`

66 

67 - `"sora-2-pro-2025-10-06"`

68 

69 - `"sora-2-2025-12-08"`

70 

71 - `object: "video"`

72 

73 The object type, which is always `video`.

74 

75 - `progress: number`

76 

77 Approximate completion percentage for the generation task.

78 

79 - `prompt: string`

80 

81 The prompt that was used to generate the video.

82 

83 - `remixed_from_video_id: string`

84 

85 Identifier of the source video if this video is a remix.

86 

87 - `seconds: string or VideoSeconds`

88 

89 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.

90 

91 - `"4"`

92 

93 - `"8"`

94 

95 - `"12"`

96 

97 - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"`

98 

99 The resolution of the generated video.

100 

101 - `"720x1280"`

102 

103 - `"1280x720"`

104 

105 - `"1024x1792"`

106 

107 - `"1792x1024"`

108 

109 - `status: "queued" or "in_progress" or "completed" or "failed"`

110 

111 Current lifecycle status of the video job.

112 

113 - `"queued"`

114 

115 - `"in_progress"`

116 

117 - `"completed"`

118 

119 - `"failed"`

120 

121### Example

122 

123```cli

124openai videos extend \

125 --api-key 'My API Key' \

126 --prompt x \

127 --seconds 4 \

128 --video 'Example data'

129```

130 

131#### Response

132 

133```json

134{

135 "id": "id",

136 "completed_at": 0,

137 "created_at": 0,

138 "error": {

139 "code": "code",

140 "message": "message"

141 },

142 "expires_at": 0,

143 "model": "sora-2",

144 "object": "video",

145 "progress": 0,

146 "prompt": "prompt",

147 "remixed_from_video_id": "remixed_from_video_id",

148 "seconds": "4",

149 "size": "720x1280",

150 "status": "queued"

151}

152```

1## List videos

2 

3`$ openai videos list`

4 

5**get** `/videos`

6 

7List recently generated videos for the current project.

8 

9### Parameters

10 

11- `--after: optional string`

12 

13 Identifier for the last item from the previous pagination request

14 

15- `--limit: optional number`

16 

17 Number of items to retrieve

18 

19- `--order: optional "asc" or "desc"`

20 

21 Sort order of results by timestamp. Use `asc` for ascending order or `desc` for descending order.

22 

23### Returns

24 

25- `VideoListResource: object { data, first_id, has_more, 2 more }`

26 

27 - `data: array of Video`

28 

29 A list of items

30 

31 - `id: string`

32 

33 Unique identifier for the video job.

34 

35 - `completed_at: number`

36 

37 Unix timestamp (seconds) for when the job completed, if finished.

38 

39 - `created_at: number`

40 

41 Unix timestamp (seconds) for when the job was created.

42 

43 - `error: object { code, message }`

44 

45 Error payload that explains why generation failed, if applicable.

46 

47 - `code: string`

48 

49 A machine-readable error code that was returned.

50 

51 - `message: string`

52 

53 A human-readable description of the error that was returned.

54 

55 - `expires_at: number`

56 

57 Unix timestamp (seconds) for when the downloadable assets expire, if set.

58 

59 - `model: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`

60 

61 The video generation model that produced the job.

62 

63 - `"sora-2"`

64 

65 - `"sora-2-pro"`

66 

67 - `"sora-2-2025-10-06"`

68 

69 - `"sora-2-pro-2025-10-06"`

70 

71 - `"sora-2-2025-12-08"`

72 

73 - `object: "video"`

74 

75 The object type, which is always `video`.

76 

77 - `progress: number`

78 

79 Approximate completion percentage for the generation task.

80 

81 - `prompt: string`

82 

83 The prompt that was used to generate the video.

84 

85 - `remixed_from_video_id: string`

86 

87 Identifier of the source video if this video is a remix.

88 

89 - `seconds: string or VideoSeconds`

90 

91 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.

92 

93 - `"4"`

94 

95 - `"8"`

96 

97 - `"12"`

98 

99 - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"`

100 

101 The resolution of the generated video.

102 

103 - `"720x1280"`

104 

105 - `"1280x720"`

106 

107 - `"1024x1792"`

108 

109 - `"1792x1024"`

110 

111 - `status: "queued" or "in_progress" or "completed" or "failed"`

112 

113 Current lifecycle status of the video job.

114 

115 - `"queued"`

116 

117 - `"in_progress"`

118 

119 - `"completed"`

120 

121 - `"failed"`

122 

123 - `first_id: string`

124 

125 The ID of the first item in the list.

126 

127 - `has_more: boolean`

128 

129 Whether there are more items available.

130 

131 - `last_id: string`

132 

133 The ID of the last item in the list.

134 

135 - `object: "list"`

136 

137 The type of object returned, must be `list`.

138 

139### Example

140 

141```cli

142openai videos list \

143 --api-key 'My API Key'

144```

145 

146#### Response

147 

148```json

149{

150 "data": [

151 {

152 "id": "id",

153 "completed_at": 0,

154 "created_at": 0,

155 "error": {

156 "code": "code",

157 "message": "message"

158 },

159 "expires_at": 0,

160 "model": "sora-2",

161 "object": "video",

162 "progress": 0,

163 "prompt": "prompt",

164 "remixed_from_video_id": "remixed_from_video_id",

165 "seconds": "4",

166 "size": "720x1280",

167 "status": "queued"

168 }

169 ],

170 "first_id": "first_id",

171 "has_more": true,

172 "last_id": "last_id",

173 "object": "list"

174}

175```

1## Remix video

2 

3`$ openai videos remix`

4 

5**post** `/videos/{video_id}/remix`

6 

7Create a remix of a completed video using a refreshed prompt.

8 

9### Parameters

10 

11- `--video-id: string`

12 

13 The identifier of the completed video to remix.

14 

15- `--prompt: string`

16 

17 Updated text prompt that directs the remix generation.

18 

19### Returns

20 

21- `video: object { id, completed_at, created_at, 10 more }`

22 

23 Structured information describing a generated video job.

24 

25 - `id: string`

26 

27 Unique identifier for the video job.

28 

29 - `completed_at: number`

30 

31 Unix timestamp (seconds) for when the job completed, if finished.

32 

33 - `created_at: number`

34 

35 Unix timestamp (seconds) for when the job was created.

36 

37 - `error: object { code, message }`

38 

39 Error payload that explains why generation failed, if applicable.

40 

41 - `code: string`

42 

43 A machine-readable error code that was returned.

44 

45 - `message: string`

46 

47 A human-readable description of the error that was returned.

48 

49 - `expires_at: number`

50 

51 Unix timestamp (seconds) for when the downloadable assets expire, if set.

52 

53 - `model: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`

54 

55 The video generation model that produced the job.

56 

57 - `"sora-2"`

58 

59 - `"sora-2-pro"`

60 

61 - `"sora-2-2025-10-06"`

62 

63 - `"sora-2-pro-2025-10-06"`

64 

65 - `"sora-2-2025-12-08"`

66 

67 - `object: "video"`

68 

69 The object type, which is always `video`.

70 

71 - `progress: number`

72 

73 Approximate completion percentage for the generation task.

74 

75 - `prompt: string`

76 

77 The prompt that was used to generate the video.

78 

79 - `remixed_from_video_id: string`

80 

81 Identifier of the source video if this video is a remix.

82 

83 - `seconds: string or VideoSeconds`

84 

85 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.

86 

87 - `"4"`

88 

89 - `"8"`

90 

91 - `"12"`

92 

93 - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"`

94 

95 The resolution of the generated video.

96 

97 - `"720x1280"`

98 

99 - `"1280x720"`

100 

101 - `"1024x1792"`

102 

103 - `"1792x1024"`

104 

105 - `status: "queued" or "in_progress" or "completed" or "failed"`

106 

107 Current lifecycle status of the video job.

108 

109 - `"queued"`

110 

111 - `"in_progress"`

112 

113 - `"completed"`

114 

115 - `"failed"`

116 

117### Example

118 

119```cli

120openai videos remix \

121 --api-key 'My API Key' \

122 --video-id video_123 \

123 --prompt x

124```

125 

126#### Response

127 

128```json

129{

130 "id": "id",

131 "completed_at": 0,

132 "created_at": 0,

133 "error": {

134 "code": "code",

135 "message": "message"

136 },

137 "expires_at": 0,

138 "model": "sora-2",

139 "object": "video",

140 "progress": 0,

141 "prompt": "prompt",

142 "remixed_from_video_id": "remixed_from_video_id",

143 "seconds": "4",

144 "size": "720x1280",

145 "status": "queued"

146}

147```

1## Retrieve video

2 

3`$ openai videos retrieve`

4 

5**get** `/videos/{video_id}`

6 

7Fetch the latest metadata for a generated video.

8 

9### Parameters

10 

11- `--video-id: string`

12 

13 The identifier of the video to retrieve.

14 

15### Returns

16 

17- `video: object { id, completed_at, created_at, 10 more }`

18 

19 Structured information describing a generated video job.

20 

21 - `id: string`

22 

23 Unique identifier for the video job.

24 

25 - `completed_at: number`

26 

27 Unix timestamp (seconds) for when the job completed, if finished.

28 

29 - `created_at: number`

30 

31 Unix timestamp (seconds) for when the job was created.

32 

33 - `error: object { code, message }`

34 

35 Error payload that explains why generation failed, if applicable.

36 

37 - `code: string`

38 

39 A machine-readable error code that was returned.

40 

41 - `message: string`

42 

43 A human-readable description of the error that was returned.

44 

45 - `expires_at: number`

46 

47 Unix timestamp (seconds) for when the downloadable assets expire, if set.

48 

49 - `model: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`

50 

51 The video generation model that produced the job.

52 

53 - `"sora-2"`

54 

55 - `"sora-2-pro"`

56 

57 - `"sora-2-2025-10-06"`

58 

59 - `"sora-2-pro-2025-10-06"`

60 

61 - `"sora-2-2025-12-08"`

62 

63 - `object: "video"`

64 

65 The object type, which is always `video`.

66 

67 - `progress: number`

68 

69 Approximate completion percentage for the generation task.

70 

71 - `prompt: string`

72 

73 The prompt that was used to generate the video.

74 

75 - `remixed_from_video_id: string`

76 

77 Identifier of the source video if this video is a remix.

78 

79 - `seconds: string or VideoSeconds`

80 

81 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.

82 

83 - `"4"`

84 

85 - `"8"`

86 

87 - `"12"`

88 

89 - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"`

90 

91 The resolution of the generated video.

92 

93 - `"720x1280"`

94 

95 - `"1280x720"`

96 

97 - `"1024x1792"`

98 

99 - `"1792x1024"`

100 

101 - `status: "queued" or "in_progress" or "completed" or "failed"`

102 

103 Current lifecycle status of the video job.

104 

105 - `"queued"`

106 

107 - `"in_progress"`

108 

109 - `"completed"`

110 

111 - `"failed"`

112 

113### Example

114 

115```cli

116openai videos retrieve \

117 --api-key 'My API Key' \

118 --video-id video_123

119```

120 

121#### Response

122 

123```json

124{

125 "id": "id",

126 "completed_at": 0,

127 "created_at": 0,

128 "error": {

129 "code": "code",

130 "message": "message"

131 },

132 "expires_at": 0,

133 "model": "sora-2",

134 "object": "video",

135 "progress": 0,

136 "prompt": "prompt",

137 "remixed_from_video_id": "remixed_from_video_id",

138 "seconds": "4",

139 "size": "720x1280",

140 "status": "queued"

141}

142```

1## Create speech

2 

3`client.Audio.Speech.New(ctx, body) (*Response, error)`

4 

5**post** `/audio/speech`