跳转到主要内容
通过Olostep的/v1/files端点,您可以上传可用作API请求上下文的JSON文件。这使您能够提供结构化数据以增强您的抓取、回答和其他操作。
  • 上传最大200MB的JSON文件
  • 文件会自动验证为正确的JSON格式
  • 在抓取、回答和其他端点中使用文件作为上下文
  • 文件在30天后过期
  • 安全的预签名URL上传过程
有关API详细信息,请参阅文件端点API参考

安装

# pip install requests

import requests

上传文件

文件上传过程分为两个步骤:
  1. 创建上传URL:请求用于上传文件的预签名URL
  2. 完成上传:将文件上传到预签名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
响应包括一个预签名的upload_url,有效期为10分钟:
{
  "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))
完成端点验证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))

通过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']}秒后过期")
响应包括一个预签名的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))
响应包括一个文件列表:
{
  "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))

完整上传示例(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']} 字节")

上传批处理文件示例

这是一个上传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']}")
上传的批处理文件包含与/v1/batches端点格式匹配的有效JSON结构:
  • items:包含custom_idurl字段的对象数组
  • parser:可选的解析器配置
  • country:可选的国家代码
此文件可用作批处理操作的输入。

文件要求

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

价格

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