> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# openai-ai
> OpenAI AI - chat completions, responses, audio, images, embeddings, and models
**Server path:** `/openai-ai` | **Type:** Application | **PCID required:** Yes
## Tools
| Tool | Description |
| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`openai_ai_create_chat_completion`](#openai_ai_create_chat_completion) | **Starting a new project?** We recommend trying Responses to take advantage of the latest OpenAI platform features. Compare Chat Completions with Responses. --- Creates a model response for the given chat conversation. Learn more in the text generation, vision, and audio guides. Parameter support can differ depending on the model used to generate the response, particularly for newer reasoning models. Parameters that are only supported for reasoning models are noted below. For the current state of unsupported parameters in reasoning models, refer to the reasoning guide. |
| [`openai_ai_create_completion`](#openai_ai_create_completion) | Creates a completion for the provided prompt and parameters. |
| [`openai_ai_create_embedding`](#openai_ai_create_embedding) | Creates an embedding vector representing the input text. |
| [`openai_ai_create_image`](#openai_ai_create_image) | Creates an image given a prompt. Learn more. |
| [`openai_ai_create_image_variation`](#openai_ai_create_image_variation) | Creates a variation of a given image. This endpoint only supports `dall-e-2`. |
| [`openai_ai_create_moderation`](#openai_ai_create_moderation) | Classifies if text and/or image inputs are potentially harmful. Learn more in the moderation guide. |
| [`openai_ai_create_realtime_session`](#openai_ai_create_realtime_session) | Create an ephemeral API token for use in client-side applications with the Realtime API. Can be configured with the same session parameters as the `session.update` client event. It responds with a session object, plus a `client_secret` key which contains a usable ephemeral API token that can be used to authenticate browser clients for the Realtime API. |
| [`openai_ai_create_realtime_transcription_session`](#openai_ai_create_realtime_transcription_session) | Create an ephemeral API token for use in client-side applications with the Realtime API specifically for realtime transcriptions. Can be configured with the same session parameters as the `transcription_session.update` client event. It responds with a session object, plus a `client_secret` key which contains a usable ephemeral API token that can be used to authenticate browser clients for the Realtime API. |
| [`openai_ai_create_response`](#openai_ai_create_response) | Creates a model response. Provide text or image inputs to generate text or JSON outputs. Have the model call your own custom code or use built-in tools like web search or file search to use your own data as input for the model's response. |
| [`openai_ai_create_speech`](#openai_ai_create_speech) | Generates audio from the input text. |
| [`openai_ai_create_transcription`](#openai_ai_create_transcription) | Transcribes audio into the input language. |
| [`openai_ai_create_translation`](#openai_ai_create_translation) | Translates audio into English. |
| [`openai_ai_delete_chat_completion`](#openai_ai_delete_chat_completion) | Delete a stored chat completion. Only Chat Completions that have been created with the `store` parameter set to `true` can be deleted. |
| [`openai_ai_delete_model`](#openai_ai_delete_model) | Delete a fine-tuned model. You must have the Owner role in your organization to delete a model. |
| [`openai_ai_delete_response`](#openai_ai_delete_response) | Deletes a model response with the given ID. |
| [`openai_ai_get_chat_completion`](#openai_ai_get_chat_completion) | Get a stored chat completion. Only Chat Completions that have been created with the `store` parameter set to `true` will be returned. |
| [`openai_ai_get_chat_completion_messages`](#openai_ai_get_chat_completion_messages) | Get the messages in a stored chat completion. Only Chat Completions that have been created with the `store` parameter set to `true` will be returned. |
| [`openai_ai_get_response`](#openai_ai_get_response) | Retrieves a model response with the given ID. |
| [`openai_ai_list_chat_completions`](#openai_ai_list_chat_completions) | List stored Chat Completions. Only Chat Completions that have been stored with the `store` parameter set to `true` will be returned. |
| [`openai_ai_list_input_items`](#openai_ai_list_input_items) | Returns a list of input items for a given response. |
| [`openai_ai_list_models`](#openai_ai_list_models) | Lists the currently available models, and provides basic information about each one such as the owner and availability. |
| [`openai_ai_retrieve_model`](#openai_ai_retrieve_model) | Retrieves a model instance, providing basic information about the model such as the owner and permissioning. |
| [`openai_ai_update_chat_completion`](#openai_ai_update_chat_completion) | Modify a stored chat completion. Only Chat Completions that have been created with the `store` parameter set to `true` can be modified. Currently, the only supported modification is to update the `metadata` field. |
***
## openai\_ai\_create\_chat\_completion
**Starting a new project?** We recommend trying Responses to take advantage of the latest OpenAI platform features. Compare Chat Completions with Responses. --- Creates a model response for the given chat conversation. Learn more in the text generation, vision, and audio guides. Parameter support can differ depending on the model used to generate the response, particularly for newer reasoning models. Parameters that are only supported for reasoning models are noted below. For the current state of unsupported parameters in reasoning models, refer to the reasoning guide.
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------------- | --------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `audio` | object | No | — | Parameters for audio output. Required when audio output is requested with `modalities: ["audio"]`. Learn more. | |
| `frequency_penalty` | number | null | No | — | Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. |
| `function_call` | object | No | — | Deprecated in favor of `tool_choice`. Controls which (if any) function is called by the model. `none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function. Specifying a particular function via `{"name": "my_function"}` forces the model to call that function. `none` is the default when no functions are present. `auto` is the default if functions are present. | |
| `functions` | object\[] | No | — | Deprecated in favor of `tools`. A list of functions the model may generate JSON inputs for. | |
| `logit_bias` | object | No | — | Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token. | |
| `logprobs` | boolean | null | No | — | Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the `content` of `message`. |
| `max_completion_tokens` | integer | null | No | — | An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens. |
| `max_tokens` | integer | null | No | — | The maximum number of tokens that can be generated in the chat completion. This value can be used to control [costs](https://openai.com/api/pricing/) for text generated via API. This value is now deprecated in favor of `max_completion_tokens`, and is not compatible with o-series models. |
| `messages` | any\[] | Yes | — | A list of messages comprising the conversation so far. Depending on the model you use, different message types (modalities) are supported, like text, images, and audio. | |
| `metadata` | object | No | — | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. | |
| `modalities` | string\[] | No | — | Output types that you would like the model to generate. Most models are capable of generating text, which is the default: `["text"]` The `gpt-4o-audio-preview` model can also be used to generate audio. To request that this model generate both text and audio responses, you can use: `["text", "audio"]` | |
| `model` | object | Yes | — | The model value | |
| `n` | integer | null | No | — | How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep `n` as `1` to minimize costs. |
| `parallel_tool_calls` | boolean | No | — | Whether to enable parallel function calling during tool use. | |
| `prediction` | object | No | — | Configuration for a Predicted Output, which can greatly improve response times when large parts of the model response are known ahead of time. This is most common when you are regenerating a file with only minor changes to most of the content. | |
| `presence_penalty` | number | null | No | — | Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. |
| `reasoning_effort` | string | null | No | — | **o-series models only** Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `low`, `medium`, and `high`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. |
| `response_format` | object | No | — | An object specifying the format that the model must output. Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide. Setting to `{ "type": "json_object" }` enables the older JSON mode, which ensures the message the model generates is valid JSON. Using `json_schema` is preferred for models that support it. | |
| `seed` | integer | null | No | — | This feature is in Beta. If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend. |
| `service_tier` | string | null | No | — | Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service: - If set to 'auto', and the Project is Scale tier enabled, the system will utilize scale tier credits until they are exhausted. - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. - If set to 'flex', the request will be processed with the Flex Processing service tier. Learn more. - When not set, the default behavior is 'auto'. When this parameter is set, the response body will include the `service_tier` utilized. |
| `stop` | string\[] | No | — | Not supported with latest reasoning models `o3` and `o4-mini`. Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence. | |
| `store` | boolean | null | No | — | Whether or not to store the output of this chat completion request for use in our model distillation or evals products. |
| `stream` | boolean | null | No | — | If set to true, the model response data will be streamed to the client as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). See the Streaming section below for more information, along with the streaming responses guide for more information on how to handle the streaming events. |
| `stream_options` | object | No | — | Options for streaming response. Only set this when you set `stream: true`. | |
| `temperature` | number | null | No | — | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. |
| `tool_choice` | object | No | — | Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present. | |
| `tools` | object\[] | No | — | A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported. | |
| `top_logprobs` | integer | null | No | — | An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. `logprobs` must be set to `true` if this parameter is used. |
| `top_p` | number | null | No | — | An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top\_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. |
| `user` | string | No | — | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more. | |
| `web_search_options` | object | No | — | This tool searches the web for relevant results to use in a response. Learn more about the web search tool. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"audio": {
"type": "object",
"description": "Parameters for audio output. Required when audio output is requested with `modalities: [\"audio\"]`. [Learn more](/docs/guides/audio).",
"properties": {
"voice": {
"description": "The voice value"
},
"format": {
"type": "string",
"description": "Specifies the output audio format. Must be one of `wav`, `mp3`, `flac`, `opus`, or `pcm16`.",
"enum": [
"wav",
"aac",
"mp3",
"flac",
"opus",
"pcm16"
]
}
},
"required": [
"voice",
"format"
]
},
"frequency_penalty": {
"type": [
"number",
"null"
],
"description": "Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim."
},
"function_call": {
"description": "Deprecated in favor of `tool_choice`. Controls which (if any) function is called by the model. `none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function. Specifying a particular function via `{\"name\": \"my_function\"}` forces the model to call that function. `none` is the default when no functions are present. `auto` is the default if functions are present."
},
"functions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "A description of what the function does, used by the model to choose when and how to call the function."
},
"name": {
"type": "string",
"description": "The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64."
},
"parameters": {
"type": "object",
"description": "The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting `parameters` defines a function with an empty parameter list."
}
},
"required": [
"name"
]
},
"description": "Deprecated in favor of `tools`. A list of functions the model may generate JSON inputs for."
},
"logit_bias": {
"type": "object",
"description": "Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token."
},
"logprobs": {
"type": [
"boolean",
"null"
],
"description": "Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the `content` of `message`."
},
"max_completion_tokens": {
"type": [
"integer",
"null"
],
"description": "An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and [reasoning tokens](/docs/guides/reasoning)."
},
"max_tokens": {
"type": [
"integer",
"null"
],
"description": "The maximum number of [tokens](/tokenizer) that can be generated in the chat completion. This value can be used to control [costs](https://openai.com/api/pricing/) for text generated via API. This value is now deprecated in favor of `max_completion_tokens`, and is not compatible with [o-series models](/docs/guides/reasoning)."
},
"messages": {
"type": "array",
"description": "A list of messages comprising the conversation so far. Depending on the [model](/docs/models) you use, different message types (modalities) are supported, like [text](/docs/guides/text-generation), [images](/docs/guides/vision), and [audio](/docs/guides/audio)."
},
"metadata": {
"type": "object",
"description": "Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters."
},
"modalities": {
"type": "array",
"items": {
"type": "string",
"enum": [
"text",
"audio"
]
},
"description": "Output types that you would like the model to generate. Most models are capable of generating text, which is the default: `[\"text\"]` The `gpt-4o-audio-preview` model can also be used to [generate audio](/docs/guides/audio). To request that this model generate both text and audio responses, you can use: `[\"text\", \"audio\"]`"
},
"model": {
"description": "The model value"
},
"n": {
"type": [
"integer",
"null"
],
"description": "How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep `n` as `1` to minimize costs."
},
"parallel_tool_calls": {
"type": "boolean",
"description": "Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use."
},
"prediction": {
"type": "object",
"description": "Configuration for a [Predicted Output](/docs/guides/predicted-outputs), which can greatly improve response times when large parts of the model response are known ahead of time. This is most common when you are regenerating a file with only minor changes to most of the content.",
"properties": {
"type": {
"type": "string",
"description": "The type of the predicted content you want to provide. This type is currently always `content`.",
"enum": [
"content"
]
},
"content": {
"description": "The content that should be matched when generating a model response. If generated tokens would match this content, the entire model response can be returned much more quickly."
}
},
"required": [
"type",
"content"
]
},
"presence_penalty": {
"type": [
"number",
"null"
],
"description": "Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics."
},
"reasoning_effort": {
"type": [
"string",
"null"
],
"description": "**o-series models only** Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `low`, `medium`, and `high`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.",
"enum": [
"low",
"medium",
"high"
]
},
"response_format": {
"description": "An object specifying the format that the model must output. Setting to `{ \"type\": \"json_schema\", \"json_schema\": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs). Setting to `{ \"type\": \"json_object\" }` enables the older JSON mode, which ensures the message the model generates is valid JSON. Using `json_schema` is preferred for models that support it."
},
"seed": {
"type": [
"integer",
"null"
],
"description": "This feature is in Beta. If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend."
},
"service_tier": {
"type": [
"string",
"null"
],
"description": "Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service: - If set to 'auto', and the Project is Scale tier enabled, the system will utilize scale tier credits until they are exhausted. - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. - If set to 'flex', the request will be processed with the Flex Processing service tier. [Learn more](/docs/guides/flex-processing). - When not set, the default behavior is 'auto'. When this parameter is set, the response body will include the `service_tier` utilized.",
"enum": [
"auto",
"default",
"flex"
]
},
"stop": {
"type": "array",
"items": {
"type": "string"
},
"description": "Not supported with latest reasoning models `o3` and `o4-mini`. Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence."
},
"store": {
"type": [
"boolean",
"null"
],
"description": "Whether or not to store the output of this chat completion request for use in our [model distillation](/docs/guides/distillation) or [evals](/docs/guides/evals) products."
},
"stream": {
"type": [
"boolean",
"null"
],
"description": "If set to true, the model response data will be streamed to the client as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). See the [Streaming section below](/docs/api-reference/chat/streaming) for more information, along with the [streaming responses](/docs/guides/streaming-responses) guide for more information on how to handle the streaming events."
},
"stream_options": {
"type": "object",
"description": "Options for streaming response. Only set this when you set `stream: true`.",
"properties": {
"include_usage": {
"type": "boolean",
"description": "If set, an additional chunk will be streamed before the `data: [DONE]` message. The `usage` field on this chunk shows the token usage statistics for the entire request, and the `choices` field will always be an empty array. All other chunks will also include a `usage` field, but with a null value. **NOTE:** If the stream is interrupted, you may not receive the final usage chunk which contains the total token usage for the request."
}
}
},
"temperature": {
"type": [
"number",
"null"
],
"description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic."
},
"tool_choice": {
"description": "Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. Specifying a particular tool via `{\"type\": \"function\", \"function\": {\"name\": \"my_function\"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present."
},
"tools": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"function"
],
"description": "The type of the tool. Currently, only `function` is supported."
},
"function": {
"type": "object",
"description": "The function value"
}
},
"required": [
"type",
"function"
]
},
"description": "A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported."
},
"top_logprobs": {
"type": [
"integer",
"null"
],
"description": "An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability. `logprobs` must be set to `true` if this parameter is used."
},
"top_p": {
"type": [
"number",
"null"
],
"description": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered."
},
"user": {
"type": "string",
"description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids)."
},
"web_search_options": {
"type": "object",
"description": "This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](/docs/guides/tools-web-search?api-mode=chat).",
"properties": {
"user_location": {
"type": "object",
"description": "Approximate location parameters for the search."
},
"search_context_size": {
"type": "string",
"description": "High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.",
"enum": [
"low",
"medium",
"high"
]
}
}
}
},
"required": [
"PCID",
"messages",
"model"
]
}
```
***
## openai\_ai\_create\_completion
Creates a completion for the provided prompt and parameters.
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ------------------- | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `best_of` | integer | null | No | — | Generates `best_of` completions server-side and returns the "best" (the one with the highest log probability per token). Results cannot be streamed. When used with `n`, `best_of` controls the number of candidate completions and `n` specifies how many to return – `best_of` must be greater than `n`. **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`. |
| `echo` | boolean | null | No | — | Echo back the prompt in addition to the completion |
| `frequency_penalty` | number | null | No | — | Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. See more information about frequency and presence penalties. |
| `logit_bias` | object | No | — | Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this tokenizer tool to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token. As an example, you can pass `{"50256": -100}` to prevent the \<\|endoftext\|> token from being generated. | |
| `logprobs` | integer | null | No | — | Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the `logprob` of the sampled token, so there may be up to `logprobs+1` elements in the response. The maximum value for `logprobs` is 5. |
| `max_tokens` | integer | null | No | — | The maximum number of tokens that can be generated in the completion. The token count of your prompt plus `max_tokens` cannot exceed the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. |
| `model` | object | Yes | — | ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them. | |
| `n` | integer | null | No | — | How many completions to generate for each prompt. **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`. |
| `presence_penalty` | number | null | No | — | Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. See more information about frequency and presence penalties. |
| `prompt` | object | Yes | — | The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays. Note that \<\|endoftext\|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document. | |
| `seed` | integer | null | No | — | If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend. |
| `stop` | string\[] | No | — | Not supported with latest reasoning models `o3` and `o4-mini`. Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence. | |
| `stream` | boolean | null | No | — | Whether to stream back partial progress. If set, tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions). |
| `stream_options` | object | No | — | Options for streaming response. Only set this when you set `stream: true`. | |
| `suffix` | string | null | No | — | The suffix that comes after a completion of inserted text. This parameter is only supported for `gpt-3.5-turbo-instruct`. |
| `temperature` | number | null | No | — | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. |
| `top_p` | number | null | No | — | An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top\_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both. |
| `user` | string | No | — | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"best_of": {
"type": [
"integer",
"null"
],
"description": "Generates `best_of` completions server-side and returns the \"best\" (the one with the highest log probability per token). Results cannot be streamed. When used with `n`, `best_of` controls the number of candidate completions and `n` specifies how many to return – `best_of` must be greater than `n`. **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`."
},
"echo": {
"type": [
"boolean",
"null"
],
"description": "Echo back the prompt in addition to the completion"
},
"frequency_penalty": {
"type": [
"number",
"null"
],
"description": "Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. [See more information about frequency and presence penalties.](/docs/guides/text-generation)"
},
"logit_bias": {
"type": "object",
"description": "Modify the likelihood of specified tokens appearing in the completion. Accepts a JSON object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this [tokenizer tool](/tokenizer?view=bpe) to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token. As an example, you can pass `{\"50256\": -100}` to prevent the <|endoftext|> token from being generated."
},
"logprobs": {
"type": [
"integer",
"null"
],
"description": "Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the `logprob` of the sampled token, so there may be up to `logprobs+1` elements in the response. The maximum value for `logprobs` is 5."
},
"max_tokens": {
"type": [
"integer",
"null"
],
"description": "The maximum number of [tokens](/tokenizer) that can be generated in the completion. The token count of your prompt plus `max_tokens` cannot exceed the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens."
},
"model": {
"description": "ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them."
},
"n": {
"type": [
"integer",
"null"
],
"description": "How many completions to generate for each prompt. **Note:** Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`."
},
"presence_penalty": {
"type": [
"number",
"null"
],
"description": "Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. [See more information about frequency and presence penalties.](/docs/guides/text-generation)"
},
"prompt": {
"description": "The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays. Note that <|endoftext|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document."
},
"seed": {
"type": [
"integer",
"null"
],
"description": "If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result. Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend."
},
"stop": {
"type": "array",
"items": {
"type": "string"
},
"description": "Not supported with latest reasoning models `o3` and `o4-mini`. Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence."
},
"stream": {
"type": [
"boolean",
"null"
],
"description": "Whether to stream back partial progress. If set, tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions)."
},
"stream_options": {
"type": "object",
"description": "Options for streaming response. Only set this when you set `stream: true`.",
"properties": {
"include_usage": {
"type": "boolean",
"description": "If set, an additional chunk will be streamed before the `data: [DONE]` message. The `usage` field on this chunk shows the token usage statistics for the entire request, and the `choices` field will always be an empty array. All other chunks will also include a `usage` field, but with a null value. **NOTE:** If the stream is interrupted, you may not receive the final usage chunk which contains the total token usage for the request."
}
}
},
"suffix": {
"type": [
"string",
"null"
],
"description": "The suffix that comes after a completion of inserted text. This parameter is only supported for `gpt-3.5-turbo-instruct`."
},
"temperature": {
"type": [
"number",
"null"
],
"description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both."
},
"top_p": {
"type": [
"number",
"null"
],
"description": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both."
},
"user": {
"type": "string",
"description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids)."
}
},
"required": [
"PCID",
"model",
"prompt"
]
}
```
***
## openai\_ai\_create\_embedding
Creates an embedding vector representing the input text.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dimensions` | integer | No | — | The number of dimensions the resulting output embeddings should have. Only supported in `text-embedding-3` and later models. |
| `encoding_format` | string | No | — | The format to return the embeddings in. Can be either `float` or [`base64`](https://pypi.org/project/pybase64/). |
| `input` | object | Yes | — | Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model (8192 tokens for `text-embedding-ada-002`), cannot be an empty string, and any array must be 2048 dimensions or less. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. Some models may also impose a limit on total number of tokens summed across inputs. |
| `model` | object | Yes | — | ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them. |
| `user` | string | No | — | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"dimensions": {
"type": "integer",
"description": "The number of dimensions the resulting output embeddings should have. Only supported in `text-embedding-3` and later models."
},
"encoding_format": {
"type": "string",
"description": "The format to return the embeddings in. Can be either `float` or [`base64`](https://pypi.org/project/pybase64/).",
"enum": [
"float",
"base64"
]
},
"input": {
"description": "Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model (8192 tokens for `text-embedding-ada-002`), cannot be an empty string, and any array must be 2048 dimensions or less. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. Some models may also impose a limit on total number of tokens summed across inputs."
},
"model": {
"description": "ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them."
},
"user": {
"type": "string",
"description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids)."
}
},
"required": [
"PCID",
"input",
"model"
]
}
```
***
## openai\_ai\_create\_image
Creates an image given a prompt. Learn more.
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| -------------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `background` | string | null | No | — | Allows to set transparency for the background of the generated image(s). This parameter is only supported for `gpt-image-1`. Must be one of `transparent`, `opaque` or `auto` (default value). When `auto` is used, the model will automatically determine the best background for the image. If `transparent`, the output format needs to support transparency, so it should be set to either `png` (default value) or `webp`. |
| `model` | object | No | — | The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or `gpt-image-1`. Defaults to `dall-e-2` unless a parameter specific to `gpt-image-1` is used. | |
| `moderation` | string | null | No | — | Control the content-moderation level for images generated by `gpt-image-1`. Must be either `low` for less restrictive filtering or `auto` (default value). |
| `n` | integer | null | No | — | The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only `n=1` is supported. |
| `output_compression` | integer | null | No | — | The compression level (0-100%) for the generated images. This parameter is only supported for `gpt-image-1` with the `webp` or `jpeg` output formats, and defaults to 100. |
| `output_format` | string | null | No | — | The format in which the generated images are returned. This parameter is only supported for `gpt-image-1`. Must be one of `png`, `jpeg`, or `webp`. |
| `prompt` | string | Yes | — | A text description of the desired image(s). The maximum length is 32000 characters for `gpt-image-1`, 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`. | |
| `quality` | string | null | No | — | The quality of the image that will be generated. - `auto` (default value) will automatically select the best quality for the given model. - `high`, `medium` and `low` are supported for `gpt-image-1`. - `hd` and `standard` are supported for `dall-e-3`. - `standard` is the only option for `dall-e-2`. |
| `response_format` | string | null | No | — | The format in which generated images with `dall-e-2` and `dall-e-3` are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. This parameter isn't supported for `gpt-image-1` which will always return base64-encoded images. |
| `size` | string | null | No | — | The size of the generated images. Must be one of `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or `auto` (default value) for `gpt-image-1`, one of `256x256`, `512x512`, or `1024x1024` for `dall-e-2`, and one of `1024x1024`, `1792x1024`, or `1024x1792` for `dall-e-3`. |
| `style` | string | null | No | — | The style of the generated images. This parameter is only supported for `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images. |
| `user` | string | No | — | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"background": {
"type": [
"string",
"null"
],
"description": "Allows to set transparency for the background of the generated image(s). This parameter is only supported for `gpt-image-1`. Must be one of `transparent`, `opaque` or `auto` (default value). When `auto` is used, the model will automatically determine the best background for the image. If `transparent`, the output format needs to support transparency, so it should be set to either `png` (default value) or `webp`.",
"enum": [
"transparent",
"opaque",
"auto"
]
},
"model": {
"description": "The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or `gpt-image-1`. Defaults to `dall-e-2` unless a parameter specific to `gpt-image-1` is used."
},
"moderation": {
"type": [
"string",
"null"
],
"description": "Control the content-moderation level for images generated by `gpt-image-1`. Must be either `low` for less restrictive filtering or `auto` (default value).",
"enum": [
"low",
"auto"
]
},
"n": {
"type": [
"integer",
"null"
],
"description": "The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only `n=1` is supported."
},
"output_compression": {
"type": [
"integer",
"null"
],
"description": "The compression level (0-100%) for the generated images. This parameter is only supported for `gpt-image-1` with the `webp` or `jpeg` output formats, and defaults to 100."
},
"output_format": {
"type": [
"string",
"null"
],
"description": "The format in which the generated images are returned. This parameter is only supported for `gpt-image-1`. Must be one of `png`, `jpeg`, or `webp`.",
"enum": [
"png",
"jpeg",
"webp"
]
},
"prompt": {
"type": "string",
"description": "A text description of the desired image(s). The maximum length is 32000 characters for `gpt-image-1`, 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`."
},
"quality": {
"type": [
"string",
"null"
],
"description": "The quality of the image that will be generated. - `auto` (default value) will automatically select the best quality for the given model. - `high`, `medium` and `low` are supported for `gpt-image-1`. - `hd` and `standard` are supported for `dall-e-3`. - `standard` is the only option for `dall-e-2`.",
"enum": [
"standard",
"hd",
"low",
"medium",
"high",
"auto"
]
},
"response_format": {
"type": [
"string",
"null"
],
"description": "The format in which generated images with `dall-e-2` and `dall-e-3` are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. This parameter isn't supported for `gpt-image-1` which will always return base64-encoded images.",
"enum": [
"url",
"b64_json"
]
},
"size": {
"type": [
"string",
"null"
],
"description": "The size of the generated images. Must be one of `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or `auto` (default value) for `gpt-image-1`, one of `256x256`, `512x512`, or `1024x1024` for `dall-e-2`, and one of `1024x1024`, `1792x1024`, or `1024x1792` for `dall-e-3`.",
"enum": [
"auto",
"1024x1024",
"1536x1024",
"1024x1536",
"256x256",
"512x512",
"1792x1024",
"1024x1792"
]
},
"style": {
"type": [
"string",
"null"
],
"description": "The style of the generated images. This parameter is only supported for `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images.",
"enum": [
"vivid",
"natural"
]
},
"user": {
"type": "string",
"description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids)."
}
},
"required": [
"PCID",
"prompt"
]
}
```
***
## openai\_ai\_create\_image\_variation
Creates a variation of a given image. This endpoint only supports `dall-e-2`.
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ----------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image` | string | Yes | — | The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square. | |
| `model` | object | No | — | The model to use for image generation. Only `dall-e-2` is supported at this time. | |
| `n` | integer | null | No | — | The number of images to generate. Must be between 1 and 10. |
| `response_format` | string | null | No | — | The format in which the generated images are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. |
| `size` | string | null | No | — | The size of the generated images. Must be one of `256x256`, `512x512`, or `1024x1024`. |
| `user` | string | No | — | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"image": {
"type": "string",
"description": "The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square."
},
"model": {
"description": "The model to use for image generation. Only `dall-e-2` is supported at this time."
},
"n": {
"type": [
"integer",
"null"
],
"description": "The number of images to generate. Must be between 1 and 10."
},
"response_format": {
"type": [
"string",
"null"
],
"description": "The format in which the generated images are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated.",
"enum": [
"url",
"b64_json"
]
},
"size": {
"type": [
"string",
"null"
],
"description": "The size of the generated images. Must be one of `256x256`, `512x512`, or `1024x1024`.",
"enum": [
"256x256",
"512x512",
"1024x1024"
]
},
"user": {
"type": "string",
"description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids)."
}
},
"required": [
"PCID",
"image"
]
}
```
***
## openai\_ai\_create\_moderation
Classifies if text and/or image inputs are potentially harmful. Learn more in the moderation guide.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `input` | object | Yes | — | Input (or inputs) to classify. Can be a single string, an array of strings, or an array of multi-modal input objects similar to other models. |
| `model` | object | No | — | The content moderation model you would like to use. Learn more in the moderation guide, and learn about available models here. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"input": {
"description": "Input (or inputs) to classify. Can be a single string, an array of strings, or an array of multi-modal input objects similar to other models."
},
"model": {
"description": "The content moderation model you would like to use. Learn more in [the moderation guide](/docs/guides/moderation), and learn about available models [here](/docs/models#moderation)."
}
},
"required": [
"PCID",
"input"
]
}
```
***
## openai\_ai\_create\_realtime\_session
Create an ephemeral API token for use in client-side applications with the Realtime API. Can be configured with the same session parameters as the `session.update` client event. It responds with a session object, plus a `client_secret` key which contains a usable ephemeral API token that can be used to authenticate browser clients for the Realtime API.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------------------- | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input_audio_format` | string | No | — | The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, single channel (mono), and little-endian byte order. |
| `input_audio_noise_reduction` | object | No | — | Configuration for input audio noise reduction. This can be set to `null` to turn off. Noise reduction filters audio added to the input audio buffer before it is sent to VAD and the model. Filtering the audio can improve VAD and turn detection accuracy (reducing false positives) and model performance by improving perception of the input audio. |
| `input_audio_transcription` | object | No | — | Configuration for input audio transcription, defaults to off and can be set to `null` to turn off once on. Input audio transcription is not native to the model, since the model consumes audio directly. Transcription runs asynchronously through [the /audio/transcriptions endpoint](https://platform.openai.com/docs/api-reference/audio/createTranscription) and should be treated as guidance of input audio content rather than precisely what the model heard. The client can optionally set the language and prompt for transcription, these offer additional guidance to the transcription service. |
| `instructions` | string | No | — | 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. 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. |
| `max_response_output_tokens` | object | No | — | Maximum number of output tokens for a single assistant response, inclusive of tool calls. Provide an integer between 1 and 4096 to limit output tokens, or `inf` for the maximum available tokens for a given model. Defaults to `inf`. |
| `modalities` | object | No | — | The set of modalities the model can respond with. To disable audio, set this to \["text"]. |
| `model` | string | No | — | The Realtime model used for this session. |
| `output_audio_format` | string | No | — | The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. For `pcm16`, output audio is sampled at a rate of 24kHz. |
| `temperature` | number | No | — | Sampling temperature for the model, limited to \[0.6, 1.2]. For audio models a temperature of 0.8 is highly recommended for best performance. |
| `tool_choice` | string | No | — | How the model chooses tools. Options are `auto`, `none`, `required`, or specify a function. |
| `tools` | object\[] | No | — | Tools (functions) available to the model. |
| `turn_detection` | object | No | — | 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. 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. Semantic VAD is more advanced and uses a turn detection model (in conjuction 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. |
| `voice` | object | No | — | The voice value |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"input_audio_format": {
"type": "string",
"description": "The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, single channel (mono), and little-endian byte order.",
"enum": [
"pcm16",
"g711_ulaw",
"g711_alaw"
]
},
"input_audio_noise_reduction": {
"type": "object",
"description": "Configuration for input audio noise reduction. This can be set to `null` to turn off. Noise reduction filters audio added to the input audio buffer before it is sent to VAD and the model. Filtering the audio can improve VAD and turn detection accuracy (reducing false positives) and model performance by improving perception of the input audio.",
"properties": {
"type": {
"type": "string",
"description": "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.",
"enum": [
"near_field",
"far_field"
]
}
}
},
"input_audio_transcription": {
"type": "object",
"description": "Configuration for input audio transcription, defaults to off and can be set to `null` to turn off once on. Input audio transcription is not native to the model, since the model consumes audio directly. Transcription runs asynchronously through [the /audio/transcriptions endpoint](https://platform.openai.com/docs/api-reference/audio/createTranscription) and should be treated as guidance of input audio content rather than precisely what the model heard. The client can optionally set the language and prompt for transcription, these offer additional guidance to the transcription service.",
"properties": {
"model": {
"type": "string",
"description": "The model to use for transcription, current options are `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, and `whisper-1`."
},
"language": {
"type": "string",
"description": "The language of the input audio. Supplying the input language in [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format will improve accuracy and latency."
},
"prompt": {
"type": "string",
"description": "An optional text to guide the model's style or continue a previous audio segment. For `whisper-1`, the [prompt is a list of keywords](/docs/guides/speech-to-text#prompting). For `gpt-4o-transcribe` models, the prompt is a free text string, for example \"expect words related to technology\"."
}
}
},
"instructions": {
"type": "string",
"description": "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. 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."
},
"max_response_output_tokens": {
"description": "Maximum number of output tokens for a single assistant response, inclusive of tool calls. Provide an integer between 1 and 4096 to limit output tokens, or `inf` for the maximum available tokens for a given model. Defaults to `inf`."
},
"modalities": {
"description": "The set of modalities the model can respond with. To disable audio, set this to [\"text\"]."
},
"model": {
"type": "string",
"description": "The Realtime model used for this session.",
"enum": [
"gpt-4o-realtime-preview",
"gpt-4o-realtime-preview-2024-10-01",
"gpt-4o-realtime-preview-2024-12-17",
"gpt-4o-mini-realtime-preview",
"gpt-4o-mini-realtime-preview-2024-12-17"
]
},
"output_audio_format": {
"type": "string",
"description": "The format of output audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. For `pcm16`, output audio is sampled at a rate of 24kHz.",
"enum": [
"pcm16",
"g711_ulaw",
"g711_alaw"
]
},
"temperature": {
"type": "number",
"description": "Sampling temperature for the model, limited to [0.6, 1.2]. For audio models a temperature of 0.8 is highly recommended for best performance."
},
"tool_choice": {
"type": "string",
"description": "How the model chooses tools. Options are `auto`, `none`, `required`, or specify a function."
},
"tools": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"function"
],
"description": "The type of the tool, i.e. `function`."
},
"name": {
"type": "string",
"description": "The name of the function."
},
"description": {
"type": "string",
"description": "The description of the function, including guidance on when and how to call it, and guidance about what to tell the user when calling (if anything)."
},
"parameters": {
"type": "object",
"description": "Parameters of the function in JSON Schema."
}
}
},
"description": "Tools (functions) available to the model."
},
"turn_detection": {
"type": "object",
"description": "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. 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. Semantic VAD is more advanced and uses a turn detection model (in conjuction 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.",
"properties": {
"type": {
"type": "string",
"description": "Type of turn detection.",
"enum": [
"server_vad",
"semantic_vad"
]
},
"eagerness": {
"type": "string",
"description": "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`.",
"enum": [
"low",
"medium",
"high",
"auto"
]
},
"threshold": {
"type": "number",
"description": "Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A higher threshold will require louder audio to activate the model, and thus might perform better in noisy environments."
},
"prefix_padding_ms": {
"type": "integer",
"description": "Used only for `server_vad` mode. Amount of audio to include before the VAD detected speech (in milliseconds). Defaults to 300ms."
},
"silence_duration_ms": {
"type": "integer",
"description": "Used only for `server_vad` mode. Duration of silence to detect speech stop (in milliseconds). Defaults to 500ms. With shorter values the model will respond more quickly, but may jump in on short pauses from the user."
},
"create_response": {
"type": "boolean",
"description": "Whether or not to automatically generate a response when a VAD stop event occurs."
},
"interrupt_response": {
"type": "boolean",
"description": "Whether or not to automatically interrupt any ongoing response with output to the default conversation (i.e. `conversation` of `auto`) when a VAD start event occurs."
}
}
},
"voice": {
"description": "The voice value"
}
},
"required": [
"PCID"
]
}
```
***
## openai\_ai\_create\_realtime\_transcription\_session
Create an ephemeral API token for use in client-side applications with the Realtime API specifically for realtime transcriptions. Can be configured with the same session parameters as the `transcription_session.update` client event. It responds with a session object, plus a `client_secret` key which contains a usable ephemeral API token that can be used to authenticate browser clients for the Realtime API.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------------------- | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include` | string\[] | No | — | The set of items to include in the transcription. Current available items are: - `item.input_audio_transcription.logprobs` |
| `input_audio_format` | string | No | — | The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, single channel (mono), and little-endian byte order. |
| `input_audio_noise_reduction` | object | No | — | Configuration for input audio noise reduction. This can be set to `null` to turn off. Noise reduction filters audio added to the input audio buffer before it is sent to VAD and the model. Filtering the audio can improve VAD and turn detection accuracy (reducing false positives) and model performance by improving perception of the input audio. |
| `input_audio_transcription` | object | No | — | Configuration for input audio transcription. The client can optionally set the language and prompt for transcription, these offer additional guidance to the transcription service. |
| `modalities` | object | No | — | The set of modalities the model can respond with. To disable audio, set this to \["text"]. |
| `turn_detection` | object | No | — | 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. 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. Semantic VAD is more advanced and uses a turn detection model (in conjuction 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. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"include": {
"type": "array",
"items": {
"type": "string"
},
"description": "The set of items to include in the transcription. Current available items are: - `item.input_audio_transcription.logprobs`"
},
"input_audio_format": {
"type": "string",
"description": "The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`. For `pcm16`, input audio must be 16-bit PCM at a 24kHz sample rate, single channel (mono), and little-endian byte order.",
"enum": [
"pcm16",
"g711_ulaw",
"g711_alaw"
]
},
"input_audio_noise_reduction": {
"type": "object",
"description": "Configuration for input audio noise reduction. This can be set to `null` to turn off. Noise reduction filters audio added to the input audio buffer before it is sent to VAD and the model. Filtering the audio can improve VAD and turn detection accuracy (reducing false positives) and model performance by improving perception of the input audio.",
"properties": {
"type": {
"type": "string",
"description": "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.",
"enum": [
"near_field",
"far_field"
]
}
}
},
"input_audio_transcription": {
"type": "object",
"description": "Configuration for input audio transcription. The client can optionally set the language and prompt for transcription, these offer additional guidance to the transcription service.",
"properties": {
"model": {
"type": "string",
"description": "The model to use for transcription, current options are `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, and `whisper-1`.",
"enum": [
"gpt-4o-transcribe",
"gpt-4o-mini-transcribe",
"whisper-1"
]
},
"language": {
"type": "string",
"description": "The language of the input audio. Supplying the input language in [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format will improve accuracy and latency."
},
"prompt": {
"type": "string",
"description": "An optional text to guide the model's style or continue a previous audio segment. For `whisper-1`, the [prompt is a list of keywords](/docs/guides/speech-to-text#prompting). For `gpt-4o-transcribe` models, the prompt is a free text string, for example \"expect words related to technology\"."
}
}
},
"modalities": {
"description": "The set of modalities the model can respond with. To disable audio, set this to [\"text\"]."
},
"turn_detection": {
"type": "object",
"description": "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. 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. Semantic VAD is more advanced and uses a turn detection model (in conjuction 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.",
"properties": {
"type": {
"type": "string",
"description": "Type of turn detection.",
"enum": [
"server_vad",
"semantic_vad"
]
},
"eagerness": {
"type": "string",
"description": "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`.",
"enum": [
"low",
"medium",
"high",
"auto"
]
},
"threshold": {
"type": "number",
"description": "Used only for `server_vad` mode. Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A higher threshold will require louder audio to activate the model, and thus might perform better in noisy environments."
},
"prefix_padding_ms": {
"type": "integer",
"description": "Used only for `server_vad` mode. Amount of audio to include before the VAD detected speech (in milliseconds). Defaults to 300ms."
},
"silence_duration_ms": {
"type": "integer",
"description": "Used only for `server_vad` mode. Duration of silence to detect speech stop (in milliseconds). Defaults to 500ms. With shorter values the model will respond more quickly, but may jump in on short pauses from the user."
},
"create_response": {
"type": "boolean",
"description": "Whether or not to automatically generate a response when a VAD stop event occurs. Not available for transcription sessions."
},
"interrupt_response": {
"type": "boolean",
"description": "Whether or not to automatically interrupt any ongoing response with output to the default conversation (i.e. `conversation` of `auto`) when a VAD start event occurs. Not available for transcription sessions."
}
}
}
},
"required": [
"PCID"
]
}
```
***
## openai\_ai\_create\_response
Creates a model response. Provide text or image inputs to generate text or JSON outputs. Have the model call your own custom code or use built-in tools like web search or file search to use your own data as input for the model's response.
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| ---------------------- | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include` | string\[] | No | — | Specify additional output data to include in the model response. Currently supported values are: file\_search\_call.results, message.input\_image.image\_url, computer\_call\_output.output.image\_url. | |
| `input` | object | Yes | — | Text, image, or file inputs to the model, used to generate a response. Learn more: - Text inputs and outputs - Image inputs - File inputs - Conversation state - Function calling | |
| `instructions` | string | null | No | — | Inserts a system (or developer) message as the first item in the model's context. When using along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. |
| `max_output_tokens` | integer | null | No | — | An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. |
| `metadata` | object | No | — | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. | |
| `model` | object | Yes | — | The model value | |
| `parallel_tool_calls` | boolean | null | No | — | Whether to allow the model to run tool calls in parallel. |
| `previous_response_id` | string | null | No | — | The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about conversation state. |
| `reasoning` | object | No | — | **o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). | |
| `service_tier` | string | null | No | — | Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service: - If set to 'auto', and the Project is Scale tier enabled, the system will utilize scale tier credits until they are exhausted. - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. - If set to 'flex', the request will be processed with the Flex Processing service tier. Learn more. - When not set, the default behavior is 'auto'. When this parameter is set, the response body will include the `service_tier` utilized. |
| `store` | boolean | null | No | — | Whether to store the generated model response for later retrieval via API. |
| `stream` | boolean | null | No | — | If set to true, the model response data will be streamed to the client as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). See the Streaming section below for more information. |
| `temperature` | number | null | No | — | What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both. |
| `text` | object | No | — | Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - Text inputs and outputs - Structured Outputs | |
| `tool_choice` | object | No | — | How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools the model can call. | |
| `tools` | any\[] | No | — | An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. The two categories of tools you can provide the model are: - **Built-in tools**: Tools that are provided by OpenAI that extend the model's capabilities, like web search or file search. Learn more about built-in tools. - **Function calls (custom tools)**: Functions that are defined by you, enabling the model to call your own code. Learn more about function calling. | |
| `top_p` | number | null | No | — | An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top\_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both. |
| `truncation` | string | null | No | — | The truncation strategy to use for the model response. - `auto`: If the context of this response and previous ones exceeds the model's context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - `disabled` (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. |
| `user` | string | No | — | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"include": {
"type": "array",
"items": {
"type": "string"
},
"description": "Specify additional output data to include in the model response. Currently supported values are: file_search_call.results, message.input_image.image_url, computer_call_output.output.image_url."
},
"input": {
"description": "Text, image, or file inputs to the model, used to generate a response. Learn more: - [Text inputs and outputs](/docs/guides/text) - [Image inputs](/docs/guides/images) - [File inputs](/docs/guides/pdf-files) - [Conversation state](/docs/guides/conversation-state) - [Function calling](/docs/guides/function-calling)"
},
"instructions": {
"type": [
"string",
"null"
],
"description": "Inserts a system (or developer) message as the first item in the model's context. When using along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses."
},
"max_output_tokens": {
"type": [
"integer",
"null"
],
"description": "An upper bound for the number of tokens that can be generated for a response, including visible output tokens and [reasoning tokens](/docs/guides/reasoning)."
},
"metadata": {
"type": "object",
"description": "Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters."
},
"model": {
"description": "The model value"
},
"parallel_tool_calls": {
"type": [
"boolean",
"null"
],
"description": "Whether to allow the model to run tool calls in parallel."
},
"previous_response_id": {
"type": [
"string",
"null"
],
"description": "The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](/docs/guides/conversation-state)."
},
"reasoning": {
"type": "object",
"description": "**o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning).",
"properties": {
"effort": {
"type": "string",
"description": "**o-series models only** Constrains effort on reasoning for [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently supported values are `low`, `medium`, and `high`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.",
"enum": [
"low",
"medium",
"high"
]
},
"summary": {
"type": "string",
"description": "A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of `auto`, `concise`, or `detailed`.",
"enum": [
"auto",
"concise",
"detailed"
]
},
"generate_summary": {
"type": "string",
"description": "**Deprecated:** use `summary` instead. A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of `auto`, `concise`, or `detailed`.",
"enum": [
"auto",
"concise",
"detailed"
]
}
}
},
"service_tier": {
"type": [
"string",
"null"
],
"description": "Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service: - If set to 'auto', and the Project is Scale tier enabled, the system will utilize scale tier credits until they are exhausted. - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. - If set to 'flex', the request will be processed with the Flex Processing service tier. [Learn more](/docs/guides/flex-processing). - When not set, the default behavior is 'auto'. When this parameter is set, the response body will include the `service_tier` utilized.",
"enum": [
"auto",
"default",
"flex"
]
},
"store": {
"type": [
"boolean",
"null"
],
"description": "Whether to store the generated model response for later retrieval via API."
},
"stream": {
"type": [
"boolean",
"null"
],
"description": "If set to true, the model response data will be streamed to the client as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). See the [Streaming section below](/docs/api-reference/responses-streaming) for more information."
},
"temperature": {
"type": [
"number",
"null"
],
"description": "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both."
},
"text": {
"type": "object",
"description": "Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - [Text inputs and outputs](/docs/guides/text) - [Structured Outputs](/docs/guides/structured-outputs)",
"properties": {
"format": {
"description": "An object specifying the format that the model must output. Configuring `{ \"type\": \"json_schema\" }` enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](/docs/guides/structured-outputs). The default format is `{ \"type\": \"text\" }` with no additional options. **Not recommended for gpt-4o and newer models:** Setting to `{ \"type\": \"json_object\" }` enables the older JSON mode, which ensures the message the model generates is valid JSON. Using `json_schema` is preferred for models that support it."
}
}
},
"tool_choice": {
"description": "How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools the model can call."
},
"tools": {
"type": "array",
"description": "An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. The two categories of tools you can provide the model are: - **Built-in tools**: Tools that are provided by OpenAI that extend the model's capabilities, like [web search](/docs/guides/tools-web-search) or [file search](/docs/guides/tools-file-search). Learn more about [built-in tools](/docs/guides/tools). - **Function calls (custom tools)**: Functions that are defined by you, enabling the model to call your own code. Learn more about [function calling](/docs/guides/function-calling)."
},
"top_p": {
"type": [
"number",
"null"
],
"description": "An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both."
},
"truncation": {
"type": [
"string",
"null"
],
"description": "The truncation strategy to use for the model response. - `auto`: If the context of this response and previous ones exceeds the model's context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. - `disabled` (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error.",
"enum": [
"auto",
"disabled"
]
},
"user": {
"type": "string",
"description": "A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids)."
}
},
"required": [
"PCID",
"input",
"model"
]
}
```
***
## openai\_ai\_create\_speech
Generates audio from the input text.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `input` | string | Yes | — | The text to generate audio for. The maximum length is 4096 characters. |
| `instructions` | string | No | — | Control the voice of your generated audio with additional instructions. Does not work with `tts-1` or `tts-1-hd`. |
| `model` | object | Yes | — | One of the available TTS models: `tts-1`, `tts-1-hd` or `gpt-4o-mini-tts`. |
| `response_format` | string | No | — | The format to audio in. Supported formats are `mp3`, `opus`, `aac`, `flac`, `wav`, and `pcm`. |
| `speed` | number | No | — | The speed of the generated audio. Select a value from `0.25` to `4.0`. `1.0` is the default. |
| `voice` | object | Yes | — | The voice value |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"input": {
"type": "string",
"description": "The text to generate audio for. The maximum length is 4096 characters."
},
"instructions": {
"type": "string",
"description": "Control the voice of your generated audio with additional instructions. Does not work with `tts-1` or `tts-1-hd`."
},
"model": {
"description": "One of the available [TTS models](/docs/models#tts): `tts-1`, `tts-1-hd` or `gpt-4o-mini-tts`."
},
"response_format": {
"type": "string",
"description": "The format to audio in. Supported formats are `mp3`, `opus`, `aac`, `flac`, `wav`, and `pcm`.",
"enum": [
"mp3",
"opus",
"aac",
"flac",
"wav",
"pcm"
]
},
"speed": {
"type": "number",
"description": "The speed of the generated audio. Select a value from `0.25` to `4.0`. `1.0` is the default."
},
"voice": {
"description": "The voice value"
}
},
"required": [
"PCID",
"input",
"model",
"voice"
]
}
```
***
## openai\_ai\_create\_transcription
Transcribes audio into the input language.
**Parameters:**
| Parameter | Type | Required | Default | Description | |
| --------------------------- | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file` | string | Yes | — | The audio file object (not file name) to transcribe, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. | |
| `include[]` | string\[] | No | — | Additional information to include in the transcription response. `logprobs` will return the log probabilities of the tokens in the response to understand the model's confidence in the transcription. `logprobs` only works with response\_format set to `json` and only with the models `gpt-4o-transcribe` and `gpt-4o-mini-transcribe`. | |
| `language` | string | No | — | The language of the input audio. Supplying the input language in [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format will improve accuracy and latency. | |
| `model` | object | Yes | — | ID of the model to use. The options are `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, and `whisper-1` (which is powered by our open source Whisper V2 model). | |
| `prompt` | string | No | — | An optional text to guide the model's style or continue a previous audio segment. The prompt should match the audio language. | |
| `response_format` | string | No | — | The format of the output, in one of these options: `json`, `text`, `srt`, `verbose_json`, or `vtt`. For `gpt-4o-transcribe` and `gpt-4o-mini-transcribe`, the only supported format is `json`. | |
| `stream` | boolean | null | No | — | If set to true, the model response data will be streamed to the client as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). See the Streaming section of the Speech-to-Text guide for more information. Note: Streaming is not supported for the `whisper-1` model and will be ignored. |
| `temperature` | number | No | — | The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use [log probability](https://en.wikipedia.org/wiki/Log_probability) to automatically increase the temperature until certain thresholds are hit. | |
| `timestamp_granularities[]` | string\[] | No | — | The timestamp granularities to populate for this transcription. `response_format` must be set `verbose_json` to use timestamp granularities. Either or both of these options are supported: `word`, or `segment`. Note: There is no additional latency for segment timestamps, but generating word timestamps incurs additional latency. | |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"file": {
"type": "string",
"description": "The audio file object (not file name) to transcribe, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm."
},
"include[]": {
"type": "array",
"items": {
"type": "string",
"enum": [
"logprobs"
]
},
"description": "Additional information to include in the transcription response. `logprobs` will return the log probabilities of the tokens in the response to understand the model's confidence in the transcription. `logprobs` only works with response_format set to `json` and only with the models `gpt-4o-transcribe` and `gpt-4o-mini-transcribe`."
},
"language": {
"type": "string",
"description": "The language of the input audio. Supplying the input language in [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) format will improve accuracy and latency."
},
"model": {
"description": "ID of the model to use. The options are `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, and `whisper-1` (which is powered by our open source Whisper V2 model)."
},
"prompt": {
"type": "string",
"description": "An optional text to guide the model's style or continue a previous audio segment. The [prompt](/docs/guides/speech-to-text#prompting) should match the audio language."
},
"response_format": {
"type": "string",
"description": "The format of the output, in one of these options: `json`, `text`, `srt`, `verbose_json`, or `vtt`. For `gpt-4o-transcribe` and `gpt-4o-mini-transcribe`, the only supported format is `json`.",
"enum": [
"json",
"text",
"srt",
"verbose_json",
"vtt"
]
},
"stream": {
"type": [
"boolean",
"null"
],
"description": "If set to true, the model response data will be streamed to the client as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). See the [Streaming section of the Speech-to-Text guide](/docs/guides/speech-to-text?lang=curl#streaming-transcriptions) for more information. Note: Streaming is not supported for the `whisper-1` model and will be ignored."
},
"temperature": {
"type": "number",
"description": "The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use [log probability](https://en.wikipedia.org/wiki/Log_probability) to automatically increase the temperature until certain thresholds are hit."
},
"timestamp_granularities[]": {
"type": "array",
"items": {
"type": "string",
"enum": [
"word",
"segment"
]
},
"description": "The timestamp granularities to populate for this transcription. `response_format` must be set `verbose_json` to use timestamp granularities. Either or both of these options are supported: `word`, or `segment`. Note: There is no additional latency for segment timestamps, but generating word timestamps incurs additional latency."
}
},
"required": [
"PCID",
"file",
"model"
]
}
```
***
## openai\_ai\_create\_translation
Translates audio into English.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file` | string | Yes | — | The audio file object (not file name) translate, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm. |
| `model` | object | Yes | — | ID of the model to use. Only `whisper-1` (which is powered by our open source Whisper V2 model) is currently available. |
| `prompt` | string | No | — | An optional text to guide the model's style or continue a previous audio segment. The prompt should be in English. |
| `response_format` | string | No | — | The format of the output, in one of these options: `json`, `text`, `srt`, `verbose_json`, or `vtt`. |
| `temperature` | number | No | — | The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use [log probability](https://en.wikipedia.org/wiki/Log_probability) to automatically increase the temperature until certain thresholds are hit. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"file": {
"type": "string",
"description": "The audio file object (not file name) translate, in one of these formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm."
},
"model": {
"description": "ID of the model to use. Only `whisper-1` (which is powered by our open source Whisper V2 model) is currently available."
},
"prompt": {
"type": "string",
"description": "An optional text to guide the model's style or continue a previous audio segment. The [prompt](/docs/guides/speech-to-text#prompting) should be in English."
},
"response_format": {
"type": "string",
"description": "The format of the output, in one of these options: `json`, `text`, `srt`, `verbose_json`, or `vtt`.",
"enum": [
"json",
"text",
"srt",
"verbose_json",
"vtt"
]
},
"temperature": {
"type": "number",
"description": "The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use [log probability](https://en.wikipedia.org/wiki/Log_probability) to automatically increase the temperature until certain thresholds are hit."
}
},
"required": [
"PCID",
"file",
"model"
]
}
```
***
## openai\_ai\_delete\_chat\_completion
Delete a stored chat completion. Only Chat Completions that have been created with the `store` parameter set to `true` can be deleted.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------- | ------ | -------- | ------- | ---------------------------------------- |
| `completion_id` | string | Yes | — | The ID of the chat completion to delete. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"completion_id": {
"type": "string",
"description": "The ID of the chat completion to delete."
}
},
"required": [
"PCID",
"completion_id"
]
}
```
***
## openai\_ai\_delete\_model
Delete a fine-tuned model. You must have the Owner role in your organization to delete a model.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ------------------- |
| `model` | string | Yes | — | The model to delete |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"model": {
"type": "string",
"description": "The model to delete"
}
},
"required": [
"PCID",
"model"
]
}
```
***
## openai\_ai\_delete\_response
Deletes a model response with the given ID.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | ------ | -------- | ------- | --------------------------------- |
| `response_id` | string | Yes | — | The ID of the response to delete. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"response_id": {
"type": "string",
"description": "The ID of the response to delete."
}
},
"required": [
"PCID",
"response_id"
]
}
```
***
## openai\_ai\_get\_chat\_completion
Get a stored chat completion. Only Chat Completions that have been created with the `store` parameter set to `true` will be returned.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------- | ------ | -------- | ------- | ------------------------------------------ |
| `completion_id` | string | Yes | — | The ID of the chat completion to retrieve. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"completion_id": {
"type": "string",
"description": "The ID of the chat completion to retrieve."
}
},
"required": [
"PCID",
"completion_id"
]
}
```
***
## openai\_ai\_get\_chat\_completion\_messages
Get the messages in a stored chat completion. Only Chat Completions that have been created with the `store` parameter set to `true` will be returned.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `completion_id` | string | Yes | — | The ID of the chat completion to retrieve messages from. |
| `after` | string | No | — | Identifier for the last message from the previous pagination request. |
| `limit` | integer | No | — | Number of messages to retrieve. |
| `order` | string | No | — | Sort order for messages by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"completion_id": {
"type": "string",
"description": "The ID of the chat completion to retrieve messages from."
},
"after": {
"type": "string",
"description": "Identifier for the last message from the previous pagination request."
},
"limit": {
"type": "integer",
"description": "Number of messages to retrieve."
},
"order": {
"type": "string",
"description": "Sort order for messages by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.",
"enum": [
"asc",
"desc"
]
}
},
"required": [
"PCID",
"completion_id"
]
}
```
***
## openai\_ai\_get\_response
Retrieves a model response with the given ID.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `response_id` | string | Yes | — | The ID of the response to retrieve. |
| `include` | string\[] | No | — | Additional fields to include in the response. See the `include` parameter for Response creation above for more information. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"response_id": {
"type": "string",
"description": "The ID of the response to retrieve."
},
"include": {
"type": "array",
"items": {
"type": "string",
"enum": [
"file_search_call.results",
"message.input_image.image_url",
"computer_call_output.output.image_url"
]
},
"description": "Additional fields to include in the response. See the `include` parameter for Response creation above for more information."
}
},
"required": [
"PCID",
"response_id"
]
}
```
***
## openai\_ai\_list\_chat\_completions
List stored Chat Completions. Only Chat Completions that have been stored with the `store` parameter set to `true` will be returned.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ---------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `model` | string | No | — | The model used to generate the Chat Completions. |
| `metadata` | object | No | — | A list of metadata keys to filter the Chat Completions by. Example: `metadata[key1]=value1&metadata[key2]=value2` |
| `after` | string | No | — | Identifier for the last chat completion from the previous pagination request. |
| `limit` | integer | No | — | Number of Chat Completions to retrieve. |
| `order` | string | No | — | Sort order for Chat Completions by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"model": {
"type": "string",
"description": "The model used to generate the Chat Completions."
},
"metadata": {
"type": "object",
"description": "A list of metadata keys to filter the Chat Completions by. Example: `metadata[key1]=value1&metadata[key2]=value2`"
},
"after": {
"type": "string",
"description": "Identifier for the last chat completion from the previous pagination request."
},
"limit": {
"type": "integer",
"description": "Number of Chat Completions to retrieve."
},
"order": {
"type": "string",
"description": "Sort order for Chat Completions by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.",
"enum": [
"asc",
"desc"
]
}
},
"required": [
"PCID"
]
}
```
***
## openai\_ai\_list\_input\_items
Returns a list of input items for a given response.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ------------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_id` | string | Yes | — | The ID of the response to retrieve input items for. |
| `limit` | integer | No | — | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. |
| `order` | string | No | — | The order to return the input items in. Default is `asc`. - `asc`: Return the input items in ascending order. - `desc`: Return the input items in descending order. |
| `after` | string | No | — | An item ID to list items after, used in pagination. |
| `before` | string | No | — | An item ID to list items before, used in pagination. |
| `include` | string\[] | No | — | Additional fields to include in the response. See the `include` parameter for Response creation above for more information. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"response_id": {
"type": "string",
"description": "The ID of the response to retrieve input items for."
},
"limit": {
"type": "integer",
"description": "A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20."
},
"order": {
"type": "string",
"description": "The order to return the input items in. Default is `asc`. - `asc`: Return the input items in ascending order. - `desc`: Return the input items in descending order.",
"enum": [
"asc",
"desc"
]
},
"after": {
"type": "string",
"description": "An item ID to list items after, used in pagination."
},
"before": {
"type": "string",
"description": "An item ID to list items before, used in pagination."
},
"include": {
"type": "array",
"items": {
"type": "string",
"enum": [
"file_search_call.results",
"message.input_image.image_url",
"computer_call_output.output.image_url"
]
},
"description": "Additional fields to include in the response. See the `include` parameter for Response creation above for more information."
}
},
"required": [
"PCID",
"response_id"
]
}
```
***
## openai\_ai\_list\_models
Lists the currently available models, and provides basic information about each one such as the owner and availability.
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
}
},
"required": [
"PCID"
]
}
```
***
## openai\_ai\_retrieve\_model
Retrieves a model instance, providing basic information about the model such as the owner and permissioning.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ------------------------------------------- |
| `model` | string | Yes | — | The ID of the model to use for this request |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"model": {
"type": "string",
"description": "The ID of the model to use for this request"
}
},
"required": [
"PCID",
"model"
]
}
```
***
## openai\_ai\_update\_chat\_completion
Modify a stored chat completion. Only Chat Completions that have been created with the `store` parameter set to `true` can be modified. Currently, the only supported modification is to update the `metadata` field.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `completion_id` | string | Yes | — | The ID of the chat completion to update. |
| `metadata` | object | Yes | — | Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. |
```json theme={null}
{
"type": "object",
"properties": {
"PCID": {
"type": "string",
"description": "Pink Connect ID for the authenticated connection"
},
"completion_id": {
"type": "string",
"description": "The ID of the chat completion to update."
},
"metadata": {
"type": "object",
"description": "Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters."
}
},
"required": [
"PCID",
"completion_id",
"metadata"
]
}
```