diff --git a/openapi.yaml b/openapi.yaml index 813a8a83..5f09487b 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1368,7 +1368,7 @@ paths: -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ - "model": "VAR_model_id", + "model": "VAR_chat_model_id", "messages": [ { "role": "system", @@ -1387,7 +1387,7 @@ paths: completion = client.chat.completions.create( - model="VAR_model_id", + model="VAR_chat_model_id", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} @@ -1406,7 +1406,7 @@ paths: async function main() { const completion = await openai.chat.completions.create({ messages: [{ role: "system", content: "You are a helpful assistant." }], - model: "VAR_model_id", + model: "VAR_chat_model_id", }); console.log(completion.choices[0]); @@ -1559,7 +1559,7 @@ paths: -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ - "model": "VAR_model_id", + "model": "VAR_chat_model_id", "messages": [ { "role": "system", @@ -1579,7 +1579,7 @@ paths: completion = client.chat.completions.create( - model="VAR_model_id", + model="VAR_chat_model_id", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} @@ -1599,7 +1599,7 @@ paths: async function main() { const completion = await openai.chat.completions.create({ - model: "VAR_model_id", + model: "VAR_chat_model_id", messages: [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} @@ -1704,7 +1704,7 @@ paths: in Boston today?"}] completion = client.chat.completions.create( - model="VAR_model_id", + model="VAR_chat_model_id", messages=messages, tools=tools, tool_choice="auto" @@ -1799,7 +1799,7 @@ paths: -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ - "model": "VAR_model_id", + "model": "VAR_chat_model_id", "messages": [ { "role": "user", @@ -1814,7 +1814,7 @@ paths: client = OpenAI() completion = client.chat.completions.create( - model="VAR_model_id", + model="VAR_chat_model_id", messages=[ {"role": "user", "content": "Hello!"} ], @@ -1832,7 +1832,7 @@ paths: async function main() { const completion = await openai.chat.completions.create({ messages: [{ role: "user", content: "Hello!" }], - model: "VAR_model_id", + model: "VAR_chat_model_id", logprobs: true, top_logprobs: 2, }); @@ -2065,7 +2065,7 @@ paths: -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ - "model": "VAR_model_id", + "model": "VAR_completion_model_id", "prompt": "Say this is a test", "max_tokens": 7, "temperature": 0 @@ -2075,7 +2075,7 @@ paths: client = OpenAI() client.completions.create( - model="VAR_model_id", + model="VAR_completion_model_id", prompt="Say this is a test", max_tokens=7, temperature=0 @@ -2087,7 +2087,7 @@ paths: async function main() { const completion = await openai.completions.create({ - model: "VAR_model_id", + model: "VAR_completion_model_id", prompt: "Say this is a test.", max_tokens: 7, temperature: 0, @@ -2101,7 +2101,7 @@ paths: "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", "object": "text_completion", "created": 1589478378, - "model": "VAR_model_id", + "model": "VAR_completion_model_id", "system_fingerprint": "fp_44709d6fcb", "choices": [ { @@ -2124,7 +2124,7 @@ paths: -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ - "model": "VAR_model_id", + "model": "VAR_completion_model_id", "prompt": "Say this is a test", "max_tokens": 7, "temperature": 0, @@ -2135,7 +2135,7 @@ paths: client = OpenAI() for chunk in client.completions.create( - model="VAR_model_id", + model="VAR_completion_model_id", prompt="Say this is a test", max_tokens=7, temperature=0, @@ -2149,7 +2149,7 @@ paths: async function main() { const stream = await openai.completions.create({ - model: "VAR_model_id", + model: "VAR_completion_model_id", prompt: "Say this is a test.", stream: true, }); @@ -3527,20 +3527,20 @@ paths: examples: request: curl: | - curl https://api.openai.com/v1/models/VAR_model_id \ + curl https://api.openai.com/v1/models/VAR_chat_model_id \ -H "Authorization: Bearer $OPENAI_API_KEY" python: | from openai import OpenAI client = OpenAI() - client.models.retrieve("VAR_model_id") + client.models.retrieve("VAR_chat_model_id") node.js: |- import OpenAI from "openai"; const openai = new OpenAI(); async function main() { - const model = await openai.models.retrieve("VAR_model_id"); + const model = await openai.models.retrieve("VAR_chat_model_id"); console.log(model); } @@ -3548,7 +3548,7 @@ paths: main(); response: | { - "id": "VAR_model_id", + "id": "VAR_chat_model_id", "object": "model", "created": 1686935002, "owned_by": "openai" @@ -3978,7 +3978,7 @@ paths: curl: | curl https://api.openai.com/v1/organization/audit_logs \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ + -H "Content-Type: application/json" response: > { "object": "list", @@ -4028,6 +4028,116 @@ paths: "last_id": "audit_log_yyy__20240101", "has_more": true } + /organization/costs: + get: + summary: Get costs details for the organization. + operationId: usage-costs + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently only `1d` is + supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1d + default: 1d + - name: project_ids + in: query + description: Return only costs for these projects. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the costs by the specified fields. Support fields include + `project_id`, `line_item` and any combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - line_item + - name: limit + in: query + description: > + A limit on the number of buckets to be returned. Limit can range + between 1 and 180, and the default is 7. + required: false + schema: + type: integer + default: 7 + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Costs data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Costs + group: usage-costs + returns: A list of paginated, time bucketed + [Costs](/docs/api-reference/usage/costs_object) objects. + examples: + request: + curl: > + curl + "https://api.openai.com/v1/organization/costs?start_time=1730419200&limit=1" + \ + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" + response: | + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "orgainzation.costs.result", + "amount": { + "value": 0.06, + "currency": "usd" + }, + "line_item": null, + "project_id": null + } + ] + } + ], + "has_more": false, + "next_page": null + } /organization/invites: get: summary: Returns a list of invites in the organization. @@ -5213,158 +5323,1261 @@ paths: description: The ID of the project. required: true schema: - type: string - - name: user_id - in: path - description: The ID of the user. - required: true + type: string + - name: user_id + in: path + description: The ID of the user. + required: true + schema: + type: string + responses: + "200": + description: Project user retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectUser" + x-oaiMeta: + name: Retrieve project user + group: administration + returns: The [ProjectUser](/docs/api-reference/project-users/object) object + matching the specified ID. + examples: + request: + curl: > + curl + https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: + content: | + { + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + post: + summary: Modifies a user's role in the project. + operationId: modify-project-user + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: user_id + in: path + description: The ID of the user. + required: true + schema: + type: string + requestBody: + description: The project user update request payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectUserUpdateRequest" + responses: + "200": + description: Project user's role updated successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectUser" + "400": + description: Error response for various conditions. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: Modify project user + group: administration + returns: The updated [ProjectUser](/docs/api-reference/project-users/object) + object. + examples: + request: + curl: > + curl -X POST + https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role": "owner" + }' + response: + content: | + { + "object": "organization.project.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + delete: + summary: Deletes a user from the project. + operationId: delete-project-user + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: user_id + in: path + description: The ID of the user. + required: true + schema: + type: string + responses: + "200": + description: Project user deleted successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectUserDeleteResponse" + "400": + description: Error response for various conditions. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: Delete project user + group: administration + returns: Confirmation that project has been deleted or an error in case of an + archived project, which has no users + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: + content: | + { + "object": "organization.project.user.deleted", + "id": "user_abc", + "deleted": true + } + /organization/usage/audio_speeches: + get: + summary: Get audio speeches usage details for the organization. + operationId: usage-audio-speeches + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`, `user_id`, `api_key_id`, `model` or any + combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Audio speeches + group: usage-audio-speeches + returns: A list of paginated, time bucketed [Audio speeches + usage](/docs/api-reference/usage/audio_speeches_object) objects. + examples: + request: + curl: > + curl + "https://api.openai.com/v1/organization/usage/audio_speeches?start_time=1730419200&limit=1" + \ + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "orgainzation.usage.audio_speeches.result", + "characters": 45, + "num_model_requests": 1, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/usage/audio_transcriptions: + get: + summary: Get audio transcriptions usage details for the organization. + operationId: usage-audio-transcriptions + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`, `user_id`, `api_key_id`, `model` or any + combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Audio transcriptions + group: usage-audio-transcriptions + returns: A list of paginated, time bucketed [Audio transcriptions + usage](/docs/api-reference/usage/audio_transcriptions_object) objects. + examples: + request: + curl: > + curl + "https://api.openai.com/v1/organization/usage/audio_transcriptions?start_time=1730419200&limit=1" + \ + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "orgainzation.usage.audio_transcriptions.result", + "seconds": 20, + "num_model_requests": 1, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/usage/code_interpreter_sessions: + get: + summary: Get code interpreter sessions usage details for the organization. + operationId: usage-code-interpreter-sessions + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Code interpreter sessions + group: usage-code-interpreter-sessions + returns: A list of paginated, time bucketed [Code interpreter sessions + usage](/docs/api-reference/usage/code_interpreter_sessions_object) + objects. + examples: + request: + curl: > + curl + "https://api.openai.com/v1/organization/usage/code_interpreter_sessions?start_time=1730419200&limit=1" + \ + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "orgainzation.usage.code_interpreter_sessions.result", + "sessions": 1, + "project_id": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/usage/completions: + get: + summary: Get completions usage details for the organization. + operationId: usage-completions + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: batch + in: query + description: > + If `true`, return batch jobs only. If `false`, return non-batch jobs + only. By default, return both. + required: false + schema: + type: boolean + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`, `user_id`, `api_key_id`, `model`, `batch` or + any combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - batch + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Completions + group: usage-completions + returns: A list of paginated, time bucketed [Completions + usage](/docs/api-reference/usage/completions_object) objects. + examples: + request: + curl: > + curl + "https://api.openai.com/v1/organization/usage/completions?start_time=1730419200&limit=1" + \ + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "orgainzation.usage.completions.result", + "input_tokens": 1000, + "output_tokens": 500, + "input_cached_tokens": 800, + "num_model_requests": 5, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null, + "batch": null + } + ] + } + ], + "has_more": true, + "next_page": "AAAAAGdGxdEiJdKOAAAAAGcqsYA=" + } + /organization/usage/embeddings: + get: + summary: Get embeddings usage details for the organization. + operationId: usage-embeddings + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`, `user_id`, `api_key_id`, `model` or any + combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. + schema: + type: string + responses: + "200": + description: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + name: Embeddings + group: usage-embeddings + returns: A list of paginated, time bucketed [Embeddings + usage](/docs/api-reference/usage/embeddings_object) objects. + examples: + request: + curl: > + curl + "https://api.openai.com/v1/organization/usage/embeddings?start_time=1730419200&limit=1" + \ + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "orgainzation.usage.embeddings.result", + "input_tokens": 16, + "num_model_requests": 2, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/usage/images: + get: + summary: Get images usage details for the organization. + operationId: usage-images + tags: + - Usage + parameters: + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. + required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false + schema: + type: string + enum: + - 1m + - 1h + - 1d + default: 1d + - name: sources + in: query + description: Return only usages for these sources. Possible values are + `image.generation`, `image.edit`, `image.variation` or any + combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - image.generation + - image.edit + - image.variation + - name: sizes + in: query + description: Return only usages for these image sizes. Possible values are + `256x256`, `512x512`, `1024x1024`, `1792x1792`, `1024x1792` or any + combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - 256x256 + - 512x512 + - 1024x1024 + - 1792x1792 + - 1024x1792 + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`, `user_id`, `api_key_id`, `model`, `size`, + `source` or any combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - size + - source + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. schema: type: string responses: "200": - description: Project user retrieved successfully. + description: Usage data retrieved successfully. content: application/json: schema: - $ref: "#/components/schemas/ProjectUser" + $ref: "#/components/schemas/UsageResponse" x-oaiMeta: - name: Retrieve project user - group: administration - returns: The [ProjectUser](/docs/api-reference/project-users/object) object - matching the specified ID. + name: Images + group: usage-images + returns: A list of paginated, time bucketed [Images + usage](/docs/api-reference/usage/images_object) objects. examples: request: curl: > curl - https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc + "https://api.openai.com/v1/organization/usage/images?start_time=1730419200&limit=1" \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" - response: - content: | - { - "object": "organization.project.user", - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "added_at": 1711471533 - } - post: - summary: Modifies a user's role in the project. - operationId: modify-project-user + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" + response: | + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "orgainzation.usage.images.result", + "images": 2, + "num_model_requests": 2, + "size": null, + "source": null, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/usage/moderations: + get: + summary: Get moderations usage details for the organization. + operationId: usage-moderations tags: - - Projects + - Usage parameters: - - name: project_id - in: path - description: The ID of the project. + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false schema: type: string - - name: user_id - in: path - description: The ID of the user. - required: true + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: user_ids + in: query + description: Return only usage for these users. + required: false + schema: + type: array + items: + type: string + - name: api_key_ids + in: query + description: Return only usage for these API keys. + required: false + schema: + type: array + items: + type: string + - name: models + in: query + description: Return only usage for these models. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`, `user_id`, `api_key_id`, `model` or any + combination of them. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - user_id + - api_key_id + - model + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. schema: type: string - requestBody: - description: The project user update request payload. - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ProjectUserUpdateRequest" responses: "200": - description: Project user's role updated successfully. - content: - application/json: - schema: - $ref: "#/components/schemas/ProjectUser" - "400": - description: Error response for various conditions. + description: Usage data retrieved successfully. content: application/json: schema: - $ref: "#/components/schemas/ErrorResponse" + $ref: "#/components/schemas/UsageResponse" x-oaiMeta: - name: Modify project user - group: administration - returns: The updated [ProjectUser](/docs/api-reference/project-users/object) - object. + name: Moderations + group: usage-moderations + returns: A list of paginated, time bucketed [Moderations + usage](/docs/api-reference/usage/moderations_object) objects. examples: request: curl: > - curl -X POST - https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc + curl + "https://api.openai.com/v1/organization/usage/moderations?start_time=1730419200&limit=1" \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" \ - -d '{ - "role": "owner" - }' - response: - content: | - { - "object": "organization.project.user", - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "added_at": 1711471533 - } - delete: - summary: Deletes a user from the project. - operationId: delete-project-user + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "orgainzation.usage.moderations.result", + "input_tokens": 16, + "num_model_requests": 2, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null + } + ] + } + ], + "has_more": false, + "next_page": null + } + /organization/usage/vector_stores: + get: + summary: Get vector stores usage details for the organization. + operationId: usage-vector-stores tags: - - Projects + - Usage parameters: - - name: project_id - in: path - description: The ID of the project. + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. required: true + schema: + type: integer + - name: end_time + in: query + description: End time (Unix seconds) of the query time range, exclusive. + required: false + schema: + type: integer + - name: bucket_width + in: query + description: Width of each time bucket in response. Currently `1m`, `1h` and + `1d` are supported, default to `1d`. + required: false schema: type: string - - name: user_id - in: path - description: The ID of the user. - required: true + enum: + - 1m + - 1h + - 1d + default: 1d + - name: project_ids + in: query + description: Return only usage for these projects. + required: false + schema: + type: array + items: + type: string + - name: group_by + in: query + description: Group the usage data by the specified fields. Support fields + include `project_id`. + required: false + schema: + type: array + items: + type: string + enum: + - project_id + - name: limit + in: query + description: | + Specifies the number of buckets to return. + - `bucket_width=1d`: default: 7, max: 31 + - `bucket_width=1h`: default: 24, max: 168 + - `bucket_width=1m`: default: 60, max: 1440 + required: false + schema: + type: integer + - name: page + in: query + description: A cursor for use in pagination. Corresponding to the `next_page` + field from the previous response. schema: type: string responses: "200": - description: Project user deleted successfully. - content: - application/json: - schema: - $ref: "#/components/schemas/ProjectUserDeleteResponse" - "400": - description: Error response for various conditions. + description: Usage data retrieved successfully. content: application/json: schema: - $ref: "#/components/schemas/ErrorResponse" + $ref: "#/components/schemas/UsageResponse" x-oaiMeta: - name: Delete project user - group: administration - returns: Confirmation that project has been deleted or an error in case of an - archived project, which has no users + name: Vector stores + group: usage-vector-stores + returns: A list of paginated, time bucketed [Vector stores + usage](/docs/api-reference/usage/vector_stores_object) objects. examples: request: curl: > - curl -X DELETE - https://api.openai.com/v1/organization/projects/proj_abc/users/user_abc + curl + "https://api.openai.com/v1/organization/usage/vector_stores?start_time=1730419200&limit=1" \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" - response: - content: | - { - "object": "organization.project.user.deleted", - "id": "user_abc", - "deleted": true - } + + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + + -H "Content-Type: application/json" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "orgainzation.usage.vector_stores.result", + "usage_bytes": 1024, + "project_id": null + } + ] + } + ], + "has_more": false, + "next_page": null + } /organization/users: get: summary: Lists all of the users in the organization. @@ -11668,6 +12881,47 @@ components: - prompt_tokens - completion_tokens - total_tokens + CostsResult: + type: object + description: The aggregated costs details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.costs.result + amount: + type: object + description: The monetary value in its associated currency. + properties: + value: + type: number + description: The numeric value of the cost. + currency: + type: string + description: Lowercase ISO-4217 currency e.g. "usd" + line_item: + type: string + description: When `group_by=line_item`, this field provides the line item of the + grouped costs result. + project_id: + type: string + description: When `group_by=project_id`, this field provides the project ID of + the grouped costs result. + required: + - object + - sessions + x-oaiMeta: + name: Costs object + example: | + { + "object": "orgainzation.costs.result", + "amount": { + "value": 0.06, + "currency": "usd" + }, + "line_item": "Image models", + "project_id": "proj_abc" + } CreateAssistantRequest: type: object additionalProperties: false @@ -11684,9 +12938,9 @@ components: - type: string enum: - gpt-4o + - gpt-4o-2024-11-20 - gpt-4o-2024-08-06 - gpt-4o-2024-05-13 - - gpt-4o-2024-08-06 - gpt-4o-mini - gpt-4o-mini-2024-07-18 - gpt-4-turbo @@ -12082,9 +13336,9 @@ components: - o1-mini - o1-mini-2024-09-12 - gpt-4o + - gpt-4o-2024-11-20 - gpt-4o-2024-08-06 - gpt-4o-2024-05-13 - - gpt-4o-2024-08-06 - gpt-4o-realtime-preview - gpt-4o-realtime-preview-2024-10-01 - gpt-4o-audio-preview @@ -12251,11 +13505,10 @@ components: - shimmer - verse description: > - The voice the model uses to respond. Supported voices are - `alloy`, - - `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, and - `verse`. + The voice the model uses to respond. Supported voices are `ash`, + `ballad`, `coral`, `sage`, and `verse` (also supported but not + recommended are `alloy`, `echo`, and `shimmer`; these voices are + less expressive). format: type: string enum: @@ -14264,9 +15517,9 @@ components: - type: string enum: - gpt-4o + - gpt-4o-2024-11-20 - gpt-4o-2024-08-06 - gpt-4o-2024-05-13 - - gpt-4o-2024-08-06 - gpt-4o-mini - gpt-4o-mini-2024-07-18 - gpt-4-turbo @@ -14474,9 +15727,9 @@ components: - type: string enum: - gpt-4o + - gpt-4o-2024-11-20 - gpt-4o-2024-08-06 - gpt-4o-2024-05-13 - - gpt-4o-2024-08-06 - gpt-4o-mini - gpt-4o-mini-2024-07-18 - gpt-4-turbo @@ -17013,7 +18266,7 @@ components: name: The model object example: | { - "id": "VAR_model_id", + "id": "VAR_chat_model_id", "object": "model", "created": 1686935002, "owned_by": "openai" @@ -17870,30 +19123,46 @@ components: - role RealtimeClientEventConversationItemCreate: type: object - description: >- + description: > Add a new Item to the Conversation's context, including messages, - function calls, and function call responses. This event can be used both - to populate a "history" of the conversation and to add new items - mid-stream, but has the current limitation that it cannot populate - assistant audio messages. + function + + calls, and function call responses. This event can be used both to + populate a + + "history" of the conversation and to add new items mid-stream, but has + the + + current limitation that it cannot populate assistant audio messages. + If successful, the server will respond with a - `conversation.item.created` event, otherwise an `error` event will be - sent. + `conversation.item.created` + + event, otherwise an `error` event will be sent. properties: event_id: type: string description: Optional client-generated ID used to identify this event. type: type: string + enum: + - conversation.item.create description: The event type, must be `conversation.item.create`. previous_item_id: type: string - description: The ID of the preceding item after which the new item will be - inserted. If not set, the new item will be appended to the end of - the conversation. If set, it allows an item to be inserted - mid-conversation. If the ID cannot be found, an error will be - returned and the item will not be added. + description: > + The ID of the preceding item after which the new item will be + inserted. + + If not set, the new item will be appended to the end of the + conversation. + + If set, it allows an item to be inserted mid-conversation. If the + ID + + cannot be found, an error will be returned and the item will not be + added. item: $ref: "#/components/schemas/RealtimeConversationItem" required: @@ -17921,18 +19190,25 @@ components: } RealtimeClientEventConversationItemDelete: type: object - description: Send this event when you want to remove any item from the - conversation history. The server will respond with a - `conversation.item.deleted` event, unless the item does not exist in the - conversation history, in which case the server will respond with an - error. + description: > + Send this event when you want to remove any item from the conversation + + history. The server will respond with a `conversation.item.deleted` + event, + + unless the item does not exist in the conversation history, in which + case the + + server will respond with an error. properties: event_id: type: string description: Optional client-generated ID used to identify this event. type: type: string - description: The event type, must be "conversation.item.delete". + enum: + - conversation.item.delete + description: The event type, must be `conversation.item.delete`. item_id: type: string description: The ID of the item to delete. @@ -17950,37 +19226,61 @@ components: } RealtimeClientEventConversationItemTruncate: type: object - description: >- + description: > Send this event to truncate a previous assistant message’s audio. The - server will produce audio faster than realtime, so this event is useful - when the user interrupts to truncate audio that has already been sent to - the client but not yet played. This will synchronize the server's - understanding of the audio with the client's playback. + server + + will produce audio faster than realtime, so this event is useful when + the user + + interrupts to truncate audio that has already been sent to the client + but not + + yet played. This will synchronize the server's understanding of the + audio with + + the client's playback. + Truncating audio will delete the server-side text transcript to ensure - there is not text in the context that hasn't been heard by the user. + there + + is not text in the context that hasn't been heard by the user. + If successful, the server will respond with a - `conversation.item.truncated` event. + `conversation.item.truncated` + + event. properties: event_id: type: string description: Optional client-generated ID used to identify this event. type: type: string - description: The event type, must be "conversation.item.truncate". + enum: + - conversation.item.truncate + description: The event type, must be `conversation.item.truncate`. item_id: type: string - description: The ID of the assistant message item to truncate. Only assistant - message items can be truncated. + description: > + The ID of the assistant message item to truncate. Only assistant + message + + items can be truncated. content_index: type: integer description: The index of the content part to truncate. Set this to 0. audio_end_ms: type: integer - description: Inclusive duration up to which audio is truncated, in milliseconds. - If the audio_end_ms is greater than the actual audio duration, the - server will respond with an error. + description: > + Inclusive duration up to which audio is truncated, in milliseconds. + If + + the audio_end_ms is greater than the actual audio duration, the + server + + will respond with an error. required: - type - item_id @@ -17999,28 +19299,48 @@ components: } RealtimeClientEventInputAudioBufferAppend: type: object - description: >- + description: > Send this event to append audio bytes to the input audio buffer. The - audio buffer is temporary storage you can write to and later commit. In - Server VAD mode, the audio buffer is used to detect speech and the - server will decide when to commit. When Server VAD is disabled, you must - commit the audio buffer manually. + audio + + buffer is temporary storage you can write to and later commit. In Server + VAD + + mode, the audio buffer is used to detect speech and the server will + decide + + when to commit. When Server VAD is disabled, you must commit the audio + buffer + + manually. + The client may choose how much audio to place in each event up to a - maximum of 15 MiB, for example streaming smaller chunks from the client - may allow the VAD to be more responsive. Unlike made other client - events, the server will not send a confirmation response to this event. + maximum + + of 15 MiB, for example streaming smaller chunks from the client may + allow the + + VAD to be more responsive. Unlike made other client events, the server + will + + not send a confirmation response to this event. properties: event_id: type: string description: Optional client-generated ID used to identify this event. type: type: string - description: The event type, must be "input_audio_buffer.append". + enum: + - input_audio_buffer.append + description: The event type, must be `input_audio_buffer.append`. audio: type: string - description: Base64-encoded audio bytes. This must be in the format specified by - the `input_audio_format` field in the session configuration. + description: > + Base64-encoded audio bytes. This must be in the format specified by + the + + `input_audio_format` field in the session configuration. required: - type - audio @@ -18035,15 +19355,18 @@ components: } RealtimeClientEventInputAudioBufferClear: type: object - description: Send this event to clear the audio bytes in the buffer. The server - will respond with an `input_audio_buffer.cleared` event. + description: | + Send this event to clear the audio bytes in the buffer. The server will + respond with an `input_audio_buffer.cleared` event. properties: event_id: type: string description: Optional client-generated ID used to identify this event. type: type: string - description: The event type, must be "input_audio_buffer.clear". + enum: + - input_audio_buffer.clear + description: The event type, must be `input_audio_buffer.clear`. required: - type x-oaiMeta: @@ -18056,24 +19379,40 @@ components: } RealtimeClientEventInputAudioBufferCommit: type: object - description: >- + description: > Send this event to commit the user input audio buffer, which will create - a new user message item in the conversation. This event will produce an - error if the input audio buffer is empty. When in Server VAD mode, the - client does not need to send this event, the server will commit the - audio buffer automatically. + a + + new user message item in the conversation. This event will produce an + error + + if the input audio buffer is empty. When in Server VAD mode, the client + does + + not need to send this event, the server will commit the audio buffer + + automatically. + + + Committing the input audio buffer will trigger input audio + transcription + + (if enabled in session configuration), but it will not create a + response - Committing the input audio buffer will trigger input audio transcription - (if enabled in session configuration), but it will not create a response from the model. The server will respond with an - `input_audio_buffer.committed` event. + `input_audio_buffer.committed` + + event. properties: event_id: type: string description: Optional client-generated ID used to identify this event. type: type: string - description: The event type, must be "input_audio_buffer.commit". + enum: + - input_audio_buffer.commit + description: The event type, must be `input_audio_buffer.commit`. required: - type x-oaiMeta: @@ -18086,15 +19425,22 @@ components: } RealtimeClientEventResponseCancel: type: object - description: Send this event to cancel an in-progress response. The server will - respond with a `response.cancelled` event or an error if there is no - response to cancel. + description: > + Send this event to cancel an in-progress response. The server will + respond + + with a `response.cancelled` event or an error if there is no response + to + + cancel. properties: event_id: type: string description: Optional client-generated ID used to identify this event. type: type: string + enum: + - response.cancel description: The event type, must be `response.cancel`. required: - type @@ -18108,31 +19454,50 @@ components: } RealtimeClientEventResponseCreate: type: object - description: >- + description: > This event instructs the server to create a Response, which means - triggering model inference. When in Server VAD mode, the server will - create Responses automatically. + triggering + + model inference. When in Server VAD mode, the server will create + Responses + + automatically. + A Response will include at least one Item, and may have two, in which - case the second will be a function call. These Items will be appended to - the conversation history. + case + + the second will be a function call. These Items will be appended to the + + conversation history. + The server will respond with a `response.created` event, events for - Items and content created, and finally a `response.done` event to - indicate the Response is complete. + Items + + and content created, and finally a `response.done` event to indicate + the + + Response is complete. + + + The `response.create` event includes inference configuration like - The `response.create` event includes inference configuration like `instructions`, and `temperature`. These fields will override the - Session's configuration for this Response only. + Session's + + configuration for this Response only. properties: event_id: type: string description: Optional client-generated ID used to identify this event. type: type: string + enum: + - response.create description: The event type, must be `response.create`. response: - $ref: "#/components/schemas/RealtimeResponse" + $ref: "#/components/schemas/RealtimeSession" required: - type - response @@ -18146,7 +19511,7 @@ components: "response": { "modalities": ["text", "audio"], "instructions": "Please assist the user.", - "voice": "alloy", + "voice": "sage", "output_audio_format": "pcm16", "tools": [ { @@ -18170,20 +19535,32 @@ components: } RealtimeClientEventSessionUpdate: type: object - description: Send this event to update the session’s default configuration. The - client may send this event at any time to update the session - configuration, and any field may be updated at any time, except for - "voice". The server will respond with a `session.updated` event that - shows the full effective configuration. Only fields that are present are - updated, thus the correct way to clear a field like "instructions" is to - pass an empty string. + description: > + Send this event to update the session’s default configuration. The + client may + + send this event at any time to update the session configuration, and + any + + field may be updated at any time, except for "voice". The server will + respond + + with a `session.updated` event that shows the full effective + configuration. + + Only fields that are present are updated, thus the correct way to clear + a + + field like "instructions" is to pass an empty string. properties: event_id: type: string description: Optional client-generated ID used to identify this event. type: type: string - description: The event type, must be "session.update". + enum: + - session.update + description: The event type, must be `session.update`. session: $ref: "#/components/schemas/RealtimeSession" required: @@ -18192,14 +19569,14 @@ components: x-oaiMeta: name: session.update group: realtime - example: > + example: | { "event_id": "event_123", "type": "session.update", "session": { "modalities": ["text", "audio"], - "instructions": "Your knowledge cutoff is 2023-10. You are a helpful assistant.", - "voice": "alloy", + "instructions": "You are a helpful assistant.", + "voice": "sage", "input_audio_format": "pcm16", "output_audio_format": "pcm16", "input_audio_transcription": { @@ -18215,7 +19592,7 @@ components: { "type": "function", "name": "get_weather", - "description": "Get the current weather for a location, tell the user you are fetching the weather.", + "description": "Get the current weather...", "parameters": { "type": "object", "properties": { @@ -18232,63 +19609,120 @@ components: } RealtimeConversationItem: type: object + x-oaiExpandable: true description: The item to add to the conversation. properties: id: type: string - description: The unique ID of the item, this can be generated by the client to - help manage server-side context, but is not required because the - server will generate one if not provided. + description: > + The unique ID of the item, this can be generated by the client to + help + + manage server-side context, but is not required because the server + will + + generate one if not provided. type: type: string - description: The type of the item (`message`, `function_call`, + enum: + - message + - function_call + - function_call_output + description: > + The type of the item (`message`, `function_call`, `function_call_output`). + object: + type: string + enum: + - realtime.item + description: > + Identifier for the API object being returned - always + `realtime.item`. status: type: string - description: The status of the item (`completed`, `incomplete`). These have no - effect on the conversation, but are accepted for consistency with - the `conversation.item.created` event. + enum: + - completed + - incomplete + description: > + The status of the item (`completed`, `incomplete`). These have no + effect + + on the conversation, but are accepted for consistency with the + + `conversation.item.created` event. role: type: string - description: The role of the message sender (`user`, `assistant`, `system`), - only applicable for `message` items. + enum: + - user + - assistant + - systems + description: > + The role of the message sender (`user`, `assistant`, `system`), + only + + applicable for `message` items. content: type: array - description: The content of the message, applicable for `message` items. Message - items with a role of `system` support only `input_text` content, - message items of role `user` support `input_text` and `input_audio` - content, and message items of role `assistant` support `text` - content. + x-oaiExpandable: true + description: > + The content of the message, applicable for `message` items. + + - Message items of role `system` support only `input_text` content + + - Message items of role `user` support `input_text` and + `input_audio` + content + - Message items of role `assistant` support `text` content. items: type: object + x-oaiExpandable: true properties: type: type: string + enum: + - input_audio + - input_text + - text description: The content type (`input_text`, `input_audio`, `text`). text: type: string - description: The text content, used for `input_text` and `text` content types. + description: > + The text content, used for `input_text` and `text` content + types. audio: type: string - description: Base64-encoded audio bytes, used for `input_audio` content type. + description: > + Base64-encoded audio bytes, used for `input_audio` content + type. transcript: type: string - description: The transcript of the audio, used for `input_audio` content type. + description: > + The transcript of the audio, used for `input_audio` content + type. call_id: type: string - description: The ID of the function call (for `function_call` and - `function_call_output` items). If passed on a `function_call_output` + description: > + The ID of the function call (for `function_call` and + + `function_call_output` items). If passed on a + `function_call_output` + item, the server will check that a `function_call` item with the - same ID exists in the conversation history. + same + + ID exists in the conversation history. name: type: string - description: The name of the function being called (for `function_call` items). + description: | + The name of the function being called (for `function_call` items). arguments: type: string - description: The arguments of the function call (for `function_call` items). + description: | + The arguments of the function call (for `function_call` items). output: type: string - description: The output of the function call (for `function_call_output` items). + description: | + The output of the function call (for `function_call_output` items). RealtimeResponse: type: object description: The response resource. @@ -18298,30 +19732,62 @@ components: description: The unique ID of the response. object: type: string + enum: + - realtime.response description: The object type, must be `realtime.response`. status: type: string - description: The final status of the response (`completed`, `cancelled`, - `failed`, `incomplete`). + enum: + - completed + - cancelled + - failed + - incomplete + description: > + The final status of the response (`completed`, `cancelled`, + `failed`, or + + `incomplete`). status_details: type: object description: Additional details about the status. properties: type: type: string - description: The type of error that caused the response to fail, corresponding + enum: + - completed + - cancelled + - failed + - incomplete + description: > + The type of error that caused the response to fail, + corresponding + with the `status` field (`cancelled`, `incomplete`, `failed`). reason: type: string - description: The reason the Response did not complete. For a `cancelled` - Response, one of `turn_detected` (the server VAD detected a new - start of speech) or `client_cancelled` (the client sent a cancel - event). For an `incomplete` Response, one of `max_output_tokens` - or `content_filter` (the server-side safety filter activated and - cut off the response). + enum: + - turn_detected + - client_cancelled + - max_output_tokens + - content_filter + description: > + The reason the Response did not complete. For a `cancelled` + Response, + + one of `turn_detected` (the server VAD detected a new start of + speech) + + or `client_cancelled` (the client sent a cancel event). For an + + `incomplete` Response, one of `max_output_tokens` or + `content_filter` + + (the server-side safety filter activated and cut off the + response). error: type: object - description: A description of the error that caused the response to fail, + description: | + A description of the error that caused the response to fail, populated when the `status` is `failed`. properties: type: @@ -18334,27 +19800,42 @@ components: type: array description: The list of output items generated by the response. items: - type: object - description: An item in the response output. + $ref: "#/components/schemas/RealtimeConversationItem" usage: type: object - description: Usage statistics for the Response, this will correspond to billing. - A Realtime API session will maintain a conversation context and - append new Items to the Conversation, thus output from previous - turns (text and audio tokens) will become the input for later turns. + description: > + Usage statistics for the Response, this will correspond to billing. + A + + Realtime API session will maintain a conversation context and append + new + + Items to the Conversation, thus output from previous turns (text + and + + audio tokens) will become the input for later turns. properties: total_tokens: type: integer - description: The total number of tokens in the Response including input and - output text and audio tokens. + description: > + The total number of tokens in the Response including input and + output + + text and audio tokens. input_tokens: type: integer - description: The number of input tokens used in the Response, including text and + description: > + The number of input tokens used in the Response, including text + and + audio tokens. output_tokens: type: integer - description: The number of output tokens sent in the Response, including text - and audio tokens. + description: > + The number of output tokens sent in the Response, including text + and + + audio tokens. input_token_details: type: object description: Details about the input tokens used in the Response. @@ -18380,15 +19861,18 @@ components: description: The number of audio tokens used in the Response. RealtimeServerEventConversationCreated: type: object - description: Returned when a conversation is created. Emitted right after - session creation. + description: > + Returned when a conversation is created. Emitted right after session + creation. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "conversation.created". + enum: + - conversation.created + description: The event type, must be `conversation.created`. conversation: type: object description: The conversation resource. @@ -18398,7 +19882,7 @@ components: description: The unique ID of the conversation. object: type: string - description: The object type, must be "realtime.conversation". + description: The object type, must be `realtime.conversation`. required: - event_id - type @@ -18417,23 +19901,35 @@ components: } RealtimeServerEventConversationItemCreated: type: object - description: >- + description: > Returned when a conversation item is created. There are several - scenarios that produce this event: - - The server is generating a Response, which if successful will produce either one or two Items, which will be of type `message` (role `assistant`) or type `function_call`. - - The input audio buffer has been committed, either by the client or the server (in `server_vad` mode). The server will take the content of the input audio buffer and add it to a new user message Item. - - The client has sent a `conversation.item.create` event to add a new Item to the Conversation. + scenarios that + + produce this event: + - The server is generating a Response, which if successful will produce + either one or two Items, which will be of type `message` + (role `assistant`) or type `function_call`. + - The input audio buffer has been committed, either by the client or the + server (in `server_vad` mode). The server will take the content of the + input audio buffer and add it to a new user message Item. + - The client has sent a `conversation.item.create` event to add a new Item + to the Conversation. properties: event_id: type: string description: The unique ID of the server event. type: type: string + enum: + - conversation.item.created description: The event type, must be `conversation.item.created`. previous_item_id: type: string - description: The ID of the preceding item in the Conversation context, allows - the client to understand the order of the conversation. + description: > + The ID of the preceding item in the Conversation context, allows + the + + client to understand the order of the conversation. item: $ref: "#/components/schemas/RealtimeConversationItem" required: @@ -18466,16 +19962,22 @@ components: } RealtimeServerEventConversationItemDeleted: type: object - description: Returned when an item in the conversation is deleted by the client - with a `conversation.item.delete` event. This event is used to - synchronize the server's understanding of the conversation history with - the client's view. + description: > + Returned when an item in the conversation is deleted by the client with + a + + `conversation.item.delete` event. This event is used to synchronize the + + server's understanding of the conversation history with the client's + view. properties: event_id: type: string description: The unique ID of the server event. type: type: string + enum: + - conversation.item.deleted description: The event type, must be `conversation.item.deleted`. item_id: type: string @@ -18495,25 +19997,41 @@ components: } RealtimeServerEventConversationItemInputAudioTranscriptionCompleted: type: object - description: >- + description: > This event is the output of audio transcription for user audio written - to the user audio buffer. Transcription begins when the input audio - buffer is committed by the client or server (in `server_vad` mode). - Transcription runs asynchronously with Response creation, so this event - may come before or after the Response events. + to the + + user audio buffer. Transcription begins when the input audio buffer is + + committed by the client or server (in `server_vad` mode). Transcription + runs + + asynchronously with Response creation, so this event may come before or + after + + the Response events. + Realtime API models accept audio natively, and thus input transcription - is a separate process run on a separate ASR (Automatic Speech - Recognition) model, currently always `whisper-1`. Thus the transcript - may diverge somewhat from the model's interpretation, and should be - treated as a rough guide. + is a + + separate process run on a separate ASR (Automatic Speech Recognition) + model, + + currently always `whisper-1`. Thus the transcript may diverge somewhat + from + + the model's interpretation, and should be treated as a rough guide. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be + enum: + - conversation.item.input_audio_transcription.completed + description: | + The event type, must be `conversation.item.input_audio_transcription.completed`. item_id: type: string @@ -18543,17 +20061,23 @@ components: } RealtimeServerEventConversationItemInputAudioTranscriptionFailed: type: object - description: Returned when input audio transcription is configured, and a - transcription request for a user message failed. These events are - separate from other `error` events so that the client can identify the - related Item. + description: > + Returned when input audio transcription is configured, and a + transcription + + request for a user message failed. These events are separate from other + + `error` events so that the client can identify the related Item. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be + enum: + - conversation.item.input_audio_transcription.failed + description: | + The event type, must be `conversation.item.input_audio_transcription.failed`. item_id: type: string @@ -18601,21 +20125,29 @@ components: } RealtimeServerEventConversationItemTruncated: type: object - description: >- + description: > Returned when an earlier assistant audio message item is truncated by - the client with a `conversation.item.truncate` event. This event is used - to synchronize the server's understanding of the audio with the client's + the + + client with a `conversation.item.truncate` event. This event is used to + + synchronize the server's understanding of the audio with the client's playback. + This action will truncate the audio and remove the server-side text - transcript to ensure there is no text in the context that hasn't been - heard by the user. + transcript + + to ensure there is no text in the context that hasn't been heard by the + user. properties: event_id: type: string description: The unique ID of the server event. type: type: string + enum: + - conversation.item.truncated description: The event type, must be `conversation.item.truncated`. item_id: type: string @@ -18625,7 +20157,8 @@ components: description: The index of the content part that was truncated. audio_end_ms: type: integer - description: The duration up to which the audio was truncated, in milliseconds. + description: | + The duration up to which the audio was truncated, in milliseconds. required: - event_id - type @@ -18645,24 +20178,31 @@ components: } RealtimeServerEventError: type: object - description: Returned when an error occurs, which could be a client problem or a - server problem. Most errors are recoverable and the session will stay - open, we recommend to implementors to monitor and log error messages by - default. + description: > + Returned when an error occurs, which could be a client problem or a + server + + problem. Most errors are recoverable and the session will stay open, we + + recommend to implementors to monitor and log error messages by default. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "error". + enum: + - error + description: The event type, must be `error`. error: type: object description: Details of the error. properties: type: type: string - description: The type of error (e.g., "invalid_request_error", "server_error"). + description: > + The type of error (e.g., "invalid_request_error", + "server_error"). code: type: string description: Error code, if any. @@ -18674,7 +20214,8 @@ components: description: Parameter related to the error, if any. event_id: type: string - description: The event_id of the client event that caused the error, if + description: > + The event_id of the client event that caused the error, if applicable. required: - event_id @@ -18697,14 +20238,17 @@ components: } RealtimeServerEventInputAudioBufferCleared: type: object - description: Returned when the input audio buffer is cleared by the client with - a `input_audio_buffer.clear` event. + description: | + Returned when the input audio buffer is cleared by the client with a + `input_audio_buffer.clear` event. properties: event_id: type: string description: The unique ID of the server event. type: type: string + enum: + - input_audio_buffer.cleared description: The event type, must be `input_audio_buffer.cleared`. required: - event_id @@ -18719,20 +20263,30 @@ components: } RealtimeServerEventInputAudioBufferCommitted: type: object - description: Returned when an input audio buffer is committed, either by the - client or automatically in server VAD mode. The `item_id` property is - the ID of the user message item that will be created, thus a - `conversation.item.created` event will also be sent to the client. + description: > + Returned when an input audio buffer is committed, either by the client + or + + automatically in server VAD mode. The `item_id` property is the ID of + the user + + message item that will be created, thus a `conversation.item.created` + event + + will also be sent to the client. properties: event_id: type: string description: The unique ID of the server event. type: type: string + enum: + - input_audio_buffer.committed description: The event type, must be `input_audio_buffer.committed`. previous_item_id: type: string - description: The ID of the preceding item after which the new item will be + description: > + The ID of the preceding item after which the new item will be inserted. item_id: type: string @@ -18754,32 +20308,56 @@ components: } RealtimeServerEventInputAudioBufferSpeechStarted: type: object - description: Sent by the server when in `server_vad` mode to indicate that - speech has been detected in the audio buffer. This can happen any time - audio is added to the buffer (unless speech is already detected). The - client may want to use this event to interrupt audio playback or provide - visual feedback to the user. The client should expect to receive a - `input_audio_buffer.speech_stopped` event when speech stops. The - `item_id` property is the ID of the user message item that will be - created when speech stops and will also be included in the + description: > + Sent by the server when in `server_vad` mode to indicate that speech has + been + + detected in the audio buffer. This can happen any time audio is added to + the + + buffer (unless speech is already detected). The client may want to use + this + + event to interrupt audio playback or provide visual feedback to the + user. + + + The client should expect to receive a + `input_audio_buffer.speech_stopped` event + + when speech stops. The `item_id` property is the ID of the user message + item + + that will be created when speech stops and will also be included in the + `input_audio_buffer.speech_stopped` event (unless the client manually - commits the audio buffer during VAD activation). + commits + + the audio buffer during VAD activation). properties: event_id: type: string description: The unique ID of the server event. type: type: string + enum: + - input_audio_buffer.speech_started description: The event type, must be `input_audio_buffer.speech_started`. audio_start_ms: type: integer - description: Milliseconds from the start of all audio written to the buffer - during the session when speech was first detected. This will - correspond to the beginning of audio sent to the model, and thus - includes the `prefix_padding_ms` configured in the Session. + description: > + Milliseconds from the start of all audio written to the buffer + during the + + session when speech was first detected. This will correspond to the + + beginning of audio sent to the model, and thus includes the + + `prefix_padding_ms` configured in the Session. item_id: type: string - description: The ID of the user message item that will be created when speech + description: > + The ID of the user message item that will be created when speech stops. required: - event_id @@ -18798,22 +20376,33 @@ components: } RealtimeServerEventInputAudioBufferSpeechStopped: type: object - description: Returned in `server_vad` mode when the server detects the end of - speech in the audio buffer. The server will also send an - `conversation.item.created` event with the user message item that is - created from the audio buffer. + description: > + Returned in `server_vad` mode when the server detects the end of speech + in + + the audio buffer. The server will also send an + `conversation.item.created` + + event with the user message item that is created from the audio buffer. properties: event_id: type: string description: The unique ID of the server event. type: type: string + enum: + - input_audio_buffer.speech_stopped description: The event type, must be `input_audio_buffer.speech_stopped`. audio_end_ms: type: integer - description: Milliseconds since the session started when speech stopped. This - will correspond to the end of audio sent to the model, and thus - includes the `min_silence_duration_ms` configured in the Session. + description: > + Milliseconds since the session started when speech stopped. This + will + + correspond to the end of audio sent to the model, and thus includes + the + + `min_silence_duration_ms` configured in the Session. item_id: type: string description: The ID of the user message item that will be created. @@ -18834,16 +20423,25 @@ components: } RealtimeServerEventRateLimitsUpdated: type: object - description: Emitted at the beginning of a Response to indicate the updated rate - limits. When a Response is created some tokens will be "reserved" for - the output tokens, the rate limits shown here reflect that reservation, - which is then adjusted accordingly once the Response is completed. + description: > + Emitted at the beginning of a Response to indicate the updated rate + limits. + + When a Response is created some tokens will be "reserved" for the + output + + tokens, the rate limits shown here reflect that reservation, which is + then + + adjusted accordingly once the Response is completed. properties: event_id: type: string description: The unique ID of the server event. type: type: string + enum: + - rate_limits.updated description: The event type, must be `rate_limits.updated`. rate_limits: type: array @@ -18898,7 +20496,9 @@ components: description: The unique ID of the server event. type: type: string - description: The event type, must be "response.audio.delta". + enum: + - response.audio.delta + description: The event type, must be `response.audio.delta`. response_id: type: string description: The ID of the response. @@ -18937,15 +20537,20 @@ components: } RealtimeServerEventResponseAudioDone: type: object - description: Returned when the model-generated audio is done. Also emitted when - a Response is interrupted, incomplete, or cancelled. + description: > + Returned when the model-generated audio is done. Also emitted when a + Response + + is interrupted, incomplete, or cancelled. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "response.audio.done". + enum: + - response.audio.done + description: The event type, must be `response.audio.done`. response_id: type: string description: The ID of the response. @@ -18979,7 +20584,8 @@ components: } RealtimeServerEventResponseAudioTranscriptDelta: type: object - description: Returned when the model-generated transcription of audio output is + description: > + Returned when the model-generated transcription of audio output is updated. properties: event_id: @@ -18987,7 +20593,9 @@ components: description: The unique ID of the server event. type: type: string - description: The event type, must be "response.audio_transcript.delta". + enum: + - response.audio_transcript.delta + description: The event type, must be `response.audio_transcript.delta`. response_id: type: string description: The ID of the response. @@ -19026,16 +20634,19 @@ components: } RealtimeServerEventResponseAudioTranscriptDone: type: object - description: Returned when the model-generated transcription of audio output is - done streaming. Also emitted when a Response is interrupted, incomplete, - or cancelled. + description: | + Returned when the model-generated transcription of audio output is done + streaming. Also emitted when a Response is interrupted, incomplete, or + cancelled. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "response.audio_transcript.done". + enum: + - response.audio_transcript.done + description: The event type, must be `response.audio_transcript.done`. response_id: type: string description: The ID of the response. @@ -19074,15 +20685,20 @@ components: } RealtimeServerEventResponseContentPartAdded: type: object - description: Returned when a new content part is added to an assistant message - item during response generation. + description: > + Returned when a new content part is added to an assistant message item + during + + response generation. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "response.content_part.added". + enum: + - response.content_part.added + description: The event type, must be `response.content_part.added`. response_id: type: string description: The ID of the response. @@ -19101,6 +20717,9 @@ components: properties: type: type: string + enum: + - audio + - text description: The content type ("text", "audio"). text: type: string @@ -19137,16 +20756,20 @@ components: } RealtimeServerEventResponseContentPartDone: type: object - description: Returned when a content part is done streaming in an assistant - message item. Also emitted when a Response is interrupted, incomplete, - or cancelled. + description: > + Returned when a content part is done streaming in an assistant message + item. + + Also emitted when a Response is interrupted, incomplete, or cancelled. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "response.content_part.done". + enum: + - response.content_part.done + description: The event type, must be `response.content_part.done`. response_id: type: string description: The ID of the response. @@ -19201,15 +20824,19 @@ components: } RealtimeServerEventResponseCreated: type: object - description: Returned when a new Response is created. The first event of - response creation, where the response is in an initial state of - `in_progress`. + description: > + Returned when a new Response is created. The first event of response + creation, + + where the response is in an initial state of `in_progress`. properties: event_id: type: string description: The unique ID of the server event. type: type: string + enum: + - response.created description: The event type, must be `response.created`. response: $ref: "#/components/schemas/RealtimeResponse" @@ -19235,17 +20862,24 @@ components: } RealtimeServerEventResponseDone: type: object - description: Returned when a Response is done streaming. Always emitted, no - matter the final state. The Response object included in the - `response.done` event will include all output Items in the Response but - will omit the raw audio data. + description: > + Returned when a Response is done streaming. Always emitted, no matter + the + + final state. The Response object included in the `response.done` event + will + + include all output Items in the Response but will omit the raw audio + data. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "response.done". + enum: + - response.done + description: The event type, must be `response.done`. response: $ref: "#/components/schemas/RealtimeResponse" required: @@ -19301,14 +20935,18 @@ components: } RealtimeServerEventResponseFunctionCallArgumentsDelta: type: object - description: Returned when the model-generated function call arguments are updated. + description: | + Returned when the model-generated function call arguments are updated. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "response.function_call_arguments.delta". + enum: + - response.function_call_arguments.delta + description: | + The event type, must be `response.function_call_arguments.delta`. response_id: type: string description: The ID of the response. @@ -19347,16 +20985,21 @@ components: } RealtimeServerEventResponseFunctionCallArgumentsDone: type: object - description: Returned when the model-generated function call arguments are done - streaming. Also emitted when a Response is interrupted, incomplete, or - cancelled. + description: > + Returned when the model-generated function call arguments are done + streaming. + + Also emitted when a Response is interrupted, incomplete, or cancelled. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "response.function_call_arguments.done". + enum: + - response.function_call_arguments.done + description: | + The event type, must be `response.function_call_arguments.done`. response_id: type: string description: The ID of the response. @@ -19402,6 +21045,8 @@ components: description: The unique ID of the server event. type: type: string + enum: + - response.output_item.added description: The event type, must be `response.output_item.added`. response_id: type: string @@ -19437,14 +21082,19 @@ components: } RealtimeServerEventResponseOutputItemDone: type: object - description: Returned when an Item is done streaming. Also emitted when a - Response is interrupted, incomplete, or cancelled. + description: > + Returned when an Item is done streaming. Also emitted when a Response + is + + interrupted, incomplete, or cancelled. properties: event_id: type: string description: The unique ID of the server event. type: type: string + enum: + - response.output_item.done description: The event type, must be `response.output_item.done`. response_id: type: string @@ -19492,7 +21142,9 @@ components: description: The unique ID of the server event. type: type: string - description: The event type, must be "response.text.delta". + enum: + - response.text.delta + description: The event type, must be `response.text.delta`. response_id: type: string description: The ID of the response. @@ -19531,16 +21183,20 @@ components: } RealtimeServerEventResponseTextDone: type: object - description: Returned when the text value of a "text" content part is done - streaming. Also emitted when a Response is interrupted, incomplete, or - cancelled. + description: > + Returned when the text value of a "text" content part is done streaming. + Also + + emitted when a Response is interrupted, incomplete, or cancelled. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "response.text.done". + enum: + - response.text.done + description: The event type, must be `response.text.done`. response_id: type: string description: The ID of the response. @@ -19579,15 +21235,21 @@ components: } RealtimeServerEventSessionCreated: type: object - description: Returned when a Session is created. Emitted automatically when a - new connection is established as the first server event. This event will - contain the default Session configuration. + description: > + Returned when a Session is created. Emitted automatically when a new + + connection is established as the first server event. This event will + contain + + the default Session configuration. properties: event_id: type: string description: The unique ID of the server event. type: type: string + enum: + - session.created description: The event type, must be `session.created`. session: $ref: "#/components/schemas/RealtimeSession" @@ -19607,8 +21269,8 @@ components: "object": "realtime.session", "model": "gpt-4o-realtime-preview-2024-10-01", "modalities": ["text", "audio"], - "instructions": "", - "voice": "alloy", + "instructions": "...model instructions here...", + "voice": "sage", "input_audio_format": "pcm16", "output_audio_format": "pcm16", "input_audio_transcription": null, @@ -19621,20 +21283,25 @@ components: "tools": [], "tool_choice": "auto", "temperature": 0.8, - "max_response_output_tokens": null + "max_response_output_tokens": "inf" } } RealtimeServerEventSessionUpdated: type: object - description: Returned when a session is updated with a `session.update` event, - unless there is an error. + description: > + Returned when a session is updated with a `session.update` event, + unless + + there is an error. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "session.updated". + enum: + - session.updated + description: The event type, must be `session.updated`. session: $ref: "#/components/schemas/RealtimeSession" required: @@ -19654,7 +21321,7 @@ components: "model": "gpt-4o-realtime-preview-2024-10-01", "modalities": ["text"], "instructions": "New instructions", - "voice": "alloy", + "voice": "sage", "input_audio_format": "pcm16", "output_audio_format": "pcm16", "input_audio_transcription": { @@ -19672,12 +21339,14 @@ components: description: Realtime session object configuration. properties: modalities: - type: array - items: - type: string description: | The set of modalities the model can respond with. To disable audio, set this to ["text"]. + items: + type: string + enum: + - text + - audio instructions: type: string description: > @@ -19723,13 +21392,21 @@ components: - shimmer - verse description: > - The voice the model uses to respond. Supported voices are `alloy`, - `ash`, + The voice the model uses to respond. Current voice options are + `ash`, + + `ballad`, `coral`, `sage`, and `verse`. + + + Also supported but not recommended are `alloy`, `echo`, and + `shimmer`. + + These older voices are less expressive. - `ballad`, `coral`, `echo`, `sage`, `shimmer`, and `verse`. Cannot - be - changed once the model has responded with audio at least once. + Voice cannot be changed during the session once the model has + + responded with audio at least once. input_audio_format: type: string description: > @@ -19812,6 +21489,8 @@ components: properties: type: type: string + enum: + - function description: The type of the tool, i.e. `function`. name: type: string @@ -21511,6 +23190,411 @@ components: "created_at": 1719186911, "upload_id": "upload_abc123" } + UsageAudioSpeechesResult: + type: object + description: The aggregated audio speeches usage details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.audio_speeches.result + characters: + type: integer + description: The number of characters processed. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + required: + - object + - characters + - num_model_requests + x-oaiMeta: + name: Audio speeches usage object + example: | + { + "object": "orgainzation.usage.audio_speeches.result", + "characters": 45, + "num_model_requests": 1, + "project_id": "proj_abc", + "user_id": "user-abc", + "api_key_id": "key_abc", + "model": "tts-1" + } + UsageAudioTranscriptionsResult: + type: object + description: The aggregated audio transcriptions usage details of the specific + time bucket. + properties: + object: + type: string + enum: + - organization.usage.audio_transcriptions.result + seconds: + type: integer + description: The number of seconds processed. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + required: + - object + - seconds + - num_model_requests + x-oaiMeta: + name: Audio transcriptions usage object + example: | + { + "object": "orgainzation.usage.audio_transcriptions.result", + "seconds": 10, + "num_model_requests": 1, + "project_id": "proj_abc", + "user_id": "user-abc", + "api_key_id": "key_abc", + "model": "tts-1" + } + UsageCodeInterpreterSessionsResult: + type: object + description: The aggregated code interpreter sessions usage details of the + specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.code_interpreter_sessions.result + sessions: + type: integer + description: The number of code interpreter sessions. + project_id: + type: string + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + required: + - object + - sessions + x-oaiMeta: + name: Code interpreter sessions usage object + example: | + { + "object": "orgainzation.usage.code_interpreter_sessions.result", + "sessions": 1, + "project_id": "proj_abc" + } + UsageCompletionsResult: + type: object + description: The aggregated completions usage details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.completions.result + input_tokens: + type: integer + description: The number of input tokens used. + input_cached_tokens: + type: integer + description: The number of input tokens that has been cached from previous + requests. + output_tokens: + type: integer + description: The number of output tokens used. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + batch: + type: boolean + description: When `group_by=batch`, this field tells whether the grouped usage + result is batch or not. + required: + - object + - input_tokens + - output_tokens + - num_model_requests + x-oaiMeta: + name: Completions usage object + example: | + { + "object": "orgainzation.usage.completions.result", + "input_tokens": 5000, + "output_tokens": 1000, + "input_cached_tokens": 4000, + "num_model_requests": 5, + "project_id": "proj_abc", + "user_id": "user-abc", + "api_key_id": "key_abc", + "model": "gpt-4o-mini-2024-07-18", + "batch": false + } + UsageEmbeddingsResult: + type: object + description: The aggregated embeddings usage details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.embeddings.result + input_tokens: + type: integer + description: The number of input tokens used. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + required: + - object + - input_tokens + - num_model_requests + x-oaiMeta: + name: Embeddings usage object + example: | + { + "object": "orgainzation.usage.embeddings.result", + "input_tokens": 20, + "num_model_requests": 2, + "project_id": "proj_abc", + "user_id": "user-abc", + "api_key_id": "key_abc", + "model": "text-embedding-ada-002-v2" + } + UsageImagesResult: + type: object + description: The aggregated images usage details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.images.result + images: + type: integer + description: The number of images processed. + num_model_requests: + type: integer + description: The count of requests made to the model. + source: + type: string + description: When `group_by=source`, this field provides the source of the + grouped usage result, possible values are `image.generation`, + `image.edit`, `image.variation`. + size: + type: string + description: When `group_by=size`, this field provides the image size of the + grouped usage result. + project_id: + type: string + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + required: + - object + - images + - num_model_requests + x-oaiMeta: + name: Images usage object + example: | + { + "object": "orgainzation.usage.images.result", + "images": 2, + "num_model_requests": 2, + "size": "1024x1024", + "source": "image.generation", + "project_id": "proj_abc", + "user_id": "user-abc", + "api_key_id": "key_abc", + "model": "dall-e-3" + } + UsageModerationsResult: + type: object + description: The aggregated moderations usage details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.moderations.result + input_tokens: + type: integer + description: The number of input tokens used. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + required: + - object + - input_tokens + - num_model_requests + x-oaiMeta: + name: Moderations usage object + example: | + { + "object": "orgainzation.usage.moderations.result", + "input_tokens": 20, + "num_model_requests": 2, + "project_id": "proj_abc", + "user_id": "user-abc", + "api_key_id": "key_abc", + "model": "text-moderation" + } + UsageResponse: + type: object + properties: + object: + type: string + enum: + - page + data: + type: array + items: + $ref: "#/components/schemas/UsageTimeBucket" + has_more: + type: boolean + next_page: + type: string + required: + - object + - data + - has_more + - next_page + UsageTimeBucket: + type: object + properties: + object: + type: string + enum: + - bucket + start_time: + type: integer + end_time: + type: integer + result: + type: array + items: + oneOf: + - $ref: "#/components/schemas/UsageCompletionsResult" + - $ref: "#/components/schemas/UsageEmbeddingsResult" + - $ref: "#/components/schemas/UsageModerationsResult" + - $ref: "#/components/schemas/UsageImagesResult" + - $ref: "#/components/schemas/UsageAudioSpeechesResult" + - $ref: "#/components/schemas/UsageAudioTranscriptionsResult" + - $ref: "#/components/schemas/UsageVectorStoresResult" + - $ref: "#/components/schemas/UsageCodeInterpreterSessionsResult" + - $ref: "#/components/schemas/CostsResult" + required: + - object + - start_time + - end_time + - result + UsageVectorStoresResult: + type: object + description: The aggregated vector stores usage details of the specific time bucket. + properties: + object: + type: string + enum: + - organization.usage.vector_stores.result + usage_bytes: + type: integer + description: The vector stores usage in bytes. + project_id: + type: string + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + required: + - object + - usage_bytes + x-oaiMeta: + name: Vector stores usage object + example: | + { + "object": "orgainzation.usage.vector_stores.result", + "usage_bytes": 1024, + "project_id": "proj_abc" + } User: type: object description: Represents an individual `user` within an organization. @@ -22596,6 +24680,78 @@ x-oaiMeta: - type: object key: AuditLog path: object + - id: usage + title: Usage + description: > + The **Usage API** provides detailed insights into your activity across + the OpenAI API. It also includes a separate [Costs + endpoint](/docs/api-reference/usage/costs), which offers visibility into + your spend, breaking down consumption by invoice line items and project + IDs. + + + While the Usage API delivers granular usage data, it may not always + reconcile perfectly with the Costs due to minor differences in how usage + and spend are recorded. For financial purposes, we recommend using the + [Costs endpoint](/docs/api-reference/usage/costs) or the [Costs + tab](/settings/organization/usage) in the Usage Dashboard, which will + reconcile back to your billing invoice. + navigationGroup: administration + sections: + - type: endpoint + key: usage-completions + path: completions + - type: object + key: UsageCompletionsResult + path: completions_object + - type: endpoint + key: usage-embeddings + path: embeddings + - type: object + key: UsageEmbeddingsResult + path: embeddings_object + - type: endpoint + key: usage-moderations + path: moderations + - type: object + key: UsageModerationsResult + path: moderations_object + - type: endpoint + key: usage-images + path: images + - type: object + key: UsageImagesResult + path: images_object + - type: endpoint + key: usage-audio-speeches + path: audio_speeches + - type: object + key: UsageAudioSpeechesResult + path: audio_speeches_object + - type: endpoint + key: usage-audio-transcriptions + path: audio_transcriptions + - type: object + key: UsageAudioTranscriptionsResult + path: audio_transcriptions_object + - type: endpoint + key: usage-vector-stores + path: vector_stores + - type: object + key: UsageVectorStoresResult + path: vector_stores_object + - type: endpoint + key: usage-code-interpreter-sessions + path: code_interpreter_sessions + - type: object + key: UsageCodeInterpreterSessionsResult + path: code_interpreter_sessions_object + - type: endpoint + key: usage-costs + path: costs + - type: object + key: CostsResult + path: costs_object - id: realtime title: Realtime beta: true