跳转到主要内容

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.

通过Olostep的/v1/files端点，你可以上传JSON文件，这些文件可以用作API请求中的上下文。这允许你提供结构化数据以增强抓取、回答和其他操作。
  • 上传最大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
响应包括一个在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))
完成端点验证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_id和url字段的对象数组
  • parser：可选的解析器配置
  • country：可选的国家代码
此文件可用作批处理操作的输入。

​
文件要求

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

​
价格

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