feat: extend file list API with enhanced parameters

Add support for querying specific files with URL generation options:

- Add FileListRequest entity with fileIds, getUrl, and expires parameters
- Extend OpenAiApi with POST /files/list endpoint
- Add overloaded listFiles method in OpenAiService
- Include comprehensive tests for new functionality

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: 2 people

api/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>top.bella</groupId>
         <artifactId>openai-java</artifactId>
-        <version>0.23.89</version>
+        <version>0.23.90</version>
     </parent>
     <packaging>jar</packaging>
     <artifactId>openai-api</artifactId>

api/src/main/java/com/theokanning/openai/file/FileListRequest.java

@@ -0,0 +1,37 @@
+package com.theokanning.openai.file;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+
+/**
+ * Request object for listing files with specific parameters
+ */
+@Data
+@Builder
+@AllArgsConstructor
+@NoArgsConstructor
+public class FileListRequest {
+
+    /**
+     * List of file IDs to retrieve
+     */
+    @JsonProperty("file_ids")
+    private List<String> fileIds;
+
+    /**
+     * Whether to include file URLs in the response
+     */
+    @JsonProperty("get_url")
+    private Boolean getUrl;
+
+    /**
+     * URL expiration time in seconds (only used when getUrl is true)
+     */
+    @JsonProperty("expires")
+    private Long expires;
+}

client/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>top.bella</groupId>
         <artifactId>openai-java</artifactId>
-        <version>0.23.89</version>
+        <version>0.23.90</version>
     </parent>
     <packaging>jar</packaging>
 

client/src/main/java/com/theokanning/openai/client/OpenAiApi.java

@@ -33,6 +33,7 @@
 import com.theokanning.openai.embedding.EmbeddingRequest;
 import com.theokanning.openai.embedding.EmbeddingResult;
 import com.theokanning.openai.file.File;
+import com.theokanning.openai.file.FileListRequest;
 import com.theokanning.openai.file.FileUrl;
 import com.theokanning.openai.fine_tuning.FineTuningEvent;
 import com.theokanning.openai.fine_tuning.FineTuningJob;
@@ -101,6 +102,9 @@ public interface OpenAiApi {
     @GET("files")
     Single<OpenAiResponse<File>> listFiles();
 
+    @POST("files/list")
+    Single<List<File>> listFiles(@Body FileListRequest request);
+
     @DELETE("files/{file_id}")
     Single<DeleteResult> deleteFile(@Path("file_id") String fileId);
 

example/pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>io.github.ke</groupId>
     <artifactId>example</artifactId>
-    <version>0.23.89</version>
+    <version>0.23.90</version>
     <name>example</name>
 
     <properties>

pom.xml

@@ -5,7 +5,7 @@
 
     <groupId>top.bella</groupId>
     <artifactId>openai-java</artifactId>
-    <version>0.23.89</version>
+    <version>0.23.90</version>
     <packaging>pom</packaging>
     <description>openai java 版本</description>
     <name>openai-java</name>

service/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>top.bella</groupId>
         <artifactId>openai-java</artifactId>
-        <version>0.23.89</version>
+        <version>0.23.90</version>
     </parent>
     <packaging>jar</packaging>
 

service/src/main/java/com/theokanning/openai/service/OpenAiService.java

@@ -59,6 +59,7 @@
 import com.theokanning.openai.embedding.EmbeddingRequest;
 import com.theokanning.openai.embedding.EmbeddingResult;
 import com.theokanning.openai.file.File;
+import com.theokanning.openai.file.FileListRequest;
 import com.theokanning.openai.file.FileUrl;
 import com.theokanning.openai.fine_tuning.FineTuningEvent;
 import com.theokanning.openai.fine_tuning.FineTuningJob;
@@ -268,6 +269,10 @@ public List<File> listFiles() {
         return execute(api.listFiles()).data;
     }
 
+    public List<File> listFiles(FileListRequest request) {
+        return execute(api.listFiles(request));
+    }
+
     public DeleteResult deleteFile(String fileId) {
         return execute(api.deleteFile(fileId));
     }

service/src/test/java/com/theokanning/openai/service/FileTest.java

@@ -2,6 +2,7 @@
 
 import com.theokanning.openai.DeleteResult;
 import com.theokanning.openai.file.File;
+import com.theokanning.openai.file.FileListRequest;
 import org.junit.jupiter.api.MethodOrderer;
 import org.junit.jupiter.api.Order;
 import org.junit.jupiter.api.Test;
@@ -11,10 +12,12 @@
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Paths;
+import java.util.Arrays;
 import java.util.List;
 import java.util.concurrent.TimeUnit;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 @TestMethodOrder(MethodOrderer.OrderAnnotation.class)
@@ -66,4 +69,52 @@ void uploadFileStream() throws Exception {
         DeleteResult result = service.deleteFile(fileId);
         assertTrue(result.isDeleted());
     }
+
+    @Test
+    @Order(3)
+    void listFilesWithRequest() {
+        // 首先上传一些测试文件
+        String filePath1 = "src/test/resources/fine-tuning-data.jsonl";
+        String filePath2 = "batch-task-data.jsonl";
+        
+        File file1 = service.uploadFile("fine-tune", filePath1);
+        InputStream resourceAsStream = getClass().getClassLoader().getResourceAsStream(filePath2);
+        File file2 = service.uploadFile("fine-tune", resourceAsStream, "batch-task-data.jsonl");
+        
+        String fileId1 = file1.getId();
+        String fileId2 = file2.getId();
+        
+        try {
+            // 测试使用 FileListRequest 查询指定文件
+            FileListRequest request = FileListRequest.builder()
+                    .fileIds(Arrays.asList(fileId1, fileId2))
+                    .getUrl(true)
+                    .expires(3600L)
+                    .build();
+            
+            List<File> files = service.listFiles(request);
+            
+            // 验证结果
+            assertNotNull(files);
+            assertEquals(2, files.size());
+            assertTrue(files.stream().anyMatch(f -> f.getId().equals(fileId1)));
+            assertTrue(files.stream().anyMatch(f -> f.getId().equals(fileId2)));
+            
+            // 测试只查询一个文件
+            FileListRequest singleFileRequest = FileListRequest.builder()
+                    .fileIds(Arrays.asList(fileId1))
+                    .getUrl(false)
+                    .build();
+            
+            List<File> singleFileResult = service.listFiles(singleFileRequest);
+            assertNotNull(singleFileResult);
+            assertEquals(1, singleFileResult.size());
+            assertEquals(fileId1, singleFileResult.get(0).getId());
+            
+        } finally {
+            // 清理测试文件
+            service.deleteFile(fileId1);
+            service.deleteFile(fileId2);
+        }
+    }
 }