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

# 文件

> 上传和管理用于API请求上下文的JSON文件

通过Olostep的`/v1/files`端点，你可以上传JSON文件，这些文件可以用作API请求中的上下文。这允许你提供结构化数据以增强抓取、回答和其他操作。

* 上传最大200MB的JSON文件
* 文件会自动验证为正确的JSON格式
* 在抓取、回答和其他端点中使用文件作为上下文
* 文件在30天后过期
* 安全的预签名URL上传过程

有关API详细信息，请参阅[文件端点API参考](/api-reference/files/create)。

## 安装

<CodeGroup>
  ```python Python theme={null}
  # pip install requests

  import requests
  ```

  ```js Node theme={null}
  // npm install node-fetch

  // ESM
  import fetch from 'node-fetch'

  // CommonJS
  const fetch = require('node-fetch')
  ```

  ```bash cURL theme={null}
  # macOS: 内置curl就可以
  ```
</CodeGroup>

## 上传文件

文件上传过程包括两个步骤：

1. **创建上传URL**：请求一个用于上传文件的预签名URL
2. **完成上传**：将文件上传到预签名URL，然后调用完成端点进行验证和最终化

### 步骤1：创建上传URL

首先，通过提供文件名和可选的目的来创建上传URL。`purpose`参数仅支持两个值：`"context"`（默认）或`"batch"`。

<CodeGroup>
  ```python Python theme={null}
  import requests
  import json

  API_KEY = "<YOUR_API_KEY>"
  API_URL = "https://api.olostep.com/v1"

  # 步骤1：创建上传URL
  payload = {
      "filename": "my-data.json",
      "purpose": "context"  # 可选，默认为"context"。支持的值："context"或"batch"
  }

  headers = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  response = requests.post(f"{API_URL}/files", headers=headers, json=payload)
  upload_data = response.json()

  print(json.dumps(upload_data, indent=2))
  # 响应包括：id, upload_url, expires_in
  ```

  ```js Node theme={null}
  const API_URL = 'https://api.olostep.com/v1'

  const res = await fetch(`${API_URL}/files`, {
    method: 'POST',
    headers: { 'Authorization': 'Bearer <YOUR_API_KEY>', 'Content-Type': 'application/json' },
    body: JSON.stringify({
      filename: 'my-data.json',
      purpose: 'context'  // 可选，默认为"context"。支持的值："context"或"batch"
    })
  })
  const uploadData = await res.json()
  console.log(uploadData)
  ```

  ```bash cURL theme={null}
  curl -s -X POST "https://api.olostep.com/v1/files" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "filename": "my-data.json",
      "purpose": "context"
    }'

  # 示例使用"batch"目的：
  curl -s -X POST "https://api.olostep.com/v1/files" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "filename": "batch-data.json",
      "purpose": "batch"
    }'
  ```
</CodeGroup>

响应包括一个在10分钟内过期的预签名`upload_url`：

```json theme={null}
{
  "id": "file_abc123xyz789",
  "object": "file.upload",
  "created": 1760329882,
  "upload_url": "https://olostep-files.s3.amazonaws.com/files/...",
  "expires_in": 600
}
```

### 步骤2：上传文件并完成

将你的JSON文件上传到预签名URL，然后调用完成端点进行验证和最终化上传。

<CodeGroup>
  ```python Python theme={null}
  import requests
  import json

  API_KEY = "<YOUR_API_KEY>"
  API_URL = "https://api.olostep.com/v1"

  # 从步骤1获取upload_url后
  file_id = upload_data["id"]
  upload_url = upload_data["upload_url"]

  # 准备你的JSON数据
  json_data = {
      "users": [
          {"name": "John Doe", "email": "john@example.com"},
          {"name": "Jane Smith", "email": "jane@example.com"}
      ]
  }

  # 步骤2a：将文件上传到预签名URL
  upload_response = requests.put(
      upload_url,
      data=json.dumps(json_data),
      headers={"Content-Type": "application/json"}
  )
  upload_response.raise_for_status()

  # 步骤2b：完成上传
  complete_response = requests.post(
      f"{API_URL}/files/{file_id}/complete",
      headers={"Authorization": f"Bearer {API_KEY}"}
  )
  file_info = complete_response.json()

  print(json.dumps(file_info, indent=2))
  ```

  ```js Node theme={null}
  const API_URL = 'https://api.olostep.com/v1'

  // 从步骤1获取upload_url后
  const fileId = uploadData.id
  const uploadUrl = uploadData.upload_url

  // 准备你的JSON数据
  const jsonData = {
    users: [
      { name: 'John Doe', email: 'john@example.com' },
      { name: 'Jane Smith', email: 'jane@example.com' }
    ]
  }

  // 步骤2a：将文件上传到预签名URL
  await fetch(uploadUrl, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(jsonData)
  })

  // 步骤2b：完成上传
  const completeRes = await fetch(`${API_URL}/files/${fileId}/complete`, {
    method: 'POST',
    headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
  })
  const fileInfo = await completeRes.json()
  console.log(fileInfo)
  ```

  ```bash cURL theme={null}
  # 步骤2a：将文件上传到预签名URL
  curl -X PUT "$UPLOAD_URL" \
    -H "Content-Type: application/json" \
    -d @my-data.json

  # 步骤2b：完成上传
  curl -s -X POST "https://api.olostep.com/v1/files/$FILE_ID/complete" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY"
  ```
</CodeGroup>

完成端点验证JSON文件并返回文件元数据：

```json theme={null}
{
  "id": "file_abc123xyz789",
  "object": "file",
  "created": 1760329882,
  "filename": "my-data.json",
  "bytes": 1024,
  "purpose": "context",
  "status": "completed"
}
```

## 通过ID检索文件元数据

通过文件ID检索文件的元数据。

<CodeGroup>
  ```python Python theme={null}
  file_id = "file_abc123xyz789"
  response = requests.get(
      f"{API_URL}/files/{file_id}",
      headers={"Authorization": f"Bearer {API_KEY}"}
  )
  file_info = response.json()
  print(json.dumps(file_info, indent=2))
  ```

  ```js Node theme={null}
  const fileId = 'file_abc123xyz789'
  const res = await fetch(`${API_URL}/files/${fileId}`, {
    headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
  })
  const fileInfo = await res.json()
  console.log(fileInfo)
  ```

  ```bash cURL theme={null}
  curl -s -X GET "https://api.olostep.com/v1/files/$FILE_ID" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY"
  ```
</CodeGroup>

## 通过ID检索文件对象

获取一个预签名URL来下载已完成文件的JSON内容。可以选择使用`expires_in`查询参数指定下载URL的过期时间（默认为600秒/10分钟）。

<CodeGroup>
  ```python Python theme={null}
  file_id = "file_abc123xyz789"
  # 获取下载URL（默认过期时间：600秒）
  response = requests.get(
      f"{API_URL}/files/{file_id}/content",
      headers={"Authorization": f"Bearer {API_KEY}"}
  )
  download_info = response.json()
  download_url = download_info["download_url"]

  # 使用预签名URL下载文件内容
  file_response = requests.get(download_url)
  file_content = file_response.json()
  print(json.dumps(file_content, indent=2))

  # 示例使用自定义过期时间（3600秒=1小时）
  response = requests.get(
      f"{API_URL}/files/{file_id}/content?expires_in=3600",
      headers={"Authorization": f"Bearer {API_KEY}"}
  )
  download_info = response.json()
  print(f"下载URL将在: {download_info['expires_in']}秒后过期")
  ```

  ```js Node theme={null}
  const fileId = 'file_abc123xyz789'

  // 获取下载URL（默认过期时间：600秒）
  const res = await fetch(`${API_URL}/files/${fileId}/content`, {
    headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
  })
  const downloadInfo = await res.json()
  const downloadUrl = downloadInfo.download_url

  // 使用预签名URL下载文件内容
  const fileRes = await fetch(downloadUrl)
  const fileContent = await fileRes.json()
  console.log(fileContent)

  // 示例使用自定义过期时间（3600秒=1小时）
  const customRes = await fetch(`${API_URL}/files/${fileId}/content?expires_in=3600`, {
    headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
  })
  const customDownloadInfo = await customRes.json()
  console.log(`下载URL将在: ${customDownloadInfo.expires_in}秒后过期`)
  ```

  ```bash cURL theme={null}
  # 获取下载URL（默认过期时间：600秒）
  curl -s -X GET "https://api.olostep.com/v1/files/$FILE_ID/content" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY"

  # 获取自定义过期时间的下载URL（3600秒=1小时）
  curl -s -X GET "https://api.olostep.com/v1/files/$FILE_ID/content?expires_in=3600" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY"

  # 使用预签名URL下载文件
  curl -s "$DOWNLOAD_URL"
  ```
</CodeGroup>

响应包括一个在指定时间后过期的预签名`download_url`：

```json theme={null}
{
  "id": "file_abc123xyz789",
  "object": "file",
  "created": 1760329882,
  "filename": "my-data.json",
  "bytes": 1024,
  "download_url": "https://olostep-files.s3.amazonaws.com/files/...",
  "expires_in": 600
}
```

## 列出文件

列出团队的所有已完成文件。可以选择按目的过滤（支持的值：`"context"`或`"batch"`）。

<CodeGroup>
  ```python Python theme={null}
  # 列出所有文件
  response = requests.get(
      f"{API_URL}/files",
      headers={"Authorization": f"Bearer {API_KEY}"}
  )
  files = response.json()
  print(json.dumps(files, indent=2))

  # 按目的过滤文件
  response = requests.get(
      f"{API_URL}/files?purpose=context",
      headers={"Authorization": f"Bearer {API_KEY}"}
  )
  context_files = response.json()
  print(json.dumps(context_files, indent=2))
  ```

  ```js Node theme={null}
  // 列出所有文件
  const res = await fetch(`${API_URL}/files`, {
    headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
  })
  const files = await res.json()
  console.log(files)

  // 按目的过滤文件
  const contextRes = await fetch(`${API_URL}/files?purpose=context`, {
    headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
  })
  const contextFiles = await contextRes.json()
  console.log(contextFiles)
  ```

  ```bash cURL theme={null}
  # 列出所有文件
  curl -s -X GET "https://api.olostep.com/v1/files" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY"

  # 按目的过滤文件
  curl -s -X GET "https://api.olostep.com/v1/files?purpose=context" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY"
  ```
</CodeGroup>

响应包括一个文件列表：

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "file_abc123xyz789",
      "object": "file",
      "created": 1760329882,
      "filename": "my-data.json",
      "bytes": 1024,
      "purpose": "context",
      "status": "completed"
    }
  ]
}
```

## 删除文件

删除文件及其相关数据。

<CodeGroup>
  ```python Python theme={null}
  file_id = "file_abc123xyz789"
  response = requests.delete(
      f"{API_URL}/files/{file_id}",
      headers={"Authorization": f"Bearer {API_KEY}"}
  )
  result = response.json()
  print(json.dumps(result, indent=2))
  ```

  ```js Node theme={null}
  const fileId = 'file_abc123xyz789'
  const res = await fetch(`${API_URL}/files/${fileId}`, {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
  })
  const result = await res.json()
  console.log(result)
  ```

  ```bash cURL theme={null}
  curl -s -X DELETE "https://api.olostep.com/v1/files/$FILE_ID" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY"
  ```
</CodeGroup>

## 完整上传示例（context目的）

这是一个完整示例，上传一个`purpose="context"`的JSON文件：

<CodeGroup>
  ```python Python theme={null}
  import requests
  import json

  API_KEY = "<YOUR_API_KEY>"
  API_URL = "https://api.olostep.com/v1"

  # 步骤1：创建上传URL
  create_response = requests.post(
      f"{API_URL}/files",
      headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
      json={"filename": "user-data.json", "purpose": "context"}
  )
  upload_data = create_response.json()
  file_id = upload_data["id"]
  upload_url = upload_data["upload_url"]

  # 步骤2：准备并上传JSON数据
  json_data = {
      "users": [
          {"id": 1, "name": "Alice", "role": "admin"},
          {"id": 2, "name": "Bob", "role": "user"}
      ]
  }

  upload_response = requests.put(
      upload_url,
      data=json.dumps(json_data),
      headers={"Content-Type": "application/json"}
  )
  upload_response.raise_for_status()

  # 步骤3：完成上传
  complete_response = requests.post(
      f"{API_URL}/files/{file_id}/complete",
      headers={"Authorization": f"Bearer {API_KEY}"}
  )
  file_info = complete_response.json()

  print(f"文件上传成功: {file_info['id']}")
  print(f"文件大小: {file_info['bytes']} 字节")
  ```

  ```js Node theme={null}
  const API_URL = 'https://api.olostep.com/v1'

  // 步骤1：创建上传URL
  const createRes = await fetch(`${API_URL}/files`, {
    method: 'POST',
    headers: { 'Authorization': 'Bearer <YOUR_API_KEY>', 'Content-Type': 'application/json' },
    body: JSON.stringify({ filename: 'user-data.json', purpose: 'context' })
  })
  const uploadData = await createRes.json()
  const fileId = uploadData.id
  const uploadUrl = uploadData.upload_url

  // 步骤2：准备并上传JSON数据
  const jsonData = {
    users: [
      { id: 1, name: 'Alice', role: 'admin' },
      { id: 2, name: 'Bob', role: 'user' }
    ]
  }

  await fetch(uploadUrl, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(jsonData)
  })

  // 步骤3：完成上传
  const completeRes = await fetch(`${API_URL}/files/${fileId}/complete`, {
    method: 'POST',
    headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
  })
  const fileInfo = await completeRes.json()

  console.log(`文件上传成功: ${fileInfo.id}`)
  console.log(`文件大小: ${fileInfo.bytes} 字节`)
  ```
</CodeGroup>

## 上传批处理文件示例

这是一个上传`purpose="batch"`的JSON文件的示例，其中包含可以与`/v1/batches`端点一起使用的有效批处理数据：

<CodeGroup>
  ```python Python theme={null}
  import requests
  import json

  API_KEY = "<YOUR_API_KEY>"
  API_URL = "https://api.olostep.com/v1"

  # 步骤1：创建上传URL，目的为"batch"
  create_response = requests.post(
      f"{API_URL}/files",
      headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
      json={"filename": "batch-items.json", "purpose": "batch"}
  )
  upload_data = create_response.json()
  file_id = upload_data["id"]
  upload_url = upload_data["upload_url"]

  # 步骤2：准备批处理JSON数据（/v1/batches端点的有效格式）
  batch_data = {
      "items": [
          {"custom_id": "item-1", "url": "https://www.google.com/search?q=stripe&gl=us&hl=en"},
          {"custom_id": "item-2", "url": "https://www.google.com/search?q=paddle&gl=us&hl=en"},
          {"custom_id": "item-3", "url": "https://www.google.com/search?q=payment+gateway&gl=us&hl=en"}
      ],
      "parser": {"id": "@olostep/google-search"},
      "country": "US"
  }

  upload_response = requests.put(
      upload_url,
      data=json.dumps(batch_data),
      headers={"Content-Type": "application/json"}
  )
  upload_response.raise_for_status()

  # 步骤3：完成上传
  complete_response = requests.post(
      f"{API_URL}/files/{file_id}/complete",
      headers={"Authorization": f"Bearer {API_KEY}"}
  )
  file_info = complete_response.json()

  print(f"批处理文件上传成功: {file_info['id']}")
  print(f"文件大小: {file_info['bytes']} 字节")
  print(f"目的: {file_info['purpose']}")
  ```

  ```js Node theme={null}
  const API_URL = 'https://api.olostep.com/v1'

  // 步骤1：创建上传URL，目的为"batch"
  const createRes = await fetch(`${API_URL}/files`, {
    method: 'POST',
    headers: { 'Authorization': 'Bearer <YOUR_API_KEY>', 'Content-Type': 'application/json' },
    body: JSON.stringify({ filename: 'batch-items.json', purpose: 'batch' })
  })
  const uploadData = await createRes.json()
  const fileId = uploadData.id
  const uploadUrl = uploadData.upload_url

  // 步骤2：准备批处理JSON数据（/v1/batches端点的有效格式）
  const batchData = {
    items: [
      { custom_id: 'item-1', url: 'https://www.google.com/search?q=stripe&gl=us&hl=en' },
      { custom_id: 'item-2', url: 'https://www.google.com/search?q=paddle&gl=us&hl=en' },
      { custom_id: 'item-3', url: 'https://www.google.com/search?q=payment+gateway&gl=us&hl=en' }
    ],
    parser: { id: '@olostep/google-search' },
    country: 'US'
  }

  await fetch(uploadUrl, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(batchData)
  })

  // 步骤3：完成上传
  const completeRes = await fetch(`${API_URL}/files/${fileId}/complete`, {
    method: 'POST',
    headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
  })
  const fileInfo = await completeRes.json()

  console.log(`批处理文件上传成功: ${fileInfo.id}`)
  console.log(`文件大小: ${fileInfo.bytes} 字节`)
  console.log(`目的: ${fileInfo.purpose}`)
  ```

  ```bash cURL theme={null}
  # 步骤1：创建上传URL，目的为"batch"
  curl -s -X POST "https://api.olostep.com/v1/files" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "filename": "batch-items.json",
      "purpose": "batch"
    }'

  # 步骤2：上传批处理JSON数据（先保存到batch-items.json）
  # batch-items.json内容：
  # {
  #   "items": [
  #     {"custom_id": "item-1", "url": "https://www.google.com/search?q=stripe&gl=us&hl=en"},
  #     {"custom_id": "item-2", "url": "https://www.google.com/search?q=paddle&gl=us&hl=en"},
  #     {"custom_id": "item-3", "url": "https://www.google.com/search?q=payment+gateway&gl=us&hl=en"}
  #   ],
  #   "parser": {"id": "@olostep/google-search"},
  #   "country": "US"
  # }

  curl -X PUT "$UPLOAD_URL" \
    -H "Content-Type: application/json" \
    -d @batch-items.json

  # 步骤3：完成上传
  curl -s -X POST "https://api.olostep.com/v1/files/$FILE_ID/complete" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY"
  ```
</CodeGroup>

上传的批处理文件包含与`/v1/batches`端点格式匹配的有效JSON结构：

* `items`：包含`custom_id`和`url`字段的对象数组
* `parser`：可选的解析器配置
* `country`：可选的国家代码

此文件可用作批处理操作的输入。

## 文件要求

* **文件格式**：仅支持JSON文件（需要`.json`扩展名）
* **文件大小**：每个文件最大200MB
* **过期时间**：文件在30天后过期
* **上传URL**：预签名URL在10分钟后过期
* **目的参数**：仅支持`"context"`或`"batch"`值（默认为`"context"`）

## 价格

文件上传是免费的。文件被安全存储，并在30天后自动过期。