feat: openai files api (#2321)

# What does this PR do?
* Adds the OpenAI compatible Files API
* Modified doc gen script to support multipart parameter

## Test Plan

---
[//]: # (BEGIN SAPLING FOOTER)
Stack created with [Sapling](https://sapling-scm.com). Best reviewed
with
[ReviewStack](https://reviewstack.dev/meta-llama/llama-stack/pull/2321).
* #2330
* __->__ #2321
This commit is contained in:
ehhuang 2025-06-02 11:45:53 -07:00 committed by GitHub
parent 17f4414be9
commit 31a3ae60f4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 881 additions and 946 deletions

View file

@ -633,90 +633,6 @@
}
}
},
"/v1/files": {
"get": {
"responses": {
"200": {
"description": "A ListBucketResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListBucketResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "List all buckets.",
"parameters": [
{
"name": "bucket",
"in": "query",
"description": "Bucket name (valid chars: a-zA-Z0-9_-).",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"post": {
"responses": {
"200": {
"description": "A FileUploadResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileUploadResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "Create a new upload session for a file identified by a bucket and key.",
"parameters": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateUploadSessionRequest"
}
}
},
"required": true
}
}
},
"/v1/agents/{agent_id}": {
"get": {
"responses": {
@ -901,101 +817,6 @@
]
}
},
"/v1/files/{bucket}/{key}": {
"get": {
"responses": {
"200": {
"description": "A FileResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "Get a file info identified by a bucket and key.",
"parameters": [
{
"name": "bucket",
"in": "path",
"description": "Bucket name (valid chars: a-zA-Z0-9_-).",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "key",
"in": "path",
"description": "Key under which the file is stored (valid chars: a-zA-Z0-9_-/.).",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"delete": {
"responses": {
"200": {
"description": "OK"
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "Delete a file identified by a bucket and key.",
"parameters": [
{
"name": "bucket",
"in": "path",
"description": "Bucket name (valid chars: a-zA-Z0-9_-).",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "key",
"in": "path",
"description": "Key under which the file is stored (valid chars: a-zA-Z0-9_-/.).",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/v1/inference/embeddings": {
"post": {
"responses": {
@ -1979,108 +1800,6 @@
"parameters": []
}
},
"/v1/files/session:{upload_id}": {
"get": {
"responses": {
"200": {
"description": "A FileUploadResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileUploadResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "Returns information about an existsing upload session.",
"parameters": [
{
"name": "upload_id",
"in": "path",
"description": "ID of the upload session.",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"post": {
"responses": {
"200": {
"description": "A FileResponse or None if the upload is not complete.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/FileResponse"
},
{
"type": "null"
}
]
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "Upload file content to an existing upload session. On the server, request body will have the raw bytes that are uploaded.",
"parameters": [
{
"name": "upload_id",
"in": "path",
"description": "ID of the upload session.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
},
"required": true
}
}
},
"/v1/vector-dbs/{vector_db_id}": {
"get": {
"responses": {
@ -2877,49 +2596,6 @@
}
}
},
"/v1/files/{bucket}": {
"get": {
"responses": {
"200": {
"description": "A ListFileResponse.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListFileResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "List all files in a bucket.",
"parameters": [
{
"name": "bucket",
"in": "path",
"description": "Bucket name (valid chars: a-zA-Z0-9_-).",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/v1/models": {
"get": {
"responses": {
@ -3607,6 +3283,90 @@
}
}
},
"/v1/openai/v1/files/{file_id}": {
"get": {
"responses": {
"200": {
"description": "An OpenAIFileObject containing file information.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenAIFileObject"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "Returns information about a specific file.",
"parameters": [
{
"name": "file_id",
"in": "path",
"description": "The ID of the file to use for this request.",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"delete": {
"responses": {
"200": {
"description": "An OpenAIFileDeleteResponse indicating successful deletion.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenAIFileDeleteResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "Delete a file.",
"parameters": [
{
"name": "file_id",
"in": "path",
"description": "The ID of the file to use for this request.",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/v1/openai/v1/embeddings": {
"post": {
"responses": {
@ -3650,6 +3410,130 @@
}
}
},
"/v1/openai/v1/files": {
"get": {
"responses": {
"200": {
"description": "An ListOpenAIFileResponse containing the list of files.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListOpenAIFileResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "Returns a list of files that belong to the user's organization.",
"parameters": [
{
"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"
}
},
{
"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"
}
},
{
"name": "order",
"in": "query",
"description": "Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.",
"required": false,
"schema": {
"$ref": "#/components/schemas/Order"
}
},
{
"name": "purpose",
"in": "query",
"description": "Only return files with the given purpose.",
"required": false,
"schema": {
"$ref": "#/components/schemas/OpenAIFilePurpose"
}
}
]
},
"post": {
"responses": {
"200": {
"description": "An OpenAIFileObject representing the uploaded file.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpenAIFileObject"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "Upload a file that can be used across various endpoints.\nThe file upload should be a multipart form request with:\n- file: The File object (not file name) to be uploaded.\n- purpose: The intended purpose of the uploaded file.",
"parameters": [],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"purpose": {
"$ref": "#/components/schemas/OpenAIFilePurpose"
}
},
"required": [
"file",
"purpose"
]
}
}
},
"required": true
}
}
},
"/v1/openai/v1/models": {
"get": {
"responses": {
@ -3683,6 +3567,49 @@
"parameters": []
}
},
"/v1/openai/v1/files/{file_id}/content": {
"get": {
"responses": {
"200": {
"description": "The raw file content as a binary response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Response"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest400"
},
"429": {
"$ref": "#/components/responses/TooManyRequests429"
},
"500": {
"$ref": "#/components/responses/InternalServerError500"
},
"default": {
"$ref": "#/components/responses/DefaultError"
}
},
"tags": [
"Files"
],
"description": "Returns the contents of the specified file.",
"parameters": [
{
"name": "file_id",
"in": "path",
"description": "The ID of the file to use for this request.",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/v1/post-training/preference-optimize": {
"post": {
"responses": {
@ -7672,65 +7599,6 @@
],
"title": "OpenAIResponseObjectStreamResponseOutputTextDelta"
},
"CreateUploadSessionRequest": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"description": "Bucket under which the file is stored (valid chars: a-zA-Z0-9_-)."
},
"key": {
"type": "string",
"description": "Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)."
},
"mime_type": {
"type": "string",
"description": "MIME type of the file."
},
"size": {
"type": "integer",
"description": "File size in bytes."
}
},
"additionalProperties": false,
"required": [
"bucket",
"key",
"mime_type",
"size"
],
"title": "CreateUploadSessionRequest"
},
"FileUploadResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the upload session"
},
"url": {
"type": "string",
"description": "Upload URL for the file or file parts"
},
"offset": {
"type": "integer",
"description": "Upload content offset"
},
"size": {
"type": "integer",
"description": "Upload content size"
}
},
"additionalProperties": false,
"required": [
"id",
"url",
"offset",
"size"
],
"title": "FileUploadResponse",
"description": "Response after initiating a file upload session."
},
"EmbeddingsRequest": {
"type": "object",
"properties": {
@ -8994,46 +8862,6 @@
"title": "URIDataSource",
"description": "A dataset that can be obtained from a URI."
},
"FileResponse": {
"type": "object",
"properties": {
"bucket": {
"type": "string",
"description": "Bucket under which the file is stored (valid chars: a-zA-Z0-9_-)"
},
"key": {
"type": "string",
"description": "Key under which the file is stored (valid chars: a-zA-Z0-9_-/.)"
},
"mime_type": {
"type": "string",
"description": "MIME type of the file"
},
"url": {
"type": "string",
"description": "Upload URL for the file contents"
},
"bytes": {
"type": "integer",
"description": "Size of the file in bytes"
},
"created_at": {
"type": "integer",
"description": "Timestamp of when the file was created"
}
},
"additionalProperties": false,
"required": [
"bucket",
"key",
"mime_type",
"url",
"bytes",
"created_at"
],
"title": "FileResponse",
"description": "Response representing a file entry."
},
"Model": {
"type": "object",
"properties": {
@ -10347,37 +10175,6 @@
],
"title": "Job"
},
"BucketResponse": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"name"
],
"title": "BucketResponse"
},
"ListBucketResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BucketResponse"
},
"description": "List of FileResponse entries"
}
},
"additionalProperties": false,
"required": [
"data"
],
"title": "ListBucketResponse",
"description": "Response representing a list of file entries."
},
"ListBenchmarksResponse": {
"type": "object",
"properties": {
@ -10495,24 +10292,6 @@
],
"title": "ListDatasetsResponse"
},
"ListFileResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FileResponse"
},
"description": "List of FileResponse entries"
}
},
"additionalProperties": false,
"required": [
"data"
],
"title": "ListFileResponse",
"description": "Response representing a list of file entries."
},
"ListModelsResponse": {
"type": "object",
"properties": {
@ -11820,6 +11599,33 @@
"title": "OpenAICompletionChoice",
"description": "A choice from an OpenAI-compatible completion response."
},
"OpenAIFileDeleteResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The file identifier that was deleted"
},
"object": {
"type": "string",
"const": "file",
"default": "file",
"description": "The object type, which is always \"file\""
},
"deleted": {
"type": "boolean",
"description": "Whether the file was successfully deleted"
}
},
"additionalProperties": false,
"required": [
"id",
"object",
"deleted"
],
"title": "OpenAIFileDeleteResponse",
"description": "Response for deleting a file in OpenAI Files API."
},
"OpenaiEmbeddingsRequest": {
"type": "object",
"properties": {
@ -11953,6 +11759,101 @@
"title": "OpenAIEmbeddingsResponse",
"description": "Response from an OpenAI-compatible embeddings request."
},
"OpenAIFilePurpose": {
"type": "string",
"enum": [
"assistants"
],
"title": "OpenAIFilePurpose",
"description": "Valid purpose values for OpenAI Files API."
},
"ListOpenAIFileResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OpenAIFileObject"
},
"description": "List of file objects"
},
"has_more": {
"type": "boolean"
},
"first_id": {
"type": "string"
},
"last_id": {
"type": "string"
},
"object": {
"type": "string",
"const": "list",
"default": "list",
"description": "The object type, which is always \"list\""
}
},
"additionalProperties": false,
"required": [
"data",
"has_more",
"first_id",
"last_id",
"object"
],
"title": "ListOpenAIFileResponse",
"description": "Response for listing files in OpenAI Files API."
},
"OpenAIFileObject": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "file",
"default": "file",
"description": "The object type, which is always \"file\""
},
"id": {
"type": "string",
"description": "The file identifier, which can be referenced in the API endpoints"
},
"bytes": {
"type": "integer",
"description": "The size of the file, in bytes"
},
"created_at": {
"type": "integer",
"description": "The Unix timestamp (in seconds) for when the file was created"
},
"expires_at": {
"type": "integer",
"description": "The Unix timestamp (in seconds) for when the file expires"
},
"filename": {
"type": "string",
"description": "The name of the file"
},
"purpose": {
"type": "string",
"enum": [
"assistants"
],
"description": "The intended purpose of the file"
}
},
"additionalProperties": false,
"required": [
"object",
"id",
"bytes",
"created_at",
"expires_at",
"filename",
"purpose"
],
"title": "OpenAIFileObject",
"description": "OpenAI File object as defined in the OpenAI Files API."
},
"OpenAIModel": {
"type": "object",
"properties": {
@ -11997,6 +11898,10 @@
],
"title": "OpenAIListModelsResponse"
},
"Response": {
"type": "object",
"title": "Response"
},
"DPOAlignmentConfig": {
"type": "object",
"properties": {