OpenAIFilesAPI

The OpenAIFilesAPI class provides functionalities to manage files using OpenAI's API. Files can be uploaded and used across various endpoints including Fine-tuning, Batch processing, and Vision.

Note: This API is only compatible with OpenAI. Other providers listed in the compatible providers documentation do not support file management operations.

API Reference: https://platform.openai.com/docs/api-reference/files

File Size Limits

• Individual files: up to 512 MB per file
• Organization total: up to 1 TB (cumulative size of all files uploaded by your organization)

Functions

create()

create(file : 4D.File | 4D.Blob; purpose : Text; parameters : cs.OpenAIFileParameters) : cs.OpenAIFileResult

Upload a file that can be used across various endpoints.

Endpoint: POST https://api.openai.com/v1/files

Parameter	Type	Description
file	4D.File or 4D.Blob	The File or Blob object (not file name) to be uploaded.
purpose	Text	Required. The intended purpose of the uploaded file.
parameters	OpenAIFileParameters	Optional parameters including expiration policy.
Function result	OpenAIFileResult	The file result

Throws: An error if file is not a 4D.File or 4D.Blob, or if purpose is empty.

Supported Purposes

• assistants: Used in the Assistants API (⚠️ deprecated by OpenAI)
• batch: Used in the Batch API (expires after 30 days by default)
• fine-tune: Used for fine-tuning
• vision: Images used for vision fine-tuning
• user_data: Flexible file type for any purpose
• evals: Used for eval data sets

File Format Requirements

• Fine-tuning API: Only supports .jsonl files with specific required formats
• Batch API: Only supports .jsonl files up to 200 MB with specific required format
• Assistants API: Supports specific file types (see Assistants Tools guide)
• Chat Completions API: PDFs are only supported

Example

var $file:=File("/RESOURCES/training-data.jsonl")

var $params:=cs.AIKit.OpenAIFileParameters.new()
$params.expires_after:={}
$params.expires_after.anchor:="created_at"
$params.expires_after.seconds:=2592000  // 30 days

var $result:=$client.files.create($file; "fine-tune"; $params)

If ($result.success)
    var $uploadedFile:=$result.file
    // $uploadedFile.id -> "file-abc123"
    // $uploadedFile.filename -> "training-data.jsonl"
    // $uploadedFile.bytes -> 120000
End if

retrieve()

retrieve(fileId : Text; parameters : cs.OpenAIParameters) : cs.OpenAIFileResult

Returns information about a specific file.

Endpoint: GET https://api.openai.com/v1/files/{file_id}

Parameter	Type	Description
fileId	Text	Required. The ID of the file to retrieve.
parameters	OpenAIParameters	Optional parameters for the request.
Function result	OpenAIFileResult	The file result

Throws: An error if fileId is empty.

Example

var $result:=$client.files.retrieve("file-abc123")

If ($result.success)
    var $file:=$result.file
    // $file.filename -> "mydata.jsonl"
    // $file.bytes -> 120000
    // $file.purpose -> "fine-tune"
End if

list()

list(parameters : cs.OpenAIFileListParameters) : cs.OpenAIFileListResult

Returns a list of files that belong to the user's organization.

Endpoint: GET https://api.openai.com/v1/files

Parameter	Type	Description
parameters	OpenAIFileListParameters	Optional parameters for filtering and pagination.
Function result	OpenAIFileListResult	The file list result

Example

var $params:=cs.AIKit.OpenAIFileListParameters.new()
$params.purpose:="assistants"
$params.limit:=50
$params.order:="desc"

var $result:=$client.files.list($params)

If ($result.success)
    var $files:=$result.files
    // $files.length -> 2
    
    For each ($file; $files)
        // $file.filename -> "salesOverview.pdf", "puppy.jsonl", etc.
    End for each
End if

delete()

delete(fileId : Text; parameters : cs.OpenAIParameters) : cs.OpenAIFileDeletedResult

Delete a file.

Endpoint: DELETE https://api.openai.com/v1/files/{file_id}

Parameter	Type	Description
fileId	Text	Required. The ID of the file to delete.
parameters	OpenAIParameters	Optional parameters for the request.
Function result	OpenAIFileDeletedResult	The file deletion result

Throws: An error if fileId is empty.

Example

var $result:=$client.files.delete("file-abc123")

If ($result.success)
    var $status:=$result.deleted
    
    If ($status.deleted)
        ALERT("File deleted successfully")
    End if
End if

See also

• OpenAIFile
• OpenAIFileParameters
• OpenAIFileListParameters
• OpenAIFileResult
• OpenAIFileListResult
• OpenAIFileDeletedResult