OpenAI API参考文档 | OpenAI开发文档|OpenAI中文官方文档|ChatGPT中文版|ChatGPT教程

Files

Files are used to upload documents that can be used with features like Assistants, Fine-tuning, and Batch API.source

Upload file

post https://api.openai.com/v1/files

Upload a file that can be used across various endpoints. Individual files can be up to 512 MB, and the size of all files uploaded by one organization can be up to 100 GB.source

The Assistants API supports files up to 2 million tokens and of specific file types. See the Assistants Tools guide for details.source

The Fine-tuning API only supports .jsonl files. The input also has certain required formats for fine-tuning chat or completions models.source

The Batch API only supports .jsonl files up to 200 MB in size. The input also has a specific required format.source

Please contact us if you need to increase these storage limits.source

Request body

file

filesource

Required

The File object (not file name) to be uploaded.source

purpose

stringsource

Required

The intended purpose of the uploaded file.source

Use "assistants" for Assistants and Message files, "vision" for Assistants image file inputs, "batch" for Batch API, and "fine-tune" for Fine-tuning.source

Returns

The uploaded File object.source

Example request

1
2
3
4
curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="fine-tune" \
  -F file="@mydata.jsonl"

1
2
3
4
5
6
7
from openai import OpenAI
client = OpenAI()

client.files.create(
  file=open("mydata.jsonl", "rb"),
  purpose="fine-tune"
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import fs from "fs";
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const file = await openai.files.create({
    file: fs.createReadStream("mydata.jsonl"),
    purpose: "fine-tune",
  });

  console.log(file);
}

main();

Response

1
2
3
4
5
6
7
8
{
  "id": "file-abc123",
  "object": "file",
  "bytes": 120000,
  "created_at": 1677610602,
  "filename": "mydata.jsonl",
  "purpose": "fine-tune",
}

List files

get https://api.openai.com/v1/files

Returns a list of files.source

Query parameters

purpose

stringsource

Optional

Only return files with the given purpose.source

limit

integersource

Optional

Defaults to 10000

A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.source

order

stringsource

Optional

Defaults to desc

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.source

after

stringsource

Optional

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.source

Returns

A list of File objects.source

Example request

1
2
curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.files.list()

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const list = await openai.files.list();

  for await (const file of list) {
    console.log(file);
  }
}

main();

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "data": [
    {
      "id": "file-abc123",
      "object": "file",
      "bytes": 175,
      "created_at": 1613677385,
      "filename": "salesOverview.pdf",
      "purpose": "assistants",
    },
    {
      "id": "file-abc123",
      "object": "file",
      "bytes": 140,
      "created_at": 1613779121,
      "filename": "puppy.jsonl",
      "purpose": "fine-tune",
    }
  ],
  "object": "list"
}

Retrieve file

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

Returns information about a specific file.source

Path parameters

file_id

stringsource

Required

The ID of the file to use for this request.source

Returns

The File object matching the specified ID.source

Example request

1
2
curl https://api.openai.com/v1/files/file-abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.files.retrieve("file-abc123")

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const file = await openai.files.retrieve("file-abc123");

  console.log(file);
}

main();

Response

1
2
3
4
5
6
7
8
{
  "id": "file-abc123",
  "object": "file",
  "bytes": 120000,
  "created_at": 1677610602,
  "filename": "mydata.jsonl",
  "purpose": "fine-tune",
}

Delete file

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

Delete a file.source

Path parameters

file_id

stringsource

Required

The ID of the file to use for this request.source

Returns

Deletion status.source

Example request

1
2
3
curl https://api.openai.com/v1/files/file-abc123 \
  -X DELETE \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.files.delete("file-abc123")

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const file = await openai.files.del("file-abc123");

  console.log(file);
}

main();

Response

1
2
3
4
5
{
  "id": "file-abc123",
  "object": "file",
  "deleted": true
}

Retrieve file content

get https://api.openai.com/v1/files/{file_id}/content

Returns the contents of the specified file.source

Path parameters

file_id

stringsource

Required

The ID of the file to use for this request.source

Returns

The file content.source

Example request

1
2
curl https://api.openai.com/v1/files/file-abc123/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > file.jsonl

1
2
3
4
from openai import OpenAI
client = OpenAI()

content = client.files.content("file-abc123")

1
2
3
4
5
6
7
8
9
10
11
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const file = await openai.files.content("file-abc123");

  console.log(file);
}

main();

The file object

The File object represents a document that has been uploaded to OpenAI.source

stringsource

The file identifier, which can be referenced in the API endpoints.source

bytes

integersource

The size of the file, in bytes.source

created_at

integersource

The Unix timestamp (in seconds) for when the file was created.source

filename

stringsource

The name of the file.source

object

stringsource

The object type, which is always file.source

purpose

stringsource

The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results and vision.source

status

Deprecated

stringsource

Deprecated. The current status of the file, which can be either uploaded, processed, or error.source

status_details

Deprecated

stringsource

Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.source

OBJECT The file object

1
2
3
4
5
6
7
8
{
  "id": "file-abc123",
  "object": "file",
  "bytes": 120000,
  "created_at": 1677610602,
  "filename": "salesOverview.pdf",
  "purpose": "assistants",
}