openai_interface/files/create/
mod.rs

1//! File upload functionality for OpenAI-compatible APIs
2//!
3//! This module provides functionality for uploading files to OpenAI-compatible APIs.
4//! Files can be uploaded for various purposes such as fine-tuning, batch processing,
5//! assistants, and more.
6//!
7//! # Overview
8//!
9//! The `create` module contains:
10//! - [`request`]: File upload request types and functionality
11//! - [`response`]: File object response types
12//! - Support for multipart/form-data file uploads
13//! - Comprehensive error handling for file operations
14//!
15//! # Features
16//!
17//! - **File Upload**: Upload files up to 512 MB in size
18//! - **Multiple Purposes**: Support for various file purposes (assistants, batch, fine-tune, etc.)
19//! - **Expiration Policies**: Configurable file expiration policies
20//! - **Multipart Uploads**: Proper handling of multipart/form-data requests
21//!
22//! # Examples
23//!
24//! ## Basic File Upload
25//!
26//! This example demonstrates how to upload a file for batch processing:
27//!
28//! ```rust
29//! use std::path::PathBuf;
30//! use std::sync::LazyLock;
31//! use openai_interface::files::create::request::{CreateFileRequest, FilePurpose};
32//! use openai_interface::files::create::response::FileObject;
33//! use openai_interface::rest::post::NoStream;
34//!
35//! const MODELSCOPE_URL: &str = "https://dashscope.aliyuncs.com/compatible-mode/v1/files";
36//! const MODELSCOPE_KEY: LazyLock<&str> =
37//!     LazyLock::new(|| include_str!("../../../keys/modelstudio_domestic_key").trim());
38//!
39//! #[tokio::main]
40//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
41//!     let file_path = PathBuf::from("src/files/create/file-test.txt");
42//!     let create_file_request = CreateFileRequest {
43//!         file: file_path,
44//!         purpose: FilePurpose::Batch,
45//!         ..Default::default()
46//!     };
47//!
48//!     let response: FileObject = create_file_request
49//!         .get_response(MODELSCOPE_URL, MODELSCOPE_KEY.as_ref())
50//!         .await?;
51//!
52//!     println!("Uploaded file ID: {}", response.id);
53//!     println!("File size: {} bytes", response.bytes);
54//!     println!("Filename: {}", response.filename);
55//!     Ok(())
56//! }
57//! ```
58//!
59//! ## File Upload with Custom Purpose
60//!
61//! This example shows how to upload a file with a custom purpose:
62//!
63//! ```rust
64//! use std::path::PathBuf;
65//! use std::sync::LazyLock;
66//! use openai_interface::files::create::request::{CreateFileRequest, FilePurpose};
67//! use openai_interface::files::create::response::FileObject;
68//! use openai_interface::rest::post::NoStream;
69//!
70//! const MODELSCOPE_URL: &str = "https://dashscope.aliyuncs.com/compatible-mode/v1/files";
71//! const MODELSCOPE_KEY: LazyLock<&str> =
72//!     LazyLock::new(|| include_str!("../../../keys/modelstudio_domestic_key").trim());
73//!
74//! #[tokio::main]
75//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
76//!     let file_path = PathBuf::from("src/files/create/file-test.txt");
77//!     let create_file_request = CreateFileRequest {
78//!         file: file_path,
79//!         purpose: FilePurpose::Other("file-extract".to_string()),
80//!         ..Default::default()
81//!     };
82//!
83//!     let response: FileObject = create_file_request
84//!         .get_response(MODELSCOPE_URL, MODELSCOPE_KEY.as_ref())
85//!         .await?;
86//!
87//!     println!("Uploaded file with custom purpose: {}", response.id);
88//!     Ok(())
89//! }
90//! ```
91//!
92//! # File Size Limits
93//!
94//! - Individual files can be up to 512 MB
95//! - Total organization storage can be up to 1 TB
96//! - Batch API files are limited to 200 MB
97//! - Fine-tuning API only supports `.jsonl` files
98//!
99//! # Supported File Purposes
100//!
101//! - `assistants`: Used in the Assistants API
102//! - `batch`: Used in the Batch API (expires after 30 days by default)
103//! - `fine-tune`: Used for fine-tuning
104//! - `vision`: Images used for vision fine-tuning
105//! - `user_data`: Flexible file type for any purpose
106//! - `evals`: Used for eval data sets
107//! - Custom purposes via the `Other` variant
108//!
109//! # Error Handling
110//!
111//! The module provides comprehensive error handling for:
112//! - File not found errors
113//! - File read permissions
114//! - Network connectivity issues
115//! - API authentication failures
116//! - Invalid file formats
117//! - Size limit violations
118
119pub mod request;
120pub mod response;
121
122#[cfg(test)]
123mod tests {
124    use std::{path::PathBuf, sync::LazyLock};
125
126    use crate::rest::post::NoStream;
127
128    use super::*;
129
130    const TEST_FILE_PATH: &str = "src/files/create/file-test.txt";
131    const MODELSCOPE_URL: &str = "https://dashscope.aliyuncs.com/compatible-mode/v1/files";
132    const MODELSCOPE_KEY: LazyLock<&str> =
133        LazyLock::new(|| include_str!("../../../keys/modelstudio_domestic_key").trim());
134
135    #[tokio::test]
136    async fn test_file_create() -> Result<(), anyhow::Error> {
137        let file_path = PathBuf::from(TEST_FILE_PATH);
138        let create_file_request = request::CreateFileRequest {
139            file: file_path,
140            purpose: request::FilePurpose::Other("file-extract".to_string()),
141            ..Default::default()
142        };
143
144        let response = create_file_request
145            .get_response(MODELSCOPE_URL, MODELSCOPE_KEY.as_ref())
146            .await?;
147
148        println!("Uploaded file ID: {}", response.id);
149        println!("File size: {} bytes", response.bytes);
150        println!("Filename: {}", response.filename);
151
152        Ok(())
153    }
154}