From 3b49d5d217eebd2541366457ff6f540f7f1aea48 Mon Sep 17 00:00:00 2001 From: Kevin Whinnery Date: Wed, 18 Dec 2024 15:05:34 -0600 Subject: [PATCH] Update openapi.yaml --- openapi.yaml | 6411 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 5145 insertions(+), 1266 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 7752078f..d9e8ac98 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -88,7 +88,7 @@ paths: description: > A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list - request and receive 100 objects, ending with obj_foo, your + request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. schema: @@ -965,7 +965,7 @@ paths: Your input file must be formatted as a [JSONL file](/docs/api-reference/batch/request-input), and must be uploaded with the purpose `batch`. The file can contain up - to 50,000 requests, and can be up to 100 MB in size. + to 50,000 requests, and can be up to 200 MB in size. endpoint: type: string enum: @@ -1338,6 +1338,19 @@ paths: [vision](/docs/guides/vision), and [audio](/docs/guides/audio) guides. + + + Parameter support can differ depending on the model used to generate the + + response, particularly for newer reasoning models. Parameters that are + only + + supported for reasoning models are noted below. For the current state + of + + unsupported parameters in reasoning models, + + [refer to the reasoning guide](/docs/guides/reasoning). requestBody: required: true content: @@ -1368,10 +1381,10 @@ 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", + "role": "developer", "content": "You are a helpful assistant." }, { @@ -1387,9 +1400,9 @@ 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": "developer", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ] ) @@ -1405,8 +1418,8 @@ paths: async function main() { const completion = await openai.chat.completions.create({ - messages: [{ role: "system", content: "You are a helpful assistant." }], - model: "VAR_model_id", + messages: [{ role: "developer", content: "You are a helpful assistant." }], + model: "VAR_chat_model_id", }); console.log(completion.choices[0]); @@ -1435,7 +1448,9 @@ paths: "completion_tokens": 12, "total_tokens": 21, "completion_tokens_details": { - "reasoning_tokens": 0 + "reasoning_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 } } } @@ -1544,7 +1559,9 @@ paths: "completion_tokens": 12, "total_tokens": 21, "completion_tokens_details": { - "reasoning_tokens": 0 + "reasoning_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 } } } @@ -1555,10 +1572,10 @@ 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", + "role": "developer", "content": "You are a helpful assistant." }, { @@ -1575,9 +1592,9 @@ 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": "developer", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ], stream=True @@ -1595,9 +1612,9 @@ 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": "developer", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ], stream: true, @@ -1700,7 +1717,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" @@ -1782,7 +1799,9 @@ paths: "completion_tokens": 17, "total_tokens": 99, "completion_tokens_details": { - "reasoning_tokens": 0 + "reasoning_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 } } } @@ -1793,7 +1812,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", @@ -1808,7 +1827,7 @@ paths: client = OpenAI() completion = client.chat.completions.create( - model="VAR_model_id", + model="VAR_chat_model_id", messages=[ {"role": "user", "content": "Hello!"} ], @@ -1826,7 +1845,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, }); @@ -2018,7 +2037,9 @@ paths: "completion_tokens": 9, "total_tokens": 18, "completion_tokens_details": { - "reasoning_tokens": 0 + "reasoning_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 } }, "system_fingerprint": null @@ -2057,7 +2078,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 @@ -2067,7 +2088,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 @@ -2079,7 +2100,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, @@ -2093,7 +2114,7 @@ paths: "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", "object": "text_completion", "created": 1589478378, - "model": "VAR_model_id", + "model": "VAR_completion_model_id", "system_fingerprint": "fp_44709d6fcb", "choices": [ { @@ -2116,7 +2137,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, @@ -2127,7 +2148,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, @@ -2141,7 +2162,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, }); @@ -2252,7 +2273,7 @@ paths: operationId: listFiles tags: - Files - summary: Returns a list of files that belong to the user's organization. + summary: Returns a list of files. parameters: - in: query name: purpose @@ -2260,6 +2281,35 @@ paths: schema: type: string description: Only return files with the given purpose. + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 10,000, and the default is 10,000. + required: false + schema: + type: integer + default: 10000 + - name: order + in: query + description: > + Sort order by the `created_at` timestamp of the objects. `asc` for + ascending order and `desc` for descending order. + schema: + type: string + default: desc + enum: + - asc + - desc + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + schema: + type: string responses: "200": description: OK @@ -2338,7 +2388,7 @@ paths: [completions](/docs/api-reference/fine-tuning/completions-input) models. - The Batch API only supports `.jsonl` files up to 100 MB in size. The + The Batch API only supports `.jsonl` files up to 200 MB in size. The input also has a specific required [format](/docs/api-reference/batch/request-input). @@ -2633,6 +2683,16 @@ paths: "status": "queued", "validation_file": null, "training_file": "file-abc123", + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "batch_size": "auto", + "learning_rate_multiplier": "auto", + "n_epochs": "auto", + } + } + } } - title: Epochs request: @@ -2643,8 +2703,13 @@ paths: -d '{ "training_file": "file-abc123", "model": "gpt-4o-mini", - "hyperparameters": { - "n_epochs": 2 + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "n_epochs": 2 + } + } } }' python: | @@ -2654,8 +2719,13 @@ paths: client.fine_tuning.jobs.create( training_file="file-abc123", model="gpt-4o-mini", - hyperparameters={ - "n_epochs":2 + method={ + "type": "supervised", + "supervised": { + "hyperparameters": { + "n_epochs": 2 + } + } } ) node.js: | @@ -2667,7 +2737,14 @@ paths: const fineTune = await openai.fineTuning.jobs.create({ training_file: "file-abc123", model: "gpt-4o-mini", - hyperparameters: { n_epochs: 2 } + method: { + type: "supervised", + supervised: { + hyperparameters: { + n_epochs: 2 + } + } + } }); console.log(fineTune); @@ -2687,6 +2764,16 @@ paths: "validation_file": null, "training_file": "file-abc123", "hyperparameters": {"n_epochs": 2}, + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "batch_size": "auto", + "learning_rate_multiplier": "auto", + "n_epochs": 2, + } + } + } } - title: Validation file request: @@ -2735,6 +2822,59 @@ paths: "status": "queued", "validation_file": "file-abc123", "training_file": "file-abc123", + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "batch_size": "auto", + "learning_rate_multiplier": "auto", + "n_epochs": "auto", + } + } + } + } + - title: DPO + request: + curl: | + curl https://api.openai.com/v1/fine_tuning/jobs \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "training_file": "file-abc123", + "validation_file": "file-abc123", + "model": "gpt-4o-mini", + "method": { + "type": "dpo", + "dpo": { + "hyperparameters": { + "beta": 0.1, + } + } + } + }' + response: | + { + "object": "fine_tuning.job", + "id": "ftjob-abc123", + "model": "gpt-4o-mini-2024-07-18", + "created_at": 1721764800, + "fine_tuned_model": null, + "organization_id": "org-123", + "result_files": [], + "status": "queued", + "validation_file": "file-abc123", + "training_file": "file-abc123", + "method": { + "type": "dpo", + "dpo": { + "hyperparameters": { + "beta": 0.1, + "batch_size": "auto", + "learning_rate_multiplier": "auto", + "n_epochs": "auto", + } + } + } } - title: W&B Integration request: @@ -2780,7 +2920,17 @@ paths: "run_id": "ftjob-abc123" } } - ] + ], + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "batch_size": "auto", + "learning_rate_multiplier": "auto", + "n_epochs": "auto", + } + } + } } get: operationId: listPaginatedFineTuningJobs @@ -2935,7 +3085,17 @@ paths: "trained_tokens": 5768, "integrations": [], "seed": 0, - "estimated_finish": 0 + "estimated_finish": 0, + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "n_epochs": 4, + "batch_size": 1, + "learning_rate_multiplier": 1.0 + } + } + } } /fine_tuning/jobs/{fine_tuning_job_id}/cancel: post: @@ -2999,9 +3159,6 @@ paths: "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], - "hyperparameters": { - "n_epochs": "auto" - }, "status": "cancelled", "validation_file": "file-abc123", "training_file": "file-abc123" @@ -3490,20 +3647,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); } @@ -3511,7 +3668,7 @@ paths: main(); response: | { - "id": "VAR_model_id", + "id": "VAR_chat_model_id", "object": "model", "created": 1686935002, "owned_by": "openai" @@ -3919,7 +4076,7 @@ paths: description: > A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list - request and receive 100 objects, ending with obj_foo, your + request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. schema: @@ -3941,7 +4098,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", @@ -3991,6 +4148,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": "organization.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. @@ -4627,10 +4894,10 @@ paths: "archived_at": 1711471533, "status": "archived" } - /organization/projects/{project_id}/service_accounts: + /organization/projects/{project_id}/rate_limits: get: - summary: Returns a list of service accounts in the project. - operationId: list-project-service-accounts + summary: Returns the rate limits per model for a project. + operationId: list-project-rate-limits tags: - Projects parameters: @@ -4642,13 +4909,12 @@ paths: type: string - name: limit in: query - description: > - A limit on the number of objects to be returned. Limit can range - between 1 and 100, and the default is 20. + description: | + A limit on the number of objects to be returned. The default is 100. required: false schema: type: integer - default: 20 + default: 100 - name: after in: query description: > @@ -4659,54 +4925,64 @@ paths: required: false schema: type: string + - name: before + in: query + description: > + A cursor for use in pagination. `before` is an object ID that + defines your place in the list. For instance, if you make a list + request and receive 100 objects, beginning with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the + previous page of the list. + required: false + schema: + type: string responses: "200": - description: Project service accounts listed successfully. + description: Project rate limits listed successfully. content: application/json: schema: - $ref: "#/components/schemas/ProjectServiceAccountListResponse" - "400": - description: Error response when project is archived. - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" + $ref: "#/components/schemas/ProjectRateLimitListResponse" x-oaiMeta: - name: List project service accounts + name: List project rate limits group: administration returns: A list of - [ProjectServiceAccount](/docs/api-reference/project-service-accounts/object) + [ProjectRateLimit](/docs/api-reference/project-rate-limits/object) objects. examples: request: curl: > curl - https://api.openai.com/v1/organization/projects/proj_abc/service_accounts?after=custom_id&limit=20 + https://api.openai.com/v1/organization/projects/proj_abc/rate_limits?after=rl_xxx&limit=20 \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" - response: - content: | - { - "object": "list", - "data": [ - { - "object": "organization.project.service_account", - "id": "svc_acct_abc", - "name": "Service Account", - "role": "owner", - "created_at": 1711471533 - } - ], - "first_id": "svc_acct_abc", - "last_id": "svc_acct_xyz", - "has_more": false - } + response: | + { + "object": "list", + "data": [ + { + "object": "project.rate_limit", + "id": "rl-ada", + "model": "ada", + "max_requests_per_1_minute": 600, + "max_tokens_per_1_minute": 150000, + "max_images_per_1_minute": 10 + } + ], + "first_id": "rl-ada", + "last_id": "rl-ada", + "has_more": false + } + error_response: | + { + "code": 404, + "message": "The project {project_id} was not found" + } + /organization/projects/{project_id}/rate_limits/{rate_limit_id}: post: - summary: Creates a new service account in the project. This also returns an - unredacted API key for the service account. - operationId: create-project-service-account + summary: Updates a project rate limit. + operationId: update-project-rate-limits tags: - Projects parameters: @@ -4716,64 +4992,210 @@ paths: required: true schema: type: string + - name: rate_limit_id + in: path + description: The ID of the rate limit. + required: true + schema: + type: string requestBody: - description: The project service account create request payload. + description: The project rate limit update request payload. required: true content: application/json: schema: - $ref: "#/components/schemas/ProjectServiceAccountCreateRequest" + $ref: "#/components/schemas/ProjectRateLimitUpdateRequest" responses: "200": - description: Project service account created successfully. + description: Project rate limit updated successfully. content: application/json: schema: - $ref: "#/components/schemas/ProjectServiceAccountCreateResponse" + $ref: "#/components/schemas/ProjectRateLimit" "400": - description: Error response when project is archived. + description: Error response for various conditions. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" x-oaiMeta: - name: Create project service account + name: Modify project rate limit group: administration - returns: The created - [ProjectServiceAccount](/docs/api-reference/project-service-accounts/object) + returns: The updated + [ProjectRateLimit](/docs/api-reference/project-rate-limits/object) object. examples: request: curl: > curl -X POST - https://api.openai.com/v1/organization/projects/proj_abc/service_accounts + https://api.openai.com/v1/organization/projects/proj_abc/rate_limits/rl_xxx \ -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ -H "Content-Type: application/json" \ -d '{ - "name": "Production App" + "max_requests_per_1_minute": 500 }' - response: - content: | - { - "object": "organization.project.service_account", - "id": "svc_acct_abc", - "name": "Production App", - "role": "member", - "created_at": 1711471533, - "api_key": { - "object": "organization.project.service_account.api_key", - "value": "sk-abcdefghijklmnop123", - "name": "Secret Key", - "created_at": 1711471533, - "id": "key_abc" - } + response: | + { + "object": "project.rate_limit", + "id": "rl-ada", + "model": "ada", + "max_requests_per_1_minute": 600, + "max_tokens_per_1_minute": 150000, + "max_images_per_1_minute": 10 } - /organization/projects/{project_id}/service_accounts/{service_account_id}: + error_response: | + { + "code": 404, + "message": "The project {project_id} was not found" + } + /organization/projects/{project_id}/service_accounts: get: - summary: Retrieves a service account in the project. - operationId: retrieve-project-service-account - tags: + summary: Returns a list of service accounts in the project. + operationId: list-project-service-accounts + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + required: false + schema: + type: string + responses: + "200": + description: Project service accounts listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectServiceAccountListResponse" + "400": + description: Error response when project is archived. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: List project service accounts + group: administration + returns: A list of + [ProjectServiceAccount](/docs/api-reference/project-service-accounts/object) + objects. + examples: + request: + curl: > + curl + https://api.openai.com/v1/organization/projects/proj_abc/service_accounts?after=custom_id&limit=20 + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: + content: | + { + "object": "list", + "data": [ + { + "object": "organization.project.service_account", + "id": "svc_acct_abc", + "name": "Service Account", + "role": "owner", + "created_at": 1711471533 + } + ], + "first_id": "svc_acct_abc", + "last_id": "svc_acct_xyz", + "has_more": false + } + post: + summary: Creates a new service account in the project. This also returns an + unredacted API key for the service account. + operationId: create-project-service-account + tags: + - Projects + parameters: + - name: project_id + in: path + description: The ID of the project. + required: true + schema: + type: string + requestBody: + description: The project service account create request payload. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectServiceAccountCreateRequest" + responses: + "200": + description: Project service account created successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/ProjectServiceAccountCreateResponse" + "400": + description: Error response when project is archived. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + x-oaiMeta: + name: Create project service account + group: administration + returns: The created + [ProjectServiceAccount](/docs/api-reference/project-service-accounts/object) + object. + examples: + request: + curl: > + curl -X POST + https://api.openai.com/v1/organization/projects/proj_abc/service_accounts + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "Production App" + }' + response: + content: | + { + "object": "organization.project.service_account", + "id": "svc_acct_abc", + "name": "Production App", + "role": "member", + "created_at": 1711471533, + "api_key": { + "object": "organization.project.service_account.api_key", + "value": "sk-abcdefghijklmnop123", + "name": "Secret Key", + "created_at": 1711471533, + "id": "key_abc" + } + } + /organization/projects/{project_id}/service_accounts/{service_account_id}: + get: + summary: Retrieves a service account in the project. + operationId: retrieve-project-service-account + tags: - Projects parameters: - name: project_id @@ -5173,204 +5595,1382 @@ paths: "id": "user_abc", "deleted": true } - /organization/users: + /organization/usage/audio_speeches: get: - summary: Lists all of the users in the organization. - operationId: list-users + summary: Get audio speeches usage details for the organization. + operationId: usage-audio-speeches tags: - - Users + - Usage parameters: - - name: limit + - name: start_time in: query - description: > - A limit on the number of objects to be returned. Limit can range - between 1 and 100, and the default is 20. + 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 - default: 20 - - name: after + - name: bucket_width in: query - description: > - A cursor for use in pagination. `after` is an object ID that defines - your place in the list. For instance, if you make a list request and - receive 100 objects, ending with obj_foo, your subsequent call can - include after=obj_foo in order to fetch the next page of the list. + 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: Users listed successfully. + description: Usage data retrieved successfully. content: application/json: schema: - $ref: "#/components/schemas/UserListResponse" + $ref: "#/components/schemas/UsageResponse" x-oaiMeta: - name: List users - group: administration - returns: A list of [User](/docs/api-reference/users/object) objects. + 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/users?after=user_abc&limit=20 + "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: - content: | - { - "object": "list", - "data": [ - { - "object": "organization.user", - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "added_at": 1711471533 - } - ], - "first_id": "user-abc", - "last_id": "user-xyz", - "has_more": false - } - /organization/users/{user_id}: + + -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": "organization.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: Retrieves a user by their identifier. - operationId: retrieve-user + summary: Get audio transcriptions usage details for the organization. + operationId: usage-audio-transcriptions tags: - - Users + - Usage parameters: - - name: user_id - in: path - description: The ID of the user. + - name: start_time + in: query + description: Start time (Unix seconds) of the query time range, inclusive. required: true schema: - type: string - responses: - "200": - description: User retrieved successfully. + 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/User" + $ref: "#/components/schemas/UsageResponse" x-oaiMeta: - name: Retrieve user - group: administration - returns: The [User](/docs/api-reference/users/object) object matching the - specified ID. + 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/users/user_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" - response: - content: | - { - "object": "organization.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 organization. - operationId: modify-user + 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": "organization.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: - - Users + - Usage parameters: - - name: user_id - in: path - description: The ID of the user. + - 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 - requestBody: - description: The new user role to modify. This must be one of `owner` or `member`. - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/UserRoleUpdateRequest" responses: "200": - description: User role updated successfully. + description: Usage data retrieved successfully. content: application/json: schema: - $ref: "#/components/schemas/User" + $ref: "#/components/schemas/UsageResponse" x-oaiMeta: - name: Modify user - group: administration - returns: The updated [User](/docs/api-reference/users/object) object. + 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 -X POST https://api.openai.com/v1/organization/users/user_abc + 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" \ - -d '{ - "role": "owner" - }' - response: - content: | - { - "object": "organization.user", - "id": "user_abc", - "name": "First Last", - "email": "user@example.com", - "role": "owner", - "added_at": 1711471533 - } - delete: - summary: Deletes a user from the organization. - operationId: delete-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": "organization.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: - - Users + - Usage parameters: - - name: user_id - in: path - description: The ID of the user. + - 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: User deleted successfully. + description: Usage data retrieved successfully. content: application/json: schema: - $ref: "#/components/schemas/UserDeleteResponse" + $ref: "#/components/schemas/UsageResponse" x-oaiMeta: - name: Delete user - group: administration - returns: Confirmation of the deleted user + 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 -X DELETE - https://api.openai.com/v1/organization/users/user_abc \ - -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ - -H "Content-Type: application/json" - response: - content: | - { - "object": "organization.user.deleted", - "id": "user_abc", - "deleted": true - } - /threads: - post: - operationId: createThread - tags: - - Assistants - summary: Create a thread. - requestBody: + 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": "organization.usage.completions.result", + "input_tokens": 1000, + "output_tokens": 500, + "input_cached_tokens": 800, + "input_audio_tokens": 0, + "output_audio_tokens": 0, + "num_model_requests": 5, + "project_id": null, + "user_id": null, + "api_key_id": null, + "model": null, + "batch": null + } + ] + } + ], + "has_more": true, + "next_page": "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": "organization.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: Usage data retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UsageResponse" + x-oaiMeta: + 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/usage/images?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": "organization.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: + - 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: Moderations + group: usage-moderations + returns: A list of paginated, time bucketed [Moderations + usage](/docs/api-reference/usage/moderations_object) objects. + examples: + request: + curl: > + 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" + response: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.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: + - 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: 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 + "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: > + { + "object": "page", + "data": [ + { + "object": "bucket", + "start_time": 1730419200, + "end_time": 1730505600, + "results": [ + { + "object": "organization.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. + operationId: list-users + tags: + - Users + parameters: + - name: limit + in: query + description: > + A limit on the number of objects to be returned. Limit can range + between 1 and 100, and the default is 20. + required: false + schema: + type: integer + default: 20 + - name: after + in: query + description: > + A cursor for use in pagination. `after` is an object ID that defines + your place in the list. For instance, if you make a list request and + receive 100 objects, ending with obj_foo, your subsequent call can + include after=obj_foo in order to fetch the next page of the list. + required: false + schema: + type: string + responses: + "200": + description: Users listed successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UserListResponse" + x-oaiMeta: + name: List users + group: administration + returns: A list of [User](/docs/api-reference/users/object) objects. + examples: + request: + curl: > + curl + https://api.openai.com/v1/organization/users?after=user_abc&limit=20 + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: + content: | + { + "object": "list", + "data": [ + { + "object": "organization.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + ], + "first_id": "user-abc", + "last_id": "user-xyz", + "has_more": false + } + /organization/users/{user_id}: + get: + summary: Retrieves a user by their identifier. + operationId: retrieve-user + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user. + required: true + schema: + type: string + responses: + "200": + description: User retrieved successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/User" + x-oaiMeta: + name: Retrieve user + group: administration + returns: The [User](/docs/api-reference/users/object) object matching the + specified ID. + examples: + request: + curl: | + curl https://api.openai.com/v1/organization/users/user_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: + content: | + { + "object": "organization.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 organization. + operationId: modify-user + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user. + required: true + schema: + type: string + requestBody: + description: The new user role to modify. This must be one of `owner` or `member`. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/UserRoleUpdateRequest" + responses: + "200": + description: User role updated successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/User" + x-oaiMeta: + name: Modify user + group: administration + returns: The updated [User](/docs/api-reference/users/object) object. + examples: + request: + curl: > + curl -X POST https://api.openai.com/v1/organization/users/user_abc + \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "role": "owner" + }' + response: + content: | + { + "object": "organization.user", + "id": "user_abc", + "name": "First Last", + "email": "user@example.com", + "role": "owner", + "added_at": 1711471533 + } + delete: + summary: Deletes a user from the organization. + operationId: delete-user + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user. + required: true + schema: + type: string + responses: + "200": + description: User deleted successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/UserDeleteResponse" + x-oaiMeta: + name: Delete user + group: administration + returns: Confirmation of the deleted user + examples: + request: + curl: > + curl -X DELETE + https://api.openai.com/v1/organization/users/user_abc \ + -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \ + -H "Content-Type: application/json" + response: + content: | + { + "object": "organization.user.deleted", + "id": "user_abc", + "deleted": true + } + /realtime/sessions: + post: + summary: > + Create an ephemeral API token for use in client-side applications with + the + + Realtime API. Can be configured with the same session parameters as the + + `session.update` client event. + + + It responds with a session object, plus a `client_secret` key which + contains + + a usable ephemeral API token that can be used to authenticate browser + clients + + for the Realtime API. + operationId: create-realtime-session + tags: + - Realtime + requestBody: + description: Create an ephemeral API key with the given session configuration. + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/RealtimeSessionCreateRequest" + responses: + "200": + description: Session created successfully. + content: + application/json: + schema: + $ref: "#/components/schemas/RealtimeSessionCreateResponse" + x-oaiMeta: + name: Create session + group: realtime + returns: The created Realtime session object, plus an ephemeral key + examples: + request: + curl: | + curl -X POST https://api.openai.com/v1/realtime/sessions \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "gpt-4o-realtime-preview-2024-12-17", + "modalities": ["audio", "text"], + "instructions": "You are a friendly assistant." + }' + response: | + { + "id": "sess_001", + "object": "realtime.session", + "model": "gpt-4o-realtime-preview-2024-12-17", + "modalities": ["audio", "text"], + "instructions": "You are a friendly assistant.", + "voice": "alloy", + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": { + "model": "whisper-1" + }, + "turn_detection": null, + "tools": [], + "tool_choice": "none", + "temperature": 0.7, + "max_response_output_tokens": 200, + "client_secret": { + "value": "ek_abc123", + "expires_at": 1234567890 + } + } + /threads: + post: + operationId: createThread + tags: + - Assistants + summary: Create a thread. + requestBody: content: application/json: schema: @@ -6229,7 +7829,7 @@ paths: description: > A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list - request and receive 100 objects, ending with obj_foo, your + request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. schema: @@ -6728,7 +8328,7 @@ paths: description: > A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list - request and receive 100 objects, ending with obj_foo, your + request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. schema: @@ -6900,7 +8500,7 @@ paths: See the [file search tool - documentation](/docs/assistants/tools/file-search/customizing-file-search-settings) + documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. schema: type: array @@ -7718,7 +9318,7 @@ paths: description: > A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list - request and receive 100 objects, ending with obj_foo, your + request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. schema: @@ -7733,7 +9333,7 @@ paths: See the [file search tool - documentation](/docs/assistants/tools/file-search/customizing-file-search-settings) + documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. schema: type: array @@ -7856,7 +9456,7 @@ paths: See the [file search tool - documentation](/docs/assistants/tools/file-search/customizing-file-search-settings) + documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. schema: type: array @@ -8293,7 +9893,7 @@ paths: Please refer to documentation for the supported MIME types for your use case: - - [Assistants](/docs/assistants/tools/file-search/supported-files) + - [Assistants](/docs/assistants/tools/file-search#supported-files) For guidance on the proper filename extensions for each purpose, please @@ -8554,7 +10154,7 @@ paths: description: > A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list - request and receive 100 objects, ending with obj_foo, your + request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. schema: @@ -9216,7 +10816,7 @@ paths: description: > A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list - request and receive 100 objects, ending with obj_foo, your + request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. schema: @@ -9351,7 +10951,7 @@ paths: description: > A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list - request and receive 100 objects, ending with obj_foo, your + request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. schema: @@ -9713,8 +11313,8 @@ components: description: > ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your - available models, or see our [Model overview](/docs/models/overview) - for descriptions of them. + available models, or see our [Model overview](/docs/models) for + descriptions of them. type: string instructions: description: > @@ -9932,7 +11532,7 @@ components: Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool - documentation](/docs/assistants/tools/file-search/customizing-file-search-settings) + documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. ranking_options: $ref: "#/components/schemas/FileSearchRankingOptions" @@ -9966,8 +11566,8 @@ components: AssistantsApiResponseFormatOption: description: > Specifies the format that the model must output. Compatible with - [GPT-4o](/docs/models/gpt-4o), [GPT-4 - Turbo](/docs/models/gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models + [GPT-4o](/docs/models#gpt-4o), [GPT-4 + Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. @@ -10251,6 +11851,44 @@ components: id: type: string description: The project ID. + rate_limit.updated: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The rate limit ID + changes_requested: + type: object + description: The payload used to update the rate limits. + properties: + max_requests_per_1_minute: + type: integer + description: The maximum requests per minute. + max_tokens_per_1_minute: + type: integer + description: The maximum tokens per minute. + max_images_per_1_minute: + type: integer + description: The maximum images per minute. Only relevant for certain models. + max_audio_megabytes_per_1_minute: + type: integer + description: The maximum audio megabytes per minute. Only relevant for certain + models. + max_requests_per_1_day: + type: integer + description: The maximum requests per day. Only relevant for certain models. + batch_1_day_max_input_tokens: + type: integer + description: The maximum batch input tokens per day. Only relevant for certain + models. + rate_limit.deleted: + type: object + description: The details for events with this `type`. + properties: + id: + type: string + description: The rate limit ID service_account.created: type: object description: The details for events with this `type`. @@ -10432,6 +12070,8 @@ components: - service_account.created - service_account.updated - service_account.deleted + - rate_limit.updated + - rate_limit.deleted - user.added - user.updated - user.deleted @@ -10827,6 +12467,8 @@ components: ChatCompletionRequestAssistantMessage: type: object title: Assistant message + description: | + Messages sent by the model in response to user messages. properties: content: x-oaiExpandable: true @@ -10901,6 +12543,43 @@ components: - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" - $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartRefusal" x-oaiExpandable: true + ChatCompletionRequestDeveloperMessage: + type: object + title: Developer message + description: > + Developer-provided instructions that the model should follow, regardless + of + + messages sent by the user. With o1 models and newer, `developer` + messages + + replace the previous `system` messages. + properties: + content: + description: The contents of the developer message. + oneOf: + - type: string + description: The contents of the developer message. + title: Text content + - type: array + description: An array of content parts with a defined type. For developer + messages, only type `text` is supported. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + minItems: 1 + role: + type: string + enum: + - developer + description: The role of the messages author, in this case `developer`. + name: + type: string + description: An optional name for the participant. Provides the model + information to differentiate between participants of the same role. + required: + - content + - role ChatCompletionRequestFunctionMessage: type: object title: Function message @@ -10924,6 +12603,7 @@ components: - name ChatCompletionRequestMessage: oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestDeveloperMessage" - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" @@ -10982,7 +12662,7 @@ components: detail: type: string description: Specifies the detail level of the image. Learn more in the [Vision - guide](/docs/guides/vision/low-or-high-fidelity-image-understanding). + guide](/docs/guides/vision#low-or-high-fidelity-image-understanding). enum: - auto - low @@ -11028,6 +12708,14 @@ components: ChatCompletionRequestSystemMessage: type: object title: System message + description: > + Developer-provided instructions that the model should follow, regardless + of + + messages sent by the user. With o1 models and newer, use `developer` + messages + + for this purpose instead. properties: content: description: The contents of the system message. @@ -11094,6 +12782,9 @@ components: ChatCompletionRequestUserMessage: type: object title: User message + description: | + Messages sent by an end user, containing prompts or additional context + information. properties: content: description: | @@ -11398,12 +13089,30 @@ components: type: object description: Breakdown of tokens used in a completion. properties: + accepted_prediction_tokens: + type: integer + description: | + When using Predicted Outputs, the number of tokens in the + prediction that appeared in the completion. audio_tokens: type: integer description: Audio input tokens generated by the model. reasoning_tokens: type: integer description: Tokens generated by the model for reasoning. + rejected_prediction_tokens: + type: integer + description: > + When using Predicted Outputs, the number of tokens in the + + prediction that did not appear in the completion. However, like + + reasoning tokens, these tokens are still counted in the total + + completion tokens for purposes of billing, output, and context + window + + limits. prompt_tokens_details: type: object description: Breakdown of tokens used in the prompt. @@ -11418,6 +13127,49 @@ 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 + nullable: true + description: When `group_by=line_item`, this field provides the line item of the + grouped costs result. + project_id: + type: string + nullable: true + 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": "organization.costs.result", + "amount": { + "value": 0.06, + "currency": "usd" + }, + "line_item": "Image models", + "project_id": "proj_abc" + } CreateAssistantRequest: type: object additionalProperties: false @@ -11426,17 +13178,17 @@ components: description: > ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your - available models, or see our [Model overview](/docs/models/overview) - for descriptions of them. + available models, or see our [Model overview](/docs/models) for + descriptions of them. example: gpt-4o anyOf: - type: string - 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 @@ -11760,7 +13512,9 @@ components: "completion_tokens": 17, "total_tokens": 99, "completion_tokens_details": { - "reasoning_tokens": 0 + "reasoning_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 } } } @@ -11792,7 +13546,9 @@ components: "completion_tokens": 12, "total_tokens": 21, "completion_tokens_details": { - "reasoning_tokens": 0 + "reasoning_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 } } } @@ -11816,25 +13572,28 @@ components: $ref: "#/components/schemas/ChatCompletionRequestMessage" model: description: ID of the model to use. See the [model endpoint - compatibility](/docs/models/model-endpoint-compatibility) table for + compatibility](/docs/models#model-endpoint-compatibility) table for details on which models work with the Chat API. example: gpt-4o anyOf: - type: string - type: string enum: + - o1 + - o1-2024-12-17 - o1-preview - o1-preview-2024-09-12 - 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 - gpt-4o-audio-preview-2024-10-01 + - gpt-4o-audio-preview-2024-12-17 + - gpt-4o-mini-audio-preview + - gpt-4o-mini-audio-preview-2024-12-17 - chatgpt-4o-latest - gpt-4o-mini - gpt-4o-mini-2024-07-18 @@ -11864,9 +13623,33 @@ components: nullable: true description: > Whether or not to store the output of this chat completion request + for + + use in our [model distillation](/docs/guides/distillation) or - for use in our [model distillation](/docs/guides/distillation) or [evals](/docs/guides/evals) products. + reasoning_effort: + type: string + enum: + - low + - medium + - high + default: medium + description: > + **o1 models only** + + + Constrains effort on reasoning for + + [reasoning + models](https://platform.openai.com/docs/guides/reasoning). + + Currently supported values are `low`, `medium`, and `high`. Reducing + + reasoning effort can result in faster responses and fewer tokens + used + + on reasoning in a response. metadata: type: object nullable: true @@ -11883,12 +13666,11 @@ components: nullable: true description: > Number between -2.0 and 2.0. Positive values penalize new tokens - based on their existing frequency in the text so far, decreasing the - model's likelihood to repeat the same line verbatim. + based on + their existing frequency in the text so far, decreasing the model's - [See more information about frequency and presence - penalties.](/docs/guides/text-generation/parameter-details) + likelihood to repeat the same line verbatim. logit_bias: type: object x-oaiTypeLabel: map @@ -11901,25 +13683,42 @@ components: completion. - Accepts a JSON object that maps tokens (specified by their token ID - in the tokenizer) to an associated bias value from -100 to 100. - Mathematically, the bias is added to the logits generated by the - model prior to sampling. The exact effect will vary per model, but - values between -1 and 1 should decrease or increase likelihood of - selection; values like -100 or 100 should result in a ban or - exclusive selection of the relevant token. + Accepts a JSON object that maps tokens (specified by their token ID + in the + + tokenizer) to an associated bias value from -100 to 100. + Mathematically, + + the bias is added to the logits generated by the model prior to + sampling. + + The exact effect will vary per model, but values between -1 and 1 + should + + decrease or increase likelihood of selection; values like -100 or + 100 + + should result in a ban or exclusive selection of the relevant token. logprobs: - description: Whether to return log probabilities of the output tokens or not. If - true, returns the log probabilities of each output token returned in - the `content` of `message`. + description: > + Whether to return log probabilities of the output tokens or not. If + true, + + returns the log probabilities of each output token returned in the + + `content` of `message`. type: boolean default: false nullable: true top_logprobs: - description: An integer between 0 and 20 specifying the number of most likely - tokens to return at each token position, each with an associated log - probability. `logprobs` must be set to `true` if this parameter is - used. + description: > + An integer between 0 and 20 specifying the number of most likely + tokens to + + return at each token position, each with an associated log + probability. + + `logprobs` must be set to `true` if this parameter is used. type: integer minimum: 0 maximum: 20 @@ -11927,13 +13726,17 @@ components: max_tokens: description: > The maximum number of [tokens](/tokenizer) that can be generated in - the chat completion. This value can be used to control + the + + chat completion. This value can be used to control + [costs](https://openai.com/api/pricing/) for text generated via API. This value is now deprecated in favor of `max_completion_tokens`, - and is not compatible with [o1 series - models](/docs/guides/reasoning). + and is + + not compatible with [o1 series models](/docs/guides/reasoning). type: integer nullable: true deprecated: true @@ -11957,6 +13760,21 @@ components: minimize costs. modalities: $ref: "#/components/schemas/ChatCompletionModalities" + prediction: + nullable: true + x-oaiExpandable: true + description: > + Configuration for a [Predicted + Output](/docs/guides/predicted-outputs), + + which can greatly improve response times when large parts of the + model + + response are known ahead of time. This is most common when you are + + regenerating a file with only minor changes to most of the content. + oneOf: + - $ref: "#/components/schemas/PredictionContent" audio: type: object nullable: true @@ -11974,14 +13792,18 @@ components: type: string enum: - alloy + - ash + - ballad + - coral - echo - - fable - - onyx - - nova + - sage - shimmer - description: | - Specifies the voice type. Supported voices are `alloy`, `echo`, - `fable`, `onyx`, `nova`, and `shimmer`. + - verse + description: > + 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: @@ -11994,7 +13816,7 @@ components: Specifies the output audio format. Must be one of `wav`, `mp3`, `flac`, - `opus`, or `pcm16`. + `opus`, or `pcm16`. presence_penalty: type: number default: 0 @@ -12003,39 +13825,51 @@ components: nullable: true description: > Number between -2.0 and 2.0. Positive values penalize new tokens - based on whether they appear in the text so far, increasing the - model's likelihood to talk about new topics. + based on + whether they appear in the text so far, increasing the model's + likelihood - [See more information about frequency and presence - penalties.](/docs/guides/text-generation/parameter-details) + to talk about new topics. response_format: description: > An object specifying the format that the model must output. - Compatible with [GPT-4o](/docs/models/gpt-4o), [GPT-4o - mini](/docs/models/gpt-4o-mini), [GPT-4 - Turbo](/docs/models/gpt-4-and-gpt-4-turbo) and all GPT-3.5 Turbo - models newer than `gpt-3.5-turbo-1106`. Setting to `{ "type": "json_schema", "json_schema": {...} }` enables + Structured Outputs which ensures the model will match your supplied - JSON schema. Learn more in the [Structured Outputs + JSON + + schema. Learn more in the [Structured Outputs + guide](/docs/guides/structured-outputs). Setting to `{ "type": "json_object" }` enables JSON mode, which - ensures the message the model generates is valid JSON. + ensures + + the message the model generates is valid JSON. **Important:** when using JSON mode, you **must** also instruct the - model to produce JSON yourself via a system or user message. Without - this, the model may generate an unending stream of whitespace until - the generation reaches the token limit, resulting in a long-running - and seemingly "stuck" request. Also note that the message content - may be partially cut off if `finish_reason="length"`, which - indicates the generation exceeded `max_tokens` or the conversation - exceeded the max context length. + model + + to produce JSON yourself via a system or user message. Without this, + the + + model may generate an unending stream of whitespace until the + generation + + reaches the token limit, resulting in a long-running and seemingly + "stuck" + + request. Also note that the message content may be partially cut off + if + + `finish_reason="length"`, which indicates the generation exceeded + + `max_tokens` or the conversation exceeded the max context length. oneOf: - $ref: "#/components/schemas/ResponseFormatText" - $ref: "#/components/schemas/ResponseFormatJsonObject" @@ -12063,7 +13897,7 @@ components: Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service: - - If set to 'auto', and the Project is Scale tier enabled, the system will utilize scale tier credits until they are exhausted. + - If set to 'auto', and the Project is Scale tier enabled, the system will utilize scale tier credits until they are exhausted. - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. - When not set, the default behavior is 'auto'. @@ -12112,7 +13946,6 @@ components: like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. - We generally recommend altering this or `top_p` but not both. top_p: type: number @@ -12123,9 +13956,15 @@ components: nullable: true description: > An alternative to sampling with temperature, called nucleus - sampling, where the model considers the results of the tokens with - top_p probability mass. So 0.1 means only the tokens comprising the - top 10% probability mass are considered. + sampling, + + where the model considers the results of the tokens with top_p + probability + + mass. So 0.1 means only the tokens comprising the top 10% + probability mass + + are considered. We generally recommend altering this or `temperature` but not both. @@ -12148,7 +13987,7 @@ components: description: > A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn - more](/docs/guides/safety-best-practices/end-user-ids). + more](/docs/guides/safety-best-practices#end-user-ids). function_call: deprecated: true description: > @@ -12157,18 +13996,29 @@ components: Controls which (if any) function is called by the model. + `none` means the model will not call a function and instead - generates a message. + generates a + + message. + `auto` means the model can pick between generating a message or - calling a function. + calling a + + function. + Specifying a particular function via `{"name": "my_function"}` - forces the model to call that function. + forces the + + model to call that function. `none` is the default when no functions are present. `auto` is the - default if functions are present. + default + + if functions are present. oneOf: - type: string description: > @@ -12329,7 +14179,9 @@ components: "cached_tokens": 0 }, "completion_tokens_details": { - "reasoning_tokens": 0 + "reasoning_tokens": 0, + "accepted_prediction_tokens": 0, + "rejected_prediction_tokens": 0 } }, "system_fingerprint": "fp_6b68a8204b" @@ -12437,6 +14289,7 @@ components: - chat.completion.chunk usage: type: object + nullable: true description: > An optional field that will only be present when you set `stream_options: {"include_usage": true}` in your request. @@ -12490,8 +14343,8 @@ components: description: > ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your - available models, or see our [Model overview](/docs/models/overview) - for descriptions of them. + available models, or see our [Model overview](/docs/models) for + descriptions of them. anyOf: - type: string - type: string @@ -12572,7 +14425,7 @@ components: [See more information about frequency and presence - penalties.](/docs/guides/text-generation/parameter-details) + penalties.](/docs/guides/text-generation) logit_bias: type: object x-oaiTypeLabel: map @@ -12654,7 +14507,7 @@ components: [See more information about frequency and presence - penalties.](/docs/guides/text-generation/parameter-details) + penalties.](/docs/guides/text-generation) seed: type: integer minimum: -9223372036854776000 @@ -12743,7 +14596,7 @@ components: description: > A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn - more](/docs/guides/safety-best-practices/end-user-ids). + more](/docs/guides/safety-best-practices#end-user-ids). required: - model - prompt @@ -12918,8 +14771,8 @@ components: description: > ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your - available models, or see our [Model overview](/docs/models/overview) - for descriptions of them. + available models, or see our [Model overview](/docs/models) for + descriptions of them. example: text-embedding-3-small anyOf: - type: string @@ -12950,7 +14803,7 @@ components: description: > A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn - more](/docs/guides/safety-best-practices/end-user-ids). + more](/docs/guides/safety-best-practices#end-user-ids). required: - model - input @@ -13024,7 +14877,7 @@ components: The name of the model to fine-tune. You can select one of the [supported - models](/docs/guides/fine-tuning/which-models-can-be-fine-tuned). + models](/docs/guides/fine-tuning#which-models-can-be-fine-tuned). example: gpt-4o-mini anyOf: - type: string @@ -13049,8 +14902,10 @@ components: The contents of the file should differ depending on if the model - uses the [chat](/docs/api-reference/fine-tuning/chat-input) or + uses the [chat](/docs/api-reference/fine-tuning/chat-input), [completions](/docs/api-reference/fine-tuning/completions-input) + format, or if the fine-tuning method uses the + [preference](/docs/api-reference/fine-tuning/preference-input) format. @@ -13060,7 +14915,11 @@ components: example: file-abc123 hyperparameters: type: object - description: The hyperparameters used for the fine-tuning job. + description: > + The hyperparameters used for the fine-tuning job. + + This value is now deprecated in favor of `method`, and should be + passed in under the `method` parameter. properties: batch_size: description: > @@ -13104,6 +14963,7 @@ components: minimum: 1 maximum: 50 default: auto + deprecated: true suffix: description: > A string of up to 64 characters that will be added to your @@ -13218,6 +15078,8 @@ components: minimum: 0 maximum: 2147483647 example: 42 + method: + $ref: "#/components/schemas/FineTuneMethod" required: - model - training_file @@ -13289,7 +15151,7 @@ components: description: > A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn - more](/docs/guides/safety-best-practices/end-user-ids). + more](/docs/guides/safety-best-practices#end-user-ids). required: - prompt - image @@ -13376,7 +15238,7 @@ components: description: > A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn - more](/docs/guides/safety-best-practices/end-user-ids). + more](/docs/guides/safety-best-practices#end-user-ids). required: - prompt CreateImageVariationRequest: @@ -13436,7 +15298,7 @@ components: description: > A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn - more](/docs/guides/safety-best-practices/end-user-ids). + more](/docs/guides/safety-best-practices#end-user-ids). required: - image CreateMessageRequest: @@ -13470,7 +15332,7 @@ components: description: An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible - models](/docs/models/overview). + models](/docs/models). title: Array of content parts items: oneOf: @@ -13579,7 +15441,7 @@ components: description: | The content moderation model you would like to use. Learn more in [the moderation guide](/docs/guides/moderation), and learn about - available models [here](/docs/models/moderation). + available models [here](/docs/models#moderation). nullable: false default: omni-moderation-latest example: omni-moderation-2024-09-26 @@ -13987,9 +15849,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 @@ -14125,7 +15987,7 @@ components: properties: model: description: > - One of the available [TTS models](/docs/models/tts): `tts-1` or + One of the available [TTS models](/docs/models#tts): `tts-1` or `tts-1-hd` anyOf: - type: string @@ -14143,7 +16005,7 @@ components: description: The voice to use when generating the audio. Supported voices are `alloy`, `echo`, `fable`, `onyx`, `nova`, and `shimmer`. Previews of the voices are available in the [Text to speech - guide](/docs/guides/text-to-speech/voice-options). + guide](/docs/guides/text-to-speech#voice-options). type: string enum: - alloy @@ -14197,9 +16059,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 @@ -14524,7 +16386,7 @@ components: prompt: description: > An optional text to guide the model's style or continue a previous - audio segment. The [prompt](/docs/guides/speech-to-text/prompting) + audio segment. The [prompt](/docs/guides/speech-to-text#prompting) should match the audio language. type: string response_format: @@ -14655,7 +16517,7 @@ components: prompt: description: > An optional text to guide the model's style or continue a previous - audio segment. The [prompt](/docs/guides/speech-to-text/prompting) + audio segment. The [prompt](/docs/guides/speech-to-text#prompting) should be in English. type: string response_format: @@ -15002,10 +16864,10 @@ components: required: - event - data - description: Occurs when an [error](/docs/guides/error-codes/api-errors) occurs. + description: Occurs when an [error](/docs/guides/error-codes#api-errors) occurs. This can happen due to an internal server error or a timeout. x-oaiMeta: - dataDescription: "`data` is an [error](/docs/guides/error-codes/api-errors)" + dataDescription: "`data` is an [error](/docs/guides/error-codes#api-errors)" ErrorResponse: type: object properties: @@ -15016,45 +16878,320 @@ components: FileSearchRankingOptions: title: File search tool call ranking options type: object - description: > - The ranking options for the file search. If not specified, the file - search tool will use the `auto` ranker and a score_threshold of 0. - - - See the [file search tool - documentation](/docs/assistants/tools/file-search/customizing-file-search-settings) - for more information. + description: > + The ranking options for the file search. If not specified, the file + search tool will use the `auto` ranker and a score_threshold of 0. + + + See the [file search tool + documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) + for more information. + properties: + ranker: + type: string + description: The ranker to use for the file search. If not specified will use + the `auto` ranker. + enum: + - auto + - default_2024_08_21 + score_threshold: + type: number + description: The score threshold for the file search. All values must be a + floating point number between 0 and 1. + minimum: 0 + maximum: 1 + required: + - score_threshold + FineTuneChatCompletionRequestAssistantMessage: + allOf: + - type: object + title: Assistant message + deprecated: false + properties: + weight: + type: integer + enum: + - 0 + - 1 + description: Controls whether the assistant message is trained against (0 or 1) + - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" + required: + - role + FineTuneChatRequestInput: + type: object + description: The per-line training example of a fine-tuning input file for chat + models using the supervised method. + properties: + messages: + type: array + minItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" + - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" + - $ref: "#/components/schemas/FineTuneChatCompletionRequestAssistantMessage" + - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" + - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" + x-oaiExpandable: true + tools: + type: array + description: A list of tools the model may generate JSON inputs for. + items: + $ref: "#/components/schemas/ChatCompletionTool" + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + functions: + deprecated: true + description: A list of functions the model may generate JSON inputs for. + type: array + minItems: 1 + maxItems: 128 + items: + $ref: "#/components/schemas/ChatCompletionFunctions" + x-oaiMeta: + name: Training format for chat models using the supervised method + example: > + { + "messages": [ + { "role": "user", "content": "What is the weather in San Francisco?" }, + { + "role": "assistant", + "tool_calls": [ + { + "id": "call_id", + "type": "function", + "function": { + "name": "get_current_weather", + "arguments": "{\"location\": \"San Francisco, USA\", \"format\": \"celsius\"}" + } + } + ] + } + ], + "parallel_tool_calls": false, + "tools": [ + { + "type": "function", + "function": { + "name": "get_current_weather", + "description": "Get the current weather", + "parameters": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "The city and country, eg. San Francisco, USA" + }, + "format": { "type": "string", "enum": ["celsius", "fahrenheit"] } + }, + "required": ["location", "format"] + } + } + } + ] + } + FineTuneCompletionRequestInput: + type: object + description: The per-line training example of a fine-tuning input file for + completions models + properties: + prompt: + type: string + description: The input prompt for this training example. + completion: + type: string + description: The desired completion for this training example. + x-oaiMeta: + name: Training format for completions models + example: | + { + "prompt": "What is the answer to 2+2", + "completion": "4" + } + FineTuneDPOMethod: + type: object + description: Configuration for the DPO fine-tuning method. + properties: + hyperparameters: + type: object + description: The hyperparameters used for the fine-tuning job. + properties: + beta: + description: > + The beta value for the DPO method. A higher beta value will + increase the weight of the penalty between the policy and + reference model. + oneOf: + - type: string + enum: + - auto + - type: number + minimum: 0 + maximum: 2 + exclusiveMinimum: true + default: auto + batch_size: + description: > + Number of examples in each batch. A larger batch size means that + model parameters are updated less frequently, but with lower + variance. + oneOf: + - type: string + enum: + - auto + - type: integer + minimum: 1 + maximum: 256 + default: auto + learning_rate_multiplier: + description: > + Scaling factor for the learning rate. A smaller learning rate + may be useful to avoid overfitting. + oneOf: + - type: string + enum: + - auto + - type: number + minimum: 0 + exclusiveMinimum: true + default: auto + n_epochs: + description: > + The number of epochs to train the model for. An epoch refers to + one full cycle through the training dataset. + oneOf: + - type: string + enum: + - auto + - type: integer + minimum: 1 + maximum: 50 + default: auto + FineTuneMethod: + type: object + description: The method used for fine-tuning. + properties: + type: + type: string + description: The type of method. Is either `supervised` or `dpo`. + enum: + - supervised + - dpo + supervised: + type: object + $ref: "#/components/schemas/FineTuneSupervisedMethod" + dpo: + type: object + $ref: "#/components/schemas/FineTuneDPOMethod" + FineTunePreferenceRequestInput: + type: object + description: The per-line training example of a fine-tuning input file for chat + models using the dpo method. + properties: + input: + type: object + properties: + messages: + type: array + minItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" + - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" + - $ref: "#/components/schemas/FineTuneChatCompletionRequestAssistantMessage" + - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" + - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" + x-oaiExpandable: true + tools: + type: array + description: A list of tools the model may generate JSON inputs for. + items: + $ref: "#/components/schemas/ChatCompletionTool" + parallel_tool_calls: + $ref: "#/components/schemas/ParallelToolCalls" + preferred_completion: + type: array + description: The preferred completion message for the output. + maxItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" + x-oaiExpandable: true + non_preferred_completion: + type: array + description: The non-preferred completion message for the output. + maxItems: 1 + items: + oneOf: + - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" + x-oaiExpandable: true + x-oaiMeta: + name: Training format for chat models using the preference method + example: > + { + "input": { + "messages": [ + { "role": "user", "content": "What is the weather in San Francisco?" } + ] + }, + "preferred_completion": [ + { + "role": "assistant", + "content": "The weather in San Francisco is 70 degrees Fahrenheit." + } + ], + "non_preferred_completion": [ + { + "role": "assistant", + "content": "The weather in San Francisco is 21 degrees Celsius." + } + ] + } + FineTuneSupervisedMethod: + type: object + description: Configuration for the supervised fine-tuning method. properties: - ranker: - type: string - description: The ranker to use for the file search. If not specified will use - the `auto` ranker. - enum: - - auto - - default_2024_08_21 - score_threshold: - type: number - description: The score threshold for the file search. All values must be a - floating point number between 0 and 1. - minimum: 0 - maximum: 1 - required: - - score_threshold - FineTuneChatCompletionRequestAssistantMessage: - allOf: - - type: object - title: Assistant message - deprecated: false + hyperparameters: + type: object + description: The hyperparameters used for the fine-tuning job. properties: - weight: - type: integer - enum: - - 0 - - 1 - description: Controls whether the assistant message is trained against (0 or 1) - - $ref: "#/components/schemas/ChatCompletionRequestAssistantMessage" - required: - - role + batch_size: + description: > + Number of examples in each batch. A larger batch size means that + model parameters are updated less frequently, but with lower + variance. + oneOf: + - type: string + enum: + - auto + - type: integer + minimum: 1 + maximum: 256 + default: auto + learning_rate_multiplier: + description: > + Scaling factor for the learning rate. A smaller learning rate + may be useful to avoid overfitting. + oneOf: + - type: string + enum: + - auto + - type: number + minimum: 0 + exclusiveMinimum: true + default: auto + n_epochs: + description: > + The number of epochs to train the model for. An epoch refers to + one full cycle through the training dataset. + oneOf: + - type: string + enum: + - auto + - type: integer + minimum: 1 + maximum: 50 + default: auto FineTuningIntegration: type: object title: Fine-Tuning Job Integration @@ -15161,27 +17298,51 @@ components: running. hyperparameters: type: object - description: The hyperparameters used for the fine-tuning job. See the - [fine-tuning guide](/docs/guides/fine-tuning) for more details. + description: The hyperparameters used for the fine-tuning job. This value will + only be returned when running `supervised` jobs. properties: - n_epochs: + batch_size: + description: > + Number of examples in each batch. A larger batch size means that + model parameters + + are updated less frequently, but with lower variance. oneOf: - type: string enum: - auto - type: integer minimum: 1 - maximum: 50 + maximum: 256 + default: auto + learning_rate_multiplier: + description: > + Scaling factor for the learning rate. A smaller learning rate + may be useful to avoid + + overfitting. + oneOf: + - type: string + enum: + - auto + - type: number + minimum: 0 + exclusiveMinimum: true default: auto - description: >- + n_epochs: + description: > The number of epochs to train the model for. An epoch refers to - one full cycle through the training dataset. + one full cycle - "auto" decides the optimal number of epochs based on the size of - the dataset. If setting the number manually, we support any - number between 1 and 50 epochs. - required: - - n_epochs + through the training dataset. + oneOf: + - type: string + enum: + - auto + - type: integer + minimum: 1 + maximum: 50 + default: auto model: type: string description: The base model that is being fine-tuned. @@ -15246,6 +17407,8 @@ components: description: The Unix timestamp (in seconds) for when the fine-tuning job is estimated to finish. The value will be null if the fine-tuning job is not running. + method: + $ref: "#/components/schemas/FineTuneMethod" required: - created_at - error @@ -15287,7 +17450,17 @@ components: "trained_tokens": 5768, "integrations": [], "seed": 0, - "estimated_finish": 0 + "estimated_finish": 0, + "method": { + "type": "supervised", + "supervised": { + "hyperparameters": { + "n_epochs": 4, + "batch_size": 1, + "learning_rate_multiplier": 1.0 + } + } + } } FineTuningJobCheckpoint: type: object @@ -15368,22 +17541,37 @@ components: type: object description: Fine-tuning job event object properties: + object: + type: string + description: The object type, which is always "fine_tuning.job.event". + enum: + - fine_tuning.job.event id: type: string + description: The object identifier. created_at: type: integer + description: The Unix timestamp (in seconds) for when the fine-tuning job was + created. level: type: string + description: The log level of the event. enum: - info - warn - error message: type: string - object: + description: The message of the event. + type: type: string + description: The type of event. enum: - - fine_tuning.job.event + - message + - metrics + data: + type: object + description: The data associated with the event. required: - id - object @@ -15398,97 +17586,9 @@ components: "id": "ftevent-abc123" "created_at": 1677610602, "level": "info", - "message": "Created fine-tuning job" - } - FinetuneChatRequestInput: - type: object - description: The per-line training example of a fine-tuning input file for chat models - properties: - messages: - type: array - minItems: 1 - items: - oneOf: - - $ref: "#/components/schemas/ChatCompletionRequestSystemMessage" - - $ref: "#/components/schemas/ChatCompletionRequestUserMessage" - - $ref: "#/components/schemas/FineTuneChatCompletionRequestAssistantMessage" - - $ref: "#/components/schemas/ChatCompletionRequestToolMessage" - - $ref: "#/components/schemas/ChatCompletionRequestFunctionMessage" - x-oaiExpandable: true - tools: - type: array - description: A list of tools the model may generate JSON inputs for. - items: - $ref: "#/components/schemas/ChatCompletionTool" - parallel_tool_calls: - $ref: "#/components/schemas/ParallelToolCalls" - functions: - deprecated: true - description: A list of functions the model may generate JSON inputs for. - type: array - minItems: 1 - maxItems: 128 - items: - $ref: "#/components/schemas/ChatCompletionFunctions" - x-oaiMeta: - name: Training format for chat models - example: > - { - "messages": [ - { "role": "user", "content": "What is the weather in San Francisco?" }, - { - "role": "assistant", - "tool_calls": [ - { - "id": "call_id", - "type": "function", - "function": { - "name": "get_current_weather", - "arguments": "{\"location\": \"San Francisco, USA\", \"format\": \"celsius\"}" - } - } - ] - } - ], - "parallel_tool_calls": false, - "tools": [ - { - "type": "function", - "function": { - "name": "get_current_weather", - "description": "Get the current weather", - "parameters": { - "type": "object", - "properties": { - "location": { - "type": "string", - "description": "The city and country, eg. San Francisco, USA" - }, - "format": { "type": "string", "enum": ["celsius", "fahrenheit"] } - }, - "required": ["location", "format"] - } - } - } - ] - } - FinetuneCompletionRequestInput: - type: object - description: The per-line training example of a fine-tuning input file for - completions models - properties: - prompt: - type: string - description: The input prompt for this training example. - completion: - type: string - description: The desired completion for this training example. - x-oaiMeta: - name: Training format for completions models - example: | - { - "prompt": "What is the answer to 2+2", - "completion": "4" + "message": "Created fine-tuning job", + "data": {}, + "type": "message" } FunctionObject: type: object @@ -15809,17 +17909,28 @@ components: ListFilesResponse: type: object properties: + object: + type: string + example: list data: type: array items: $ref: "#/components/schemas/OpenAIFile" - object: + first_id: type: string - enum: - - list + example: file-abc123 + last_id: + type: string + example: file-abc456 + has_more: + type: boolean + example: false required: - object - data + - first_id + - last_id + - has_more ListFineTuningJobCheckpointsResponse: type: object properties: @@ -16725,7 +18836,7 @@ components: name: The model object example: | { - "id": "VAR_model_id", + "id": "VAR_chat_model_id", "object": "model", "created": 1686935002, "owned_by": "openai" @@ -16738,8 +18849,8 @@ components: description: > ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your - available models, or see our [Model overview](/docs/models/overview) - for descriptions of them. + available models, or see our [Model overview](/docs/models) for + descriptions of them. anyOf: - type: string name: @@ -17006,10 +19117,52 @@ components: - type ParallelToolCalls: description: Whether to enable [parallel function - calling](/docs/guides/function-calling/parallel-function-calling) during - tool use. + calling](/docs/guides/function-calling#configuring-parallel-function-calling) + during tool use. type: boolean default: true + PredictionContent: + type: object + title: Static Content + description: > + Static predicted output content, such as the content of a text file that + is + + being regenerated. + required: + - type + - content + properties: + type: + type: string + enum: + - content + description: | + The type of the predicted content you want to provide. This type is + currently always `content`. + content: + x-oaiExpandable: true + description: > + The content that should be matched when generating a model response. + + If generated tokens would match this content, the entire model + response + + can be returned much more quickly. + oneOf: + - type: string + title: Text content + description: | + The content used for a Predicted Output. This is often the + text of a file you are regenerating with minor changes. + - type: array + description: An array of content parts with a defined type. Supported options + differ based on the [model](/docs/models) being used to generate + the response. Can contain text inputs. + title: Array of content parts + items: + $ref: "#/components/schemas/ChatCompletionRequestMessageContentPartText" + minItems: 1 Project: type: object description: Represents an individual project. @@ -17187,6 +19340,104 @@ components: - first_id - last_id - has_more + ProjectRateLimit: + type: object + description: Represents a project rate limit config. + properties: + object: + type: string + enum: + - project.rate_limit + description: The object type, which is always `project.rate_limit` + id: + type: string + description: The identifier, which can be referenced in API endpoints. + model: + type: string + description: The model this rate limit applies to. + max_requests_per_1_minute: + type: integer + description: The maximum requests per minute. + max_tokens_per_1_minute: + type: integer + description: The maximum tokens per minute. + max_images_per_1_minute: + type: integer + description: The maximum images per minute. Only present for relevant models. + max_audio_megabytes_per_1_minute: + type: integer + description: The maximum audio megabytes per minute. Only present for relevant + models. + max_requests_per_1_day: + type: integer + description: The maximum requests per day. Only present for relevant models. + batch_1_day_max_input_tokens: + type: integer + description: The maximum batch input tokens per day. Only present for relevant + models. + required: + - object + - id + - model + - max_requests_per_1_minute + - max_tokens_per_1_minute + x-oaiMeta: + name: The project rate limit object + example: | + { + "object": "project.rate_limit", + "id": "rl_ada", + "model": "ada", + "max_requests_per_1_minute": 600, + "max_tokens_per_1_minute": 150000, + "max_images_per_1_minute": 10 + } + ProjectRateLimitListResponse: + type: object + properties: + object: + type: string + enum: + - list + data: + type: array + items: + $ref: "#/components/schemas/ProjectRateLimit" + first_id: + type: string + last_id: + type: string + has_more: + type: boolean + required: + - object + - data + - first_id + - last_id + - has_more + ProjectRateLimitUpdateRequest: + type: object + properties: + max_requests_per_1_minute: + type: integer + description: The maximum requests per minute. + max_tokens_per_1_minute: + type: integer + description: The maximum tokens per minute. + max_images_per_1_minute: + type: integer + description: The maximum images per minute. Only relevant for certain models. + max_audio_megabytes_per_1_minute: + type: integer + description: The maximum audio megabytes per minute. Only relevant for certain + models. + max_requests_per_1_day: + type: integer + description: The maximum requests per day. Only relevant for certain models. + batch_1_day_max_input_tokens: + type: integer + description: The maximum batch input tokens per day. Only relevant for certain + models. ProjectServiceAccount: type: object description: Represents an individual service account in a project. @@ -17442,65 +19693,48 @@ components: - role RealtimeClientEventConversationItemCreate: type: object - description: Send this event when adding an item to the conversation. + 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. + + + If successful, the server will respond with a + `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 - description: The event type, must be "conversation.item.create". + 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. + 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: - type: object - description: The item to add to the conversation. - properties: - id: - type: string - description: The unique ID of the item. - type: - type: string - description: The type of the item ("message", "function_call", - "function_call_output"). - status: - type: string - description: The status of the item ("completed", "in_progress", "incomplete"). - role: - type: string - description: The role of the message sender ("user", "assistant", "system"). - content: - type: array - description: The content of the message. - items: - type: object - properties: - type: - type: string - description: The content type ("input_text", "input_audio", "text", "audio"). - text: - type: string - description: The text content. - audio: - type: string - description: Base64-encoded audio bytes. - transcript: - type: string - description: The transcript of the audio. - call_id: - type: string - description: The ID of the function call (for "function_call" items). - name: - type: string - 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). - output: - type: string - description: The output of the function call (for "function_call_output" items). + $ref: "#/components/schemas/RealtimeConversationItem" required: - type - item @@ -17515,7 +19749,6 @@ components: "item": { "id": "msg_001", "type": "message", - "status": "completed", "role": "user", "content": [ { @@ -17527,15 +19760,25 @@ components: } RealtimeClientEventConversationItemDelete: type: object - description: Send this event when you want to remove any item from the - conversation history. + 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. @@ -17553,24 +19796,61 @@ components: } RealtimeClientEventConversationItemTruncate: type: object - description: Send this event when you want to truncate a previous assistant - message’s audio. + 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. + + + 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. + + + If successful, the server will respond with a + `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. + 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. + 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. + 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 @@ -17589,17 +19869,48 @@ components: } RealtimeClientEventInputAudioBufferAppend: type: object - description: Send this event to append audio bytes to the input audio buffer. + 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. + + + 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. 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. + 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 @@ -17614,14 +19925,18 @@ components: } RealtimeClientEventInputAudioBufferClear: type: object - description: Send this event to clear the audio bytes in the buffer. + 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: @@ -17634,14 +19949,40 @@ components: } RealtimeClientEventInputAudioBufferCommit: type: object - description: Send this event to commit audio bytes to a user message. + 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. + + + 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. 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: @@ -17654,14 +19995,28 @@ components: } RealtimeClientEventResponseCancel: type: object - description: Send this event to cancel an in-progress response. + 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 - description: The event type, must be "response.cancel". + enum: + - response.cancel + description: The event type, must be `response.cancel`. + response_id: + type: string + description: | + A specific response ID to cancel - if not provided, will cancel an + in-progress response in the default conversation. required: - type x-oaiMeta: @@ -17674,252 +20029,624 @@ components: } RealtimeClientEventResponseCreate: type: object - description: Send this event to trigger a response generation. + 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. + + + 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. + + + 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. + + + The `response.create` event includes inference configuration like + + `instructions`, and `temperature`. These fields will override the + 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 - description: The event type, must be "response.create". + enum: + - response.create + description: The event type, must be `response.create`. response: - type: object - description: Configuration for the response. - properties: - modalities: - type: array - items: - type: string - description: The modalities for the response. - instructions: - type: string - description: Instructions for the model. - voice: - type: string - description: The voice the model uses to respond - one of `alloy`, `echo`, or - `shimmer`. - output_audio_format: - type: string - description: The format of output audio. - tools: - type: array - description: Tools (functions) available to the model. - items: - type: object - properties: - type: - type: string - description: The type of the tool. - name: - type: string - description: The name of the function. - description: - type: string - description: The description of the function. - parameters: - type: object - description: Parameters of the function in JSON Schema. - tool_choice: - type: string - description: How the model chooses tools. - temperature: - type: number - description: Sampling temperature. - max_output_tokens: - oneOf: - - type: integer - - type: string - enum: - - inf - description: Maximum number of output tokens for a single assistant response, - inclusive of tool calls. Provide an integer between 1 and 4096 - to limit output tokens, or "inf" for the maximum available - tokens for a given model. Defaults to "inf". + $ref: "#/components/schemas/RealtimeResponseCreateParams" + required: + - type + x-oaiMeta: + name: response.create + group: realtime + example: | + { + "event_id": "event_234", + "type": "response.create", + "response": { + "modalities": ["text", "audio"], + "instructions": "Please assist the user.", + "voice": "sage", + "output_audio_format": "pcm16", + "tools": [ + { + "type": "function", + "name": "calculate_sum", + "description": "Calculates the sum of two numbers.", + "parameters": { + "type": "object", + "properties": { + "a": { "type": "number" }, + "b": { "type": "number" } + }, + "required": ["a", "b"] + } + } + ], + "tool_choice": "auto", + "temperature": 0.8, + "max_output_tokens": 1024 + } + } + 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. + properties: + event_id: + type: string + description: Optional client-generated ID used to identify this event. + type: + type: string + enum: + - session.update + description: The event type, must be `session.update`. + session: + $ref: "#/components/schemas/RealtimeSessionCreateRequest" required: - type - - response + - session x-oaiMeta: - name: response.create + name: session.update group: realtime example: | { - "event_id": "event_234", - "type": "response.create", - "response": { + "event_id": "event_123", + "type": "session.update", + "session": { "modalities": ["text", "audio"], - "instructions": "Please assist the user.", - "voice": "alloy", + "instructions": "You are a helpful assistant.", + "voice": "sage", + "input_audio_format": "pcm16", "output_audio_format": "pcm16", + "input_audio_transcription": { + "model": "whisper-1" + }, + "turn_detection": { + "type": "server_vad", + "threshold": 0.5, + "prefix_padding_ms": 300, + "silence_duration_ms": 500, + "create_response": true + }, "tools": [ { "type": "function", - "name": "calculate_sum", - "description": "Calculates the sum of two numbers.", + "name": "get_weather", + "description": "Get the current weather...", "parameters": { "type": "object", "properties": { - "a": { "type": "number" }, - "b": { "type": "number" } + "location": { "type": "string" } }, - "required": ["a", "b"] + "required": ["location"] } } ], "tool_choice": "auto", - "temperature": 0.7, - "max_output_tokens": 150 + "temperature": 0.8, + "max_response_output_tokens": "inf" } } - RealtimeClientEventSessionUpdate: + RealtimeConversationItem: type: object - description: Send this event to update the session’s default configuration. + x-oaiExpandable: true + description: The item to add to the conversation. properties: - event_id: + id: type: string - description: Optional client-generated ID used to identify this event. + 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 event type, must be "session.update". - session: + 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 + 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 + enum: + - user + - assistant + - system + description: > + The role of the message sender (`user`, `assistant`, `system`), + only + + applicable for `message` items. + content: + type: array + 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 + - item_reference + - text + description: > + The content type (`input_text`, `input_audio`, + `item_reference`, `text`). + text: + type: string + description: > + The text content, used for `input_text` and `text` content + types. + id: + type: string + description: > + ID of a previous conversation item to reference (for + `item_reference` + + content types in `response.create` events). These can + reference both + + client and server created items. + audio: + type: string + 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. + 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` + + item, the server will check that a `function_call` item with the + same + + ID exists in the conversation history. + name: + type: string + 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). + output: + type: string + description: | + The output of the function call (for `function_call_output` items). + RealtimeResponse: + type: object + description: The response resource. + properties: + id: + type: string + description: The unique ID of the response. + object: + type: string + enum: + - realtime.response + description: The object type, must be `realtime.response`. + status: + type: string + 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 + enum: + - completed + - cancelled + - failed + - incomplete + description: > + The type of error that caused the response to fail, + corresponding + + with the `status` field (`completed`, `cancelled`, + `incomplete`, + + `failed`). + reason: + type: string + 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, + populated when the `status` is `failed`. + properties: + type: + type: string + description: The type of error. + code: + type: string + description: Error code, if any. + output: + type: array + description: The list of output items generated by the response. + items: + $ref: "#/components/schemas/RealtimeConversationItem" + metadata: + description: > + Developer-provided string key-value pairs associated with this + response. + type: object + x-oaiTypeLabel: map + nullable: true + 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. + properties: + total_tokens: + type: integer + 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 + + audio tokens. + output_tokens: + type: integer + 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. + properties: + cached_tokens: + type: integer + description: The number of cached tokens used in the Response. + text_tokens: + type: integer + description: The number of text tokens used in the Response. + audio_tokens: + type: integer + description: The number of audio tokens used in the Response. + output_token_details: + type: object + description: Details about the output tokens used in the Response. + properties: + text_tokens: + type: integer + description: The number of text tokens used in the Response. + audio_tokens: + type: integer + description: The number of audio tokens used in the Response. + RealtimeResponseCreateParams: + type: object + description: Create a new Realtime response with these parameters + properties: + modalities: + type: array + 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: > + The default system instructions (i.e. system message) prepended to + model + + calls. This field allows the client to guide the model on desired + + responses. The model can be instructed on response content and + format, + + (e.g. "be extremely succinct", "act friendly", "here are examples of + good + + responses") and on audio behavior (e.g. "talk quickly", "inject + emotion + + into your voice", "laugh frequently"). The instructions are not + guaranteed + + to be followed by the model, but they provide guidance to the model + on the + + desired behavior. + + + Note that the server sets default instructions which will be used if + this + + field is not set and are visible in the `session.created` event at + the + + start of the session. + voice: + type: string + enum: + - alloy + - ash + - ballad + - coral + - echo + - sage + - shimmer + - verse + description: > + The voice the model uses to respond. Voice cannot be changed during + the + + session once the model has responded with audio at least once. + Current + + voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, + + `shimmer` and `verse`. + output_audio_format: + type: string + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + tools: + type: array + description: Tools (functions) available to the model. + items: + type: object + properties: + type: + type: string + enum: + - function + description: The type of the tool, i.e. `function`. + name: + type: string + description: The name of the function. + description: + type: string + description: > + The description of the function, including guidance on when + and how + + to call it, and guidance about what to tell the user when + calling + + (if anything). + parameters: + type: object + description: Parameters of the function in JSON Schema. + tool_choice: + type: string + description: > + How the model chooses tools. Options are `auto`, `none`, `required`, + or + + specify a function, like `{"type": "function", "function": {"name": + "my_function"}}`. + temperature: + type: number + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. Defaults + to 0.8. + max_response_output_tokens: + oneOf: + - type: integer + - type: string + enum: + - inf + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls. Provide an integer between 1 and 4096 to + limit output tokens, or `inf` for the maximum available tokens for a + given model. Defaults to `inf`. + conversation: + description: > + Controls which conversation the response is added to. Currently + supports + + `auto` and `none`, with `auto` as the default value. The `auto` + value + + means that the contents of the response will be added to the default + + conversation. Set this to `none` to create an out-of-band response + which + + will not add items to default conversation. + oneOf: + - type: string + - type: string + default: auto + enum: + - auto + - none + metadata: + description: > + Set of 16 key-value pairs that can be attached to an object. This + can be + + useful for storing additional information about the object in a + structured + + format. Keys can be a maximum of 64 characters long and values can + be a + + maximum of 512 characters long. type: object - description: Session configuration to update. - properties: - modalities: - type: array - items: - type: string - description: The set of modalities the model can respond with. To disable audio, - set this to ["text"]. - instructions: - type: string - description: The default system instructions prepended to model calls. - voice: - type: string - description: The voice the model uses to respond - one of `alloy`, `echo`, - or `shimmer`. Cannot be changed once the model has responded - with audio at least once. - input_audio_format: - type: string - description: The format of input audio. Options are "pcm16", "g711_ulaw", or - "g711_alaw". - output_audio_format: - type: string - description: The format of output audio. Options are "pcm16", "g711_ulaw", or - "g711_alaw". - input_audio_transcription: - type: object - description: Configuration for input audio transcription. Can be set to `null` - to turn off. - properties: - model: - type: string - description: The model to use for transcription (e.g., "whisper-1"). - turn_detection: - type: object - description: Configuration for turn detection. Can be set to `null` to turn off. - properties: - type: - type: string - description: Type of turn detection, only "server_vad" is currently supported. - threshold: - type: number - description: Activation threshold for VAD (0.0 to 1.0). - prefix_padding_ms: - type: integer - description: Amount of audio to include before speech starts (in milliseconds). - silence_duration_ms: - type: integer - description: Duration of silence to detect speech stop (in milliseconds). - tools: - type: array - description: Tools (functions) available to the model. - items: - type: object - properties: - type: - type: string - description: The type of the tool, e.g., "function". - name: - type: string - description: The name of the function. - description: - type: string - description: The description of the function. - parameters: - type: object - description: Parameters of the function in JSON Schema. - tool_choice: - type: string - description: How the model chooses tools. Options are "auto", "none", - "required", or specify a function. - temperature: - type: number - description: Sampling temperature for the model. - max_output_tokens: - oneOf: - - type: integer - - type: string - enum: - - inf - description: Maximum number of output tokens for a single assistant response, - inclusive of tool calls. Provide an integer between 1 and 4096 - to limit output tokens, or "inf" for the maximum available - tokens for a given model. Defaults to "inf". - required: - - type - - session - x-oaiMeta: - name: session.update - group: realtime - 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", - "input_audio_format": "pcm16", - "output_audio_format": "pcm16", - "input_audio_transcription": { - "model": "whisper-1" - }, - "turn_detection": { - "type": "server_vad", - "threshold": 0.5, - "prefix_padding_ms": 300, - "silence_duration_ms": 200 - }, - "tools": [ - { - "type": "function", - "name": "get_weather", - "description": "Get the current weather for a location.", - "parameters": { - "type": "object", - "properties": { - "location": { "type": "string" } - }, - "required": ["location"] - } - } - ], - "tool_choice": "auto", - "temperature": 0.8, - "max_output_tokens": null - } - } + x-oaiTypeLabel: map + nullable: true + input: + type: array + description: > + Input items to include in the prompt for the model. Creates a new + context + + for this response, without including the default conversation. Can + include + + references to items from the default conversation. + items: + $ref: "#/components/schemas/RealtimeConversationItem" 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. @@ -17929,7 +20656,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 @@ -17948,67 +20675,37 @@ components: } RealtimeServerEventConversationItemCreated: type: object - description: Returned when a conversation item is created. + 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. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "conversation.item.created". + 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. + description: > + The ID of the preceding item in the Conversation context, allows + the + + client to understand the order of the conversation. item: - type: object - description: The item that was created. - properties: - id: - type: string - description: The unique ID of the item. - object: - type: string - description: The object type, must be "realtime.item". - type: - type: string - description: The type of the item ("message", "function_call", - "function_call_output"). - status: - type: string - description: The status of the item ("completed", "in_progress", "incomplete"). - role: - type: string - description: The role associated with the item ("user", "assistant", "system"). - content: - type: array - description: The content of the item. - items: - type: object - properties: - type: - type: string - description: The content type ("text", "audio", "input_text", "input_audio"). - text: - type: string - description: The text content. - audio: - type: string - description: Base64-encoded audio data. - transcript: - type: string - description: The transcript of the audio. - call_id: - type: string - description: The ID of the function call (for "function_call" items). - name: - type: string - description: The name of the function being called. - arguments: - type: string - description: The arguments of the function call. - output: - type: string - description: The output of the function call (for "function_call_output" items). + $ref: "#/components/schemas/RealtimeConversationItem" required: - event_id - type @@ -18031,21 +20728,31 @@ components: "content": [ { "type": "input_audio", - "transcript": null + "transcript": "hello how are you", + "audio": "base64encodedaudio==" } ] } } RealtimeServerEventConversationItemDeleted: type: object - description: Returned when an item in the conversation is deleted. + 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 - description: The event type, must be "conversation.item.deleted". + enum: + - conversation.item.deleted + description: The event type, must be `conversation.item.deleted`. item_id: type: string description: The ID of the item that was deleted. @@ -18064,19 +20771,45 @@ components: } RealtimeServerEventConversationItemInputAudioTranscriptionCompleted: type: object - description: Returned when input audio transcription is enabled and a - transcription succeeds. + 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. + + + 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. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be - "conversation.item.input_audio_transcription.completed". + enum: + - conversation.item.input_audio_transcription.completed + description: | + The event type, must be + `conversation.item.input_audio_transcription.completed`. item_id: type: string - description: The ID of the user message item. + description: The ID of the user message item containing the audio. content_index: type: integer description: The index of the content part containing the audio. @@ -18102,16 +20835,24 @@ components: } RealtimeServerEventConversationItemInputAudioTranscriptionFailed: type: object - description: Returned when input audio transcription is configured, and a - transcription request for a user message failed. + 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 - "conversation.item.input_audio_transcription.failed". + enum: + - conversation.item.input_audio_transcription.failed + description: | + The event type, must be + `conversation.item.input_audio_transcription.failed`. item_id: type: string description: The ID of the user message item. @@ -18158,15 +20899,30 @@ components: } RealtimeServerEventConversationItemTruncated: type: object - description: Returned when an earlier assistant audio message item is truncated - by the client. + 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 + 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. properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "conversation.item.truncated". + enum: + - conversation.item.truncated + description: The event type, must be `conversation.item.truncated`. item_id: type: string description: The ID of the assistant message item that was truncated. @@ -18175,7 +20931,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 @@ -18195,34 +20952,51 @@ components: } RealtimeServerEventError: type: object - description: Returned when an error occurs. + 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. + required: + - type + - message 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. + nullable: true message: type: string description: A human-readable error message. param: type: string description: Parameter related to the error, if any. + nullable: true 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. + nullable: true required: - event_id - type @@ -18244,14 +21018,18 @@ components: } RealtimeServerEventInputAudioBufferCleared: type: object - description: Returned when the input audio buffer is cleared by the client. + 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 - description: The event type, must be "input_audio_buffer.cleared". + enum: + - input_audio_buffer.cleared + description: The event type, must be `input_audio_buffer.cleared`. required: - event_id - type @@ -18265,18 +21043,30 @@ components: } RealtimeServerEventInputAudioBufferCommitted: type: object - description: Returned when an input audio buffer is committed, either by the - client or automatically in server VAD mode. + 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 - description: The event type, must be "input_audio_buffer.committed". + 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 @@ -18298,20 +21088,56 @@ components: } RealtimeServerEventInputAudioBufferSpeechStarted: type: object - description: Returned in server turn detection mode when speech is detected. + 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). properties: event_id: type: string description: The unique ID of the server event. type: type: string - description: The event type, must be "input_audio_buffer.speech_started". + enum: + - input_audio_buffer.speech_started + description: The event type, must be `input_audio_buffer.speech_started`. audio_start_ms: type: integer - description: Milliseconds since the session started when speech was detected. + 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 @@ -18330,17 +21156,33 @@ components: } RealtimeServerEventInputAudioBufferSpeechStopped: type: object - description: Returned in server turn detection mode when speech stops. + 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 - description: The event type, must be "input_audio_buffer.speech_stopped". + 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. + 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. @@ -18361,15 +21203,26 @@ components: } RealtimeServerEventRateLimitsUpdated: type: object - description: Emitted after every "response.done" event to indicate the updated - rate limits. + 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 - description: The event type, must be "rate_limits.updated". + enum: + - rate_limits.updated + description: The event type, must be `rate_limits.updated`. rate_limits: type: array description: List of rate limit information. @@ -18378,8 +21231,11 @@ components: properties: name: type: string - description: The name of the rate limit ("requests", "tokens", "input_tokens", - "output_tokens"). + enum: + - requests + - tokens + description: | + The name of the rate limit (`requests`, `tokens`). limit: type: integer description: The maximum allowed value for the rate limit. @@ -18424,7 +21280,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. @@ -18463,15 +21321,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. @@ -18505,7 +21368,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: @@ -18513,7 +21377,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. @@ -18552,16 +21418,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. @@ -18600,15 +21469,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. @@ -18627,6 +21501,9 @@ components: properties: type: type: string + enum: + - audio + - text description: The content type ("text", "audio"). text: type: string @@ -18663,16 +21540,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. @@ -18691,6 +21572,9 @@ components: properties: type: type: string + enum: + - audio + - text description: The content type ("text", "audio"). text: type: string @@ -18727,41 +21611,22 @@ 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 - description: The event type, must be "response.created". + enum: + - response.created + description: The event type, must be `response.created`. response: - type: object - description: The response resource. - properties: - id: - type: string - description: The unique ID of the response. - object: - type: string - description: The object type, must be "realtime.response". - status: - type: string - description: The status of the response ("in_progress"). - status_details: - type: object - description: Additional details about the status. - output: - type: array - description: The list of output items generated by the response. - items: - type: object - description: An item in the response output. - usage: - type: object - description: Usage statistics for the response. + $ref: "#/components/schemas/RealtimeResponse" required: - event_id - type @@ -18784,41 +21649,26 @@ components: } RealtimeServerEventResponseDone: type: object - description: Returned when a Response is done streaming. Always emitted, no - matter the final state. - properties: - event_id: - type: string - description: The unique ID of the server event. - type: - type: string - description: The event type, must be "response.done". - response: - type: object - description: The response resource. - properties: - id: - type: string - description: The unique ID of the response. - object: - type: string - description: The object type, must be "realtime.response". - status: - type: string - description: The final status of the response ("completed", "cancelled", - "failed", "incomplete"). - status_details: - type: object - description: Additional details about the status. - output: - type: array - description: The list of output items generated by the response. - items: - type: object - description: An item in the response output. - usage: - type: object - description: Usage statistics for the response. + 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 + enum: + - response.done + description: The event type, must be `response.done`. + response: + $ref: "#/components/schemas/RealtimeResponse" required: - event_id - type @@ -18851,22 +21701,39 @@ components: } ], "usage": { - "total_tokens": 50, - "input_tokens": 20, - "output_tokens": 30 + "total_tokens":275, + "input_tokens":127, + "output_tokens":148, + "input_token_details": { + "cached_tokens":384, + "text_tokens":119, + "audio_tokens":8, + "cached_tokens_details": { + "text_tokens": 128, + "audio_tokens": 256 + } + }, + "output_token_details": { + "text_tokens":36, + "audio_tokens":112 + } } } } 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. @@ -18905,16 +21772,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. @@ -18953,58 +21825,24 @@ components: } RealtimeServerEventResponseOutputItemAdded: type: object - description: Returned when a new Item is created during response generation. + description: Returned when a new Item is created 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.output_item.added". + enum: + - response.output_item.added + description: The event type, must be `response.output_item.added`. response_id: type: string - description: The ID of the response to which the item belongs. + description: The ID of the Response to which the item belongs. output_index: type: integer - description: The index of the output item in the response. + description: The index of the output item in the Response. item: - type: object - description: The item that was added. - properties: - id: - type: string - description: The unique ID of the item. - object: - type: string - description: The object type, must be "realtime.item". - type: - type: string - description: The type of the item ("message", "function_call", - "function_call_output"). - status: - type: string - description: The status of the item ("in_progress", "completed"). - role: - type: string - description: The role associated with the item ("assistant"). - content: - type: array - description: The content of the item. - items: - type: object - properties: - type: - type: string - description: The content type ("text", "audio"). - text: - type: string - description: The text content. - audio: - type: string - description: Base64-encoded audio data. - transcript: - type: string - description: The transcript of the audio. + $ref: "#/components/schemas/RealtimeConversationItem" required: - event_id - type @@ -19031,59 +21869,28 @@ 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 - description: The event type, must be "response.output_item.done". + enum: + - response.output_item.done + description: The event type, must be `response.output_item.done`. response_id: type: string - description: The ID of the response to which the item belongs. + description: The ID of the Response to which the item belongs. output_index: type: integer - description: The index of the output item in the response. + description: The index of the output item in the Response. item: - type: object - description: The completed item. - properties: - id: - type: string - description: The unique ID of the item. - object: - type: string - description: The object type, must be "realtime.item". - type: - type: string - description: The type of the item ("message", "function_call", - "function_call_output"). - status: - type: string - description: The final status of the item ("completed", "incomplete"). - role: - type: string - description: The role associated with the item ("assistant"). - content: - type: array - description: The content of the item. - items: - type: object - properties: - type: - type: string - description: The content type ("text", "audio"). - text: - type: string - description: The text content. - audio: - type: string - description: Base64-encoded audio data. - transcript: - type: string - description: The transcript of the audio. + $ref: "#/components/schemas/RealtimeConversationItem" required: - event_id - type @@ -19122,7 +21929,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. @@ -19161,16 +21970,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. @@ -19209,103 +22022,24 @@ components: } RealtimeServerEventSessionCreated: type: object - description: Returned when a session is created. Emitted automatically when a - new connection is established. + 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 - description: The event type, must be "session.created". + enum: + - session.created + description: The event type, must be `session.created`. session: - type: object - description: The session resource. - properties: - id: - type: string - description: The unique ID of the session. - object: - type: string - description: The object type, must be "realtime.session". - model: - type: string - description: The default model used for this session. - modalities: - type: array - items: - type: string - description: The set of modalities the model can respond with. - instructions: - type: string - description: The default system instructions. - voice: - type: string - description: The voice the model uses to respond - one of `alloy`, `echo`, or - `shimmer`. - input_audio_format: - type: string - description: The format of input audio. - output_audio_format: - type: string - description: The format of output audio. - input_audio_transcription: - type: object - description: Configuration for input audio transcription. - properties: - enabled: - type: boolean - description: Whether input audio transcription is enabled. - model: - type: string - description: The model used for transcription. - turn_detection: - type: object - description: Configuration for turn detection. - properties: - type: - type: string - description: The type of turn detection ("server_vad" or "none"). - threshold: - type: number - description: Activation threshold for VAD. - prefix_padding_ms: - type: integer - description: Audio included before speech starts (in milliseconds). - silence_duration_ms: - type: integer - description: Duration of silence to detect speech stop (in milliseconds). - tools: - type: array - description: Tools (functions) available to the model. - items: - type: object - properties: - type: - type: string - description: The type of the tool. - name: - type: string - description: The name of the function. - description: - type: string - description: The description of the function. - parameters: - type: object - description: Parameters of the function in JSON Schema. - tool_choice: - type: string - description: How the model chooses tools. - temperature: - type: number - description: Sampling temperature. - max_output_tokens: - oneOf: - - type: integer - - type: string - enum: - - inf - description: Maximum number of output tokens. + $ref: "#/components/schemas/RealtimeSession" required: - event_id - type @@ -19320,10 +22054,10 @@ components: "session": { "id": "sess_001", "object": "realtime.session", - "model": "gpt-4o-realtime-preview-2024-10-01", + "model": "gpt-4o-realtime-preview-2024-12-17", "modalities": ["text", "audio"], - "instructions": "", - "voice": "alloy", + "instructions": "...model instructions here...", + "voice": "sage", "input_audio_format": "pcm16", "output_audio_format": "pcm16", "input_audio_transcription": null, @@ -19336,139 +22070,733 @@ components: "tools": [], "tool_choice": "auto", "temperature": 0.8, - "max_output_tokens": null + "max_response_output_tokens": "inf" } } RealtimeServerEventSessionUpdated: type: object - description: Returned when a session is updated. + 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 + enum: + - session.updated + description: The event type, must be `session.updated`. + session: + $ref: "#/components/schemas/RealtimeSession" + required: + - event_id + - type + - session + x-oaiMeta: + name: session.updated + group: realtime + example: | + { + "event_id": "event_5678", + "type": "session.updated", + "session": { + "id": "sess_001", + "object": "realtime.session", + "model": "gpt-4o-realtime-preview-2024-12-17", + "modalities": ["text"], + "instructions": "New instructions", + "voice": "sage", + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": { + "model": "whisper-1" + }, + "turn_detection": null, + "tools": [], + "tool_choice": "none", + "temperature": 0.7, + "max_response_output_tokens": 200 + } + } + RealtimeSession: + type: object + description: Realtime session object configuration. + properties: + id: + type: string + description: | + Unique identifier for the session object. + modalities: + description: | + The set of modalities the model can respond with. To disable audio, + set this to ["text"]. + items: + type: string + enum: + - text + - audio + model: + description: | + The Realtime model used for this session. + anyOf: + - type: string + - type: string + enum: + - gpt-4o-realtime-preview + - gpt-4o-realtime-preview-2024-10-01 + - gpt-4o-realtime-preview-2024-12-17 + - gpt-4o-mini-realtime-preview + - gpt-4o-mini-realtime-preview-2024-12-17 + instructions: + type: string + description: > + The default system instructions (i.e. system message) prepended to + model + + calls. This field allows the client to guide the model on desired + + responses. The model can be instructed on response content and + format, + + (e.g. "be extremely succinct", "act friendly", "here are examples of + good + + responses") and on audio behavior (e.g. "talk quickly", "inject + emotion + + into your voice", "laugh frequently"). The instructions are not + guaranteed + + to be followed by the model, but they provide guidance to the model + on the + + desired behavior. + + + Note that the server sets default instructions which will be used if + this + + field is not set and are visible in the `session.created` event at + the + + start of the session. + voice: + type: string + enum: + - alloy + - ash + - ballad + - coral + - echo + - sage + - shimmer + - verse + description: > + The voice the model uses to respond. Voice cannot be changed during + the + + session once the model has responded with audio at least once. + Current + + voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, + + `shimmer` and `verse`. + input_audio_format: + type: string + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of input audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + output_audio_format: + type: string + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + input_audio_transcription: + type: object + description: > + Configuration for input audio transcription, defaults to off and can + be + + set to `null` to turn off once on. Input audio transcription is not + native + + to the model, since the model consumes audio directly. Transcription + runs + + asynchronously through Whisper and should be treated as rough + guidance + + rather than the representation understood by the model. + properties: + model: + type: string + description: > + The model to use for transcription, `whisper-1` is the only + currently + + supported model. + turn_detection: + type: object + nullable: true + description: > + Configuration for turn detection. Can be set to `null` to turn off. + Server + + VAD means that the model will detect the start and end of speech + based on + + audio volume and respond at the end of user speech. + properties: + type: + type: string + enum: + - server_vad + description: > + Type of turn detection, only `server_vad` is currently supported. + threshold: + type: number + description: > + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. + A + + higher threshold will require louder audio to activate the + model, and + + thus might perform better in noisy environments. + prefix_padding_ms: + type: integer + description: | + Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. + silence_duration_ms: + type: integer + description: > + Duration of silence to detect speech stop (in milliseconds). + Defaults + + to 500ms. With shorter values the model will respond more + quickly, + + but may jump in on short pauses from the user. + tools: + type: array + description: Tools (functions) available to the model. + items: + type: object + properties: + type: + type: string + enum: + - function + description: The type of the tool, i.e. `function`. + name: + type: string + description: The name of the function. + description: + type: string + description: > + The description of the function, including guidance on when + and how + + to call it, and guidance about what to tell the user when + calling + + (if anything). + parameters: + type: object + description: Parameters of the function in JSON Schema. + tool_choice: + type: string + description: > + How the model chooses tools. Options are `auto`, `none`, `required`, + or + + specify a function. + temperature: + type: number + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. Defaults + to 0.8. + max_response_output_tokens: + oneOf: + - type: integer + - type: string + enum: + - inf + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls. Provide an integer between 1 and 4096 to + limit output tokens, or `inf` for the maximum available tokens for a + given model. Defaults to `inf`. + RealtimeSessionCreateRequest: + type: object + description: Realtime session object configuration. + required: + - model properties: - event_id: + modalities: + description: | + The set of modalities the model can respond with. To disable audio, + set this to ["text"]. + items: + type: string + enum: + - text + - audio + model: type: string - description: The unique ID of the server event. - type: + description: | + The Realtime model used for this session. + enum: + - gpt-4o-realtime-preview + - gpt-4o-realtime-preview-2024-10-01 + - gpt-4o-realtime-preview-2024-12-17 + - gpt-4o-mini-realtime-preview + - gpt-4o-mini-realtime-preview-2024-12-17 + instructions: type: string - description: The event type, must be "session.updated". - session: + description: > + The default system instructions (i.e. system message) prepended to + model + + calls. This field allows the client to guide the model on desired + + responses. The model can be instructed on response content and + format, + + (e.g. "be extremely succinct", "act friendly", "here are examples of + good + + responses") and on audio behavior (e.g. "talk quickly", "inject + emotion + + into your voice", "laugh frequently"). The instructions are not + guaranteed + + to be followed by the model, but they provide guidance to the model + on the + + desired behavior. + + + Note that the server sets default instructions which will be used if + this + + field is not set and are visible in the `session.created` event at + the + + start of the session. + voice: + type: string + enum: + - alloy + - ash + - ballad + - coral + - echo + - sage + - shimmer + - verse + description: > + The voice the model uses to respond. Voice cannot be changed during + the + + session once the model has responded with audio at least once. + Current + + voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, + + `shimmer` and `verse`. + input_audio_format: + type: string + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of input audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + output_audio_format: + type: string + enum: + - pcm16 + - g711_ulaw + - g711_alaw + description: > + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + input_audio_transcription: type: object - description: The updated session resource. + description: > + Configuration for input audio transcription, defaults to off and can + be + + set to `null` to turn off once on. Input audio transcription is not + native + + to the model, since the model consumes audio directly. Transcription + runs + + asynchronously through Whisper and should be treated as rough + guidance + + rather than the representation understood by the model. properties: - id: - type: string - description: The unique ID of the session. - object: - type: string - description: The object type, must be "realtime.session". model: type: string - description: The default model used for this session. - modalities: - type: array - items: - type: string - description: The set of modalities the model can respond with. - instructions: - type: string - description: The default system instructions. - voice: + description: > + The model to use for transcription, `whisper-1` is the only + currently + + supported model. + turn_detection: + type: object + description: > + Configuration for turn detection. Can be set to `null` to turn off. + Server + + VAD means that the model will detect the start and end of speech + based on + + audio volume and respond at the end of user speech. + properties: + type: type: string - description: The voice the model uses to respond - one of `alloy`, `echo`, or - `shimmer`. - input_audio_format: + description: > + Type of turn detection, only `server_vad` is currently supported. + threshold: + type: number + description: > + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. + A + + higher threshold will require louder audio to activate the + model, and + + thus might perform better in noisy environments. + prefix_padding_ms: + type: integer + description: | + Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. + silence_duration_ms: + type: integer + description: > + Duration of silence to detect speech stop (in milliseconds). + Defaults + + to 500ms. With shorter values the model will respond more + quickly, + + but may jump in on short pauses from the user. + create_response: + type: boolean + default: true + description: | + Whether or not to automatically generate a response when VAD is + enabled. `true` by default. + tools: + type: array + description: Tools (functions) available to the model. + items: + type: object + properties: + type: + type: string + enum: + - function + description: The type of the tool, i.e. `function`. + name: + type: string + description: The name of the function. + description: + type: string + description: > + The description of the function, including guidance on when + and how + + to call it, and guidance about what to tell the user when + calling + + (if anything). + parameters: + type: object + description: Parameters of the function in JSON Schema. + tool_choice: + type: string + description: > + How the model chooses tools. Options are `auto`, `none`, `required`, + or + + specify a function. + temperature: + type: number + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. Defaults + to 0.8. + max_response_output_tokens: + oneOf: + - type: integer + - type: string + enum: + - inf + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls. Provide an integer between 1 and 4096 to + limit output tokens, or `inf` for the maximum available tokens for a + given model. Defaults to `inf`. + RealtimeSessionCreateResponse: + type: object + description: > + A new Realtime session configuration, with an ephermeral key. Default + TTL + + for keys is one minute. + properties: + client_secret: + type: object + description: Ephemeral key returned by the API. + properties: + value: type: string - description: The format of input audio. - output_audio_format: + description: > + Ephemeral key usable in client environments to authenticate + connections + + to the Realtime API. Use this in client-side environments rather + than + + a standard API token, which should only be used server-side. + expires_at: + type: integer + description: > + Timestamp for when the token expires. Currently, all tokens + expire + + after one minute. + modalities: + 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: > + The default system instructions (i.e. system message) prepended to + model + + calls. This field allows the client to guide the model on desired + + responses. The model can be instructed on response content and + format, + + (e.g. "be extremely succinct", "act friendly", "here are examples of + good + + responses") and on audio behavior (e.g. "talk quickly", "inject + emotion + + into your voice", "laugh frequently"). The instructions are not + guaranteed + + to be followed by the model, but they provide guidance to the model + on the + + desired behavior. + + + Note that the server sets default instructions which will be used if + this + + field is not set and are visible in the `session.created` event at + the + + start of the session. + voice: + type: string + enum: + - alloy + - ash + - ballad + - coral + - echo + - sage + - shimmer + - verse + description: > + The voice the model uses to respond. Voice cannot be changed during + the + + session once the model has responded with audio at least once. + Current + + voice options are `alloy`, `ash`, `ballad`, `coral`, `echo` `sage`, + + `shimmer` and `verse`. + input_audio_format: + type: string + description: > + The format of input audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + output_audio_format: + type: string + description: > + The format of output audio. Options are `pcm16`, `g711_ulaw`, or + `g711_alaw`. + input_audio_transcription: + type: object + description: > + Configuration for input audio transcription, defaults to off and can + be + + set to `null` to turn off once on. Input audio transcription is not + native + + to the model, since the model consumes audio directly. Transcription + runs + + asynchronously through Whisper and should be treated as rough + guidance + + rather than the representation understood by the model. + properties: + model: type: string - description: The format of output audio. - input_audio_transcription: - type: object - description: Configuration for input audio transcription. - properties: - enabled: - type: boolean - description: Whether input audio transcription is enabled. - model: - type: string - description: The model used for transcription. - turn_detection: - type: object - description: Configuration for turn detection. - properties: - type: - type: string - description: The type of turn detection ("server_vad" or "none"). - threshold: - type: number - description: Activation threshold for VAD. - prefix_padding_ms: - type: integer - description: Audio included before speech starts (in milliseconds). - silence_duration_ms: - type: integer - description: Duration of silence to detect speech stop (in milliseconds). - tools: - type: array - description: Tools (functions) available to the model. - items: - type: object - properties: - type: - type: string - description: The type of the tool. - name: - type: string - description: The name of the function. - description: - type: string - description: The description of the function. - parameters: - type: object - description: Parameters of the function in JSON Schema. - tool_choice: + description: > + The model to use for transcription, `whisper-1` is the only + currently + + supported model. + turn_detection: + type: object + description: > + Configuration for turn detection. Can be set to `null` to turn off. + Server + + VAD means that the model will detect the start and end of speech + based on + + audio volume and respond at the end of user speech. + properties: + type: type: string - description: How the model chooses tools. - temperature: + description: > + Type of turn detection, only `server_vad` is currently supported. + threshold: type: number - description: Sampling temperature. - max_output_tokens: - oneOf: - - type: integer - - type: string - enum: - - inf - description: Maximum number of output tokens. - required: - - event_id - - type - - session - x-oaiMeta: - name: session.updated - group: realtime - example: | - { - "event_id": "event_5678", - "type": "session.updated", - "session": { - "id": "sess_001", - "object": "realtime.session", - "model": "gpt-4o-realtime-preview-2024-10-01", - "modalities": ["text"], - "instructions": "New instructions", - "voice": "alloy", - "input_audio_format": "pcm16", - "output_audio_format": "pcm16", - "input_audio_transcription": { - "enabled": true, - "model": "whisper-1" - }, - "turn_detection": { - "type": "none" - }, - "tools": [], - "tool_choice": "none", - "temperature": 0.7, - "max_output_tokens": 200 - } + description: > + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. + A + + higher threshold will require louder audio to activate the + model, and + + thus might perform better in noisy environments. + prefix_padding_ms: + type: integer + description: | + Amount of audio to include before the VAD detected speech (in + milliseconds). Defaults to 300ms. + silence_duration_ms: + type: integer + description: > + Duration of silence to detect speech stop (in milliseconds). + Defaults + + to 500ms. With shorter values the model will respond more + quickly, + + but may jump in on short pauses from the user. + tools: + type: array + description: Tools (functions) available to the model. + items: + type: object + properties: + type: + type: string + enum: + - function + description: The type of the tool, i.e. `function`. + name: + type: string + description: The name of the function. + description: + type: string + description: > + The description of the function, including guidance on when + and how + + to call it, and guidance about what to tell the user when + calling + + (if anything). + parameters: + type: object + description: Parameters of the function in JSON Schema. + tool_choice: + type: string + description: > + How the model chooses tools. Options are `auto`, `none`, `required`, + or + + specify a function. + temperature: + type: number + description: > + Sampling temperature for the model, limited to [0.6, 1.2]. Defaults + to 0.8. + max_response_output_tokens: + oneOf: + - type: integer + - type: string + enum: + - inf + description: | + Maximum number of output tokens for a single assistant response, + inclusive of tool calls. Provide an integer between 1 and 4096 to + limit output tokens, or `inf` for the maximum available tokens for a + given model. Defaults to `inf`. + x-oaiMeta: + name: The session object + group: realtime + example: | + { + "id": "sess_001", + "object": "realtime.session", + "model": "gpt-4o-realtime-preview-2024-12-17", + "modalities": ["audio", "text"], + "instructions": "You are a friendly assistant.", + "voice": "alloy", + "input_audio_format": "pcm16", + "output_audio_format": "pcm16", + "input_audio_transcription": { + "model": "whisper-1" + }, + "turn_detection": null, + "tools": [], + "tool_choice": "none", + "temperature": 0.7, + "max_response_output_tokens": 200, + "client_secret": { + "value": "ek_abc123", + "expires_at": 1234567890 + } } ResponseFormatJsonObject: type: object @@ -21129,6 +24457,453 @@ 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 + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + nullable: true + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + nullable: true + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + nullable: true + 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": "organization.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 + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + nullable: true + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + nullable: true + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + nullable: true + 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": "organization.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 + nullable: true + 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": "organization.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 aggregated number of text input tokens used, including cached + tokens. For customers subscribe to scale tier, this includes scale + tier tokens. + input_cached_tokens: + type: integer + description: The aggregated number of text input tokens that has been cached + from previous requests. For customers subscribe to scale tier, this + includes scale tier tokens. + output_tokens: + type: integer + description: The aggregated number of text output tokens used. For customers + subscribe to scale tier, this includes scale tier tokens. + input_audio_tokens: + type: integer + description: The aggregated number of audio input tokens used, including cached + tokens. + output_audio_tokens: + type: integer + description: The aggregated number of audio output tokens used. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + nullable: true + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + nullable: true + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + nullable: true + description: When `group_by=model`, this field provides the model name of the + grouped usage result. + batch: + type: boolean + nullable: true + 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": "organization.usage.completions.result", + "input_tokens": 5000, + "output_tokens": 1000, + "input_cached_tokens": 4000, + "input_audio_tokens": 300, + "output_audio_tokens": 200, + "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 aggregated number of input tokens used. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + nullable: true + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + nullable: true + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + nullable: true + 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": "organization.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 + nullable: true + 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 + nullable: true + description: When `group_by=size`, this field provides the image size of the + grouped usage result. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + nullable: true + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + nullable: true + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + nullable: true + 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": "organization.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 aggregated number of input tokens used. + num_model_requests: + type: integer + description: The count of requests made to the model. + project_id: + type: string + nullable: true + description: When `group_by=project_id`, this field provides the project ID of + the grouped usage result. + user_id: + type: string + nullable: true + description: When `group_by=user_id`, this field provides the user ID of the + grouped usage result. + api_key_id: + type: string + nullable: true + description: When `group_by=api_key_id`, this field provides the API key ID of + the grouped usage result. + model: + type: string + nullable: true + 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": "organization.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 + nullable: true + 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": "organization.usage.vector_stores.result", + "usage_bytes": 1024, + "project_id": "proj_abc" + } User: type: object description: Represents an individual `user` within an organization. @@ -21628,10 +25403,13 @@ x-oaiMeta: key: cancelFineTuningJob path: cancel - type: object - key: FinetuneChatRequestInput + key: FineTuneChatRequestInput path: chat-input - type: object - key: FinetuneCompletionRequestInput + key: FineTunePreferenceRequestInput + path: preference-input + - type: object + key: FineTuneCompletionRequestInput path: completions-input - type: object key: FineTuningJob @@ -22030,7 +25808,7 @@ x-oaiMeta: API keys cannot be used for non-administration endpoints. For best practices on setting up your organization, please refer to this - [guide](/docs/guides/production-best-practices/setting-up-your-organization) + [guide](/docs/guides/production-best-practices#setting-up-your-organization) navigationGroup: administration - id: invite title: Invites @@ -22180,6 +25958,22 @@ x-oaiMeta: - type: object key: ProjectApiKey path: object + - id: project-rate-limits + title: Project rate limits + description: > + Manage rate limits per model for projects. Rate limits may be configured + to be equal to or lower than the organization's rate limits. + navigationGroup: administration + sections: + - type: endpoint + key: list-project-rate-limits + path: list + - type: endpoint + key: update-project-rate-limits + path: update + - type: object + key: ProjectRateLimit + path: object - id: audit-logs title: Audit logs description: > @@ -22198,17 +25992,102 @@ 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 + description: | + Communicate with a GPT-4o class model in real time using WebRTC or + WebSockets. Supports text and audio inputs and ouputs, along with audio + transcriptions. + [Learn more about the Realtime API](/docs/guides/realtime). + navigationGroup: realtime + - id: realtime-sessions + title: Session tokens description: > - Communicate with a GPT-4o class model live, in real time, over - WebSocket. + REST API endpoint to generate ephemeral session tokens for use in + client-side - Produces both audio and text transcriptions. - - [Learn more about the Realtime API](/docs/guides/realtime). + applications. navigationGroup: realtime + sections: + - type: endpoint + key: create-realtime-session + path: create + - type: object + key: RealtimeSessionCreateResponse + path: session_object - id: realtime-client-events title: Client events description: > @@ -22342,7 +26221,7 @@ x-oaiMeta: Given a prompt, the model will return one or more predicted completions along with the probabilities of alternative tokens at each position. Most developer should use our [Chat Completions - API](/docs/guides/text-generation/text-generation-models) to leverage + API](/docs/guides/text-generation#text-generation-models) to leverage our best and newest models. sections: - type: endpoint