文件 - Olostep Docs

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

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

有关API详细信息，请参阅文件端点API参考。

安装

# pip install requests

import requests

// npm install node-fetch

// ESM
import fetch from 'node-fetch'

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

# macOS: 内置curl就可以

上传文件

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

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

步骤1：创建上传URL

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

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

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)

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"
  }'

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

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

步骤2：上传文件并完成

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

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))

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)

# 步骤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"

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

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

通过ID检索文件元数据

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

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))

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)

curl -s -X GET "https://api.olostep.com/v1/files/$FILE_ID" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY"

通过ID检索文件对象

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

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']}秒后过期")

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}秒后过期`)

# 获取下载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"

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

{
  "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"）。

# 列出所有文件
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))

// 列出所有文件
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)

# 列出所有文件
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"

响应包括一个文件列表：

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

删除文件

删除文件及其相关数据。

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))

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)

curl -s -X DELETE "https://api.olostep.com/v1/files/$FILE_ID" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY"

完整上传示例（context目的）

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

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']} 字节")

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} 字节`)

上传批处理文件示例

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

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']}")

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}`)

# 步骤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"

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

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

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

文件要求

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

价格

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

开始使用

功能

余额与账单

文件

安装

上传文件

步骤1：创建上传URL

步骤2：上传文件并完成

通过ID检索文件元数据

通过ID检索文件对象

列出文件

删除文件

完整上传示例（context目的）

上传批处理文件示例

文件要求

价格

​安装

​上传文件

​步骤1：创建上传URL

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

​通过ID检索文件元数据

​通过ID检索文件对象

​列出文件

​删除文件

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

​上传批处理文件示例

​文件要求

​价格

安装

上传文件

步骤1：创建上传URL

步骤2：上传文件并完成

通过ID检索文件元数据

通过ID检索文件对象

列出文件

删除文件

完整上传示例（context目的）

上传批处理文件示例

文件要求

价格