> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 上传文件

上传一个文件到文件服务

## 请求地址

`POST https://api.stepfun.com/v1/files`

## 请求体

* `purpose` `string` ***required***\
  文件上传的意图，支持 `file-extract` 、 `retrieval-text` 、`retrieval-image` 和 `storage` 等四种类型；
  * `file-extract`: 用于提取文件内容
  * `retrieval-text` 用于文本知识库
  * `retrieval-image` 用于图片知识库
  * `storage` 用于图片理解、视频理解、音色复刻等功能。

* `url` `string` ***optional***\
   远程文件的 URL ，支持 文件格式等同于 file 字段支持的文件格式；同时传 file 和 url 字段，取 file 字段内容。

* `file` `File` ***optional***\
  用于上传的文件。限制单个用户上传文件 1000 个；当传入 url 时，可不传入此字段。\

  `file-extract` 和 `retrieval-text` 支持的文件格式,文件大小限制为 64M；

  * 纯文本（.txt,.md）
  * PDF(.pdf)
  * Word（doc,docx）
  * Excel（xls,xlsx）
  * PPT(ppt,pptx)
  * CSV(.csv)
  * HTML/XML(.html,.htm,.xml)

  `storage` 支持的文件格式,文件大小限制为 128M；

  * 视频（mp4）
  * 图片（jpg/jpeg、png、webp、静态 gif）
  * 音频文件（mp3、wav），用于音色复刻时，音频时长为 5\~10 秒。

  `retrieval-image` 支持的文件格式,文件大小限制为 64M；

  * 图片（jpg、png）

## 请求响应

返回单个[File 对象](https://platform.stepfun.com/docs/zh/api-reference/files/object.md)

## 示例

> [tab] python
>
> ```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> from openai import OpenAI
>
> client = OpenAI(api_key="YOUR_STEP_API_KEY", base_url="https://api.stepfun.com/v1")
>
> client.files.create(
>     file=open("salesOverview.pdf", "rb"),
>     purpose="file-extract"
> )
> ```

> [tab] js
>
> ```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> import OpenAI from "openai";
> import fs from "fs";
>
> const openai = new OpenAI({
>     apiKey: "YOUR_STEP_API_KEY",
>     baseURL: "https://api.stepfun.com/v1"
> });
>
> async function main() {
>     const file = await openai.files.create({
>         file: fs.createReadStream("salesOverview.pdf"),
>         purpose: "file-extract"
>     });
>
>     console.log(file);
> }
>
> main();
> ```

> [tab] curl
>
> ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> curl https://api.stepfun.com/v1/files \
>   -H "Authorization: Bearer $STEP_API_KEY" \
>   -F purpose="file-extract" \
>   -F file="@salesOverview.pdf"
> ```

```json filename="返回" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "id": "file-abc123",
  "object": "file",
  "bytes": 140,
  "created_at": 1613779121,
  "filename": "salesOverview.pdf",
  "purpose": "file-extract",
  "status": "processed"
}
```

## 备注

* 原 `purpose` 为 `retrieval`，现已废弃，建议使用 `retrieval-text` 替代。`retrieval` 将于 2025 年 5 月 15 日下线。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.