AI 助理
备案控制台登录注册
官方文档
输入文档关键字查找
首页大模型服务平台百炼API参考（模型）工具包/框架OpenAI兼容-File

OpenAI文件接口兼容

更新时间：2025-04-29 05:08:51
产品详情
我的收藏

当您使用qwen-long模型分析文档，或使用OpenAI兼容-Batch推理服务时，需要使用OpenAI文件兼容接口来获取file_id。本文为您介绍OpenAI文件兼容接口的使用方法与参数。

前提条件

  • 请开通阿里云百炼服务并获得API-KEY：获取API Key。

  • 如果您通过OpenAI Python/Java SDK使用，请参考安装OpenAI SDK完成OpenAI SDK的安装。

  • 我们推荐您将API-KEY配置到环境变量中以降低API-KEY的泄露风险，配置方法可参考配置API Key到环境变量。

功能描述

上传文件

当您使用qwen-long模型分析文档，或使用Batch推理服务时，需要使用上传文件接口获取file_id，通过purpose参数指定上传文件的用途。您可以上传Batch任务的单个文件最大为500 MB；当前阿里云账号下的百炼存储空间支持的最大文件数为10000个，文件总量不超过100 GB，文件暂时没有有效期。

用于文档分析
用于Batch调用

您需要将purpose指定为file-extract。文件格式支持文本文件（ TXT、DOCX、PDF、XLSX、EPUB、MOBI、MD、CSV），图片文件（BMP、PNG、JPG/JPEG、GIF和PDF扫描件）。

关于通过file_id进行文档分析，请参考长上下文。

请求示例

Python
Java
curl
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

# test.txt 是一个本地示例文件
file_object = client.files.create(file=Path("test.txt"), purpose="file-extract")

print(file_object.model_dump_json())
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileCreateParams;
import com.openai.models.FileObject;
import com.openai.models.FilePurpose;

import java.nio.file.Path;
import java.nio.file.Paths;

public class Main {
    public static void main(String[] args) {
        // 创建客户端，使用环境变量中的API密钥
        OpenAIClient client = OpenAIOkHttpClient.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
                .build();
        // 设置文件路径,请根据实际需求修改路径与文件名
        Path filePath = Paths.get("src/main/java/org/example/test.txt");
        // 创建文件上传参数
        FileCreateParams params = FileCreateParams.builder()
                .file(filePath)
                .purpose(FilePurpose.of("file-extract"))
                .build();

        // 上传文件
        FileObject fileObject = client.files().create(params);
        System.out.println(fileObject);
    }
}
curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
--form 'file=@"test.txt"' \
--form 'purpose="file-extract"'

响应示例

{
    "id": "file-fe-xxx",
    "bytes": 2055,
    "created_at": 1729065448,
    "filename": "test.txt",
    "object": "file",
    "purpose": "file-extract",
    "status": "processed",
    "status_details": null
}

您需要将purpose指定为batch。输入文件必须是jsonl文件，且符合输入文件格式。

关于Batch调用的更多用法，请参考OpenAI兼容-Batch。

请求示例

Python
Java
curl
import os
from pathlib import Path
from openai import OpenAI


client = OpenAI(
    # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

# test.jsonl 是一个本地示例文件
file_object = client.files.create(file=Path("test.jsonl"), purpose="batch")

print(file_object.model_dump_json())
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileCreateParams;
import com.openai.models.FileObject;
import com.openai.models.FilePurpose;

import java.nio.file.Path;
import java.nio.file.Paths;

public class Main {
    public static void main(String[] args) {
        // 创建客户端，使用环境变量中的API密钥
        OpenAIClient client = OpenAIOkHttpClient.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
                .build();
        // 设置文件路径,请根据实际需求修改路径与文件名
        Path filePath = Paths.get("src/main/java/org/example/test.txt");
        // 创建文件上传参数
        FileCreateParams params = FileCreateParams.builder()
                .file(filePath)
                .purpose(FilePurpose.of("batch"))
                .build();

        // 上传文件
        FileObject fileObject = client.files().create(params);
        System.out.println(fileObject);
    }
}
curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
--form 'file=@"test.jsonl"' \
--form 'purpose="batch"'

响应示例

{
    "id": "file-batch-xxx",
    "bytes": 231,
    "created_at": 1729065815,
    "filename": "test.jsonl",
    "object": "file",
    "purpose": "batch",
    "status": "processed",
    "status_details": null
}

输入参数

输入参数与OpenAI的接口参数对齐，参数说明和可选值如下。

参数

类型

必选

说明

参数

类型

必选

说明

file

File

是

用于指定待上传的文件。

purpose

string

是

用于指定上传文件的用途，当前可选值如下：

file-extract: 用于qwen-long模型的文档理解；

batch: 用于OpenAI兼容-Batch任务，file格式必须满足输入文件格式。

返回参数

字段

类型

描述

示例值

字段

类型

描述

示例值

id

string

文件的标识符。

"file-fe-123"

bytes

integer

文件大小，单位为字节。

123

created_at

integer

文件创建时的 Unix 时间戳（秒）。

1617981067

filename

string

上传的文件名。

"mydata.jsonl"

object

string

对象类型，始终为"file"。

"file"

purpose

string

与输入参数中的purpose保持一致。

"batch"

status

string

文件的当前状态。

"processed"

查询文件信息

您可以输入file_id来查询指定文件的信息。

OpenAI Python SDK
OpenAI Java SDK
HTTP

您可以通过在retrieve方法中指定file_id来查询文件信息。

请求示例

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

file = client.files.retrieve(file_id="file-fe-xxx")

print(file.model_dump_json())

返回示例

{
  "id": "file-fe-xxx",
  "bytes": 27,
  "created_at": 1722480306,
  "filename": "test.txt",
  "object": "file",
  "purpose": "file-extract",
  "status": "processed",
  "status_details": null
}

您可以通过在retrieve方法中传入FileRetrieveParams类来查询文件信息。

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileObject;
import com.openai.models.FileRetrieveParams;

public class Main {
    public static void main(String[] args) {
        // 创建客户端，使用环境变量中的API密钥
        OpenAIClient client = OpenAIOkHttpClient.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
                .build();
        // 创建文件查询参数,请根据实际需求替换相应的fileId
        FileRetrieveParams params= FileRetrieveParams.builder()
                .fileId("file-fe-xxx")
                .build();
        //查询文件
        FileObject fileObject = client.files().retrieve(params);
        System.out.println(fileObject);
    }
}

您可以通过GET方法，在URL中指定file_id来查询文件信息。

需要配置的endpoint

GET https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file_id}

请求示例

curl -X GET https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-fe-xxx \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

返回示例

{
    "id": "file-fe-xxx",
    "object": "file",
    "bytes": 499719,
    "created_at": 1715935833,
    "filename": "test.txt",
    "purpose": "file-extract",
    "status": "processed"
}

输入参数

参数

类型

必选

说明

参数

类型

必选

说明

file_id

string

是

待查询的文件id。

返回参数

字段

类型

描述

示例值

字段

类型

描述

示例值

id

string

文件标识符。

"file-fe-123"

bytes

integer

文件大小，单位为字节。

123456

created_at

integer

文件创建时的 Unix 时间戳（秒）。

1617981067

filename

string

文件名。

"mydata.jsonl"

object

string

对象类型，始终为 file。

"file"

purpose

string

文件的用途，有batch、file-extract、batch_output三种取值。

"batch"

查询文件列表

查询文件列表接口会返回您所有文件的信息，包括通过上传文件接口上传的文件，以及batch任务的结果文件。

OpenAI Python SDK
OpenAI Java SDK
HTTP

您可以通过list方法，查询您所有文件的信息。

查询文件列表接口无请求参数。

请求示例

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

file_stk = client.files.list(after="file-fe-xxx",limit=20)
print(file_stk.model_dump_json())

返回示例

{
  "data": [
    {
      "id": "file-fe-xxx",
      "bytes": 27,
      "created_at": 1722480543,
      "filename": "test.txt",
      "object": "file",
      "purpose": "file-extract",
      "status": "processed",
      "status_details": null
    },
    {
      "id": "file-fe-yyy",
      "bytes": 431986,
      "created_at": 1718089390,
      "filename": "test.pdf",
      "object": "file",
      "purpose": "file-extract",
      "status": "processed",
      "status_details": null
    }
  ],
  "object": "list",
  "has_more": false
}

您可以通过配置FileListParams参数，查询您所有文件的信息。

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileListPage;
import com.openai.models.FileListParams;

public class Main {
    public static void main(String[] args) {
        // 创建客户端，使用环境变量中的API密钥
        OpenAIClient client = OpenAIOkHttpClient.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
                .build();
        // 创建文件列表查询参数
        FileListParams params = FileListParams.builder()
                .after("file-fe-xxx")
                .limit(20)
                .build();
        //查询文件列表
        FileListPage file_stk = client.files().list(params);
        System.out.println(file_stk);
    }
}

您可以通过GET方法，查询您所有文件的信息。

查询文件列表接口无请求参数。

需要配置的endpoint

GET https://dashscope.aliyuncs.com/compatible-mode/v1/files

请求示例

curl -X GET https://dashscope.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

返回示例

{
    "object": "list",
    "has_more": true,
    "data": [
        {
            "id": "file-fe-xxx",
            "object": "file",
            "bytes": 84889,
            "created_at": 1715569225,
            "filename": "example.txt",
            "purpose": "file-extract",
            "status": "processed"
        },
        {
            "id": "file-fe-yyy",
            "object": "file",
            "bytes": 722355,
            "created_at": 1715413868,
            "filename": "Agent_survey.pdf",
            "purpose": "file-extract",
            "status": "processed"
        }
    ]
}

输入参数

字段

类型

传参方式

必选

描述

字段

类型

传参方式

必选

描述

after

String

Query

否

用于分页的游标，参数after的取值为当前分页的最后一个File ID，表示查询该ID之后下一页的数据。

例如，若本次查询返回了20条数据，且最后一个File ID是file-fe-xxx，则后续查询时可以设置after="file-fe-xxx"，以获取列表的下一页。

limit

Integer

Query

否

每次查询返回的文件数量，取值范围[1,2000]，默认2000。

返回参数

字段

类型

描述

字段

类型

描述

object

string

固定值为 “list”。

has_more

boolean

是否还有下一页数据。

data

array

返回的文件列表，列表中每个元素格式与返回参数一致。

下载Batch任务结果文件

在Batch推理任务结束后，您可以通过接口下载结果文件。

您可以通过查询文件列表或通过查询Batch任务列表返回参数中的output_file_id获取下载文件的file_id。仅支持下载以file-batch_output开头的file_id对应的文件。
OpenAI Python SDK
OpenAI Java SDK
HTTP

您可以通过content方法获取Batch任务结果文件内容，并通过write_to_file方法将其保存至本地。

请求示例

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
content = client.files.content(file_id="file-batch_output-xxx")
# 打印结果文件内容
print(content.text)
# 保存结果文件至本地
content.write_to_file("result.jsonl")

返回示例

{"id":"xxx","custom_id":"request-1","response":{"status_code":200,"request_id":"xxx","body":{"id":"xxx","object":"chat.completion","created":1729490866,"model":"qwen-turbo","choices":[{"finish_reason":"stop","index":0,"message":{"content":"2 + 2 equals 4."}}],"usage":{"completion_tokens":8,"prompt_tokens":36,"total_tokens":44},"system_fingerprint":null}},"error":null}
{"id":"yyy","custom_id":"request-2","response":{"status_code":200,"request_id":"yyy","body":{"id":"yyy","object":"chat.completion","created":1729490866,"model":"qwen-turbo","choices":[{"finish_reason":"stop","index":0,"message":{"content":"你好！有什么我可以帮你的吗？"}}],"usage":{"completion_tokens":8,"prompt_tokens":31,"total_tokens":39},"system_fingerprint":null}},"error":null}

您可以通过content方法传入FileContentParams类获取Batch任务结果文件内容，并将其保存至本地。

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.HttpResponse;
import com.openai.models.FileContentParams;

import java.io.*;

public class Main {
    public static void main(String[] args) throws IOException {
        // 创建客户端，使用环境变量中的API密钥
        OpenAIClient client = OpenAIOkHttpClient.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
                .build();
        // 创建文件获取请求参数
        FileContentParams params = FileContentParams.builder()
                .fileId("file-batch_output-xxx")
                .build();
        // 获取Batch任务结果内容
        try (HttpResponse response = client.files().content(params)) {
            java.nio.file.Files.copy(
                    response.body(),
                    java.nio.file.Paths.get("src/main/java/org/example/output.json"),
                    java.nio.file.StandardCopyOption.REPLACE_EXISTING
            );
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

您可以通过GET方法，在URL中指定file_id来下载Batch任务结果文件。

需要配置的endpoint

GET https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file_id}/content

请求示例

curl -X GET https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-batch_output-xxx/content \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" > result.jsonl

输入参数

字段

类型

传参方式

必选

描述

字段

类型

传参方式

必选

描述

file_id

string

Path

是

需要下载的文件的id

返回结果

Batch任务结果的jsonl文件，格式请参考输出文件格式。

删除文件

若您文件的个数或存储空间达到上限，可以通过删除文件接口删除指定file_id的文件。

可通过查询文件信息接口获取指定文件信息，或通过查询文件列表接口查询所有文件信息。

该接口限流为10 qps。
OpenAI Python SDK
OpenAI Java SDK
HTTP

您可以通过delete方法，传入file_id来删除指定文件。

请求示例

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

file_object = client.files.delete("file-fe-xxx")
print(file_object.model_dump_json())

返回示例

{
  "object": "file",
  "deleted": true,
  "id": "file-fe-xxx"
}

您可以通过delete方法，传入FileDeleteParams类来删除指定文件。

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.FileDeleteParams;
import com.openai.models.FileListPage;
import com.openai.models.FileListParams;

public class Main {
    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
                .build();
        FileDeleteParams params = FileDeleteParams.builder()
                .fileId("file-fe-xxx")
                .build();

        System.out.println(client.files().delete(params));
    }
}

您可以通过DELETE方法，在URL中指定file_id来删除指定文件。

需要配置的endpoint

DELETE https://dashscope.aliyuncs.com/compatible-mode/v1/files/{file_id}

请求示例

curl -X  DELETE https://dashscope.aliyuncs.com/compatible-mode/v1/files/file-fe-xxx \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"

返回示例

{
  "object": "file",
  "deleted": true,
  "id": "file-fe-oLIon7bzfxELqJBTS5okwC4E"
}

输入参数

参数

类型

必选

说明

参数

类型

必选

说明

file_id

string

是

待删除文件id。

返回参数

字段

类型

描述

字段

类型

描述

object

string

固定值为 “file”。

deleted

boolean

是否删除成功，true表示删除成功。

id

string

成功删除的文件的id。

上一篇：OpenAI兼容-Vision下一篇：OpenAI兼容-Batch
  • 本页导读 （1）
  • 前提条件
  • 功能描述
  • 上传文件
  • 查询文件信息
  • 查询文件列表
  • 下载Batch任务结果文件
  • 删除文件
AI助理

点击开启售前

在线咨询服务

你好，我是AI助理

可以解答问题、推荐解决方案等