Saltar al contenido principal
A través del endpoint /v1/files de Olostep puedes subir archivos JSON que se pueden utilizar como contexto en tus solicitudes de API. Esto te permite proporcionar datos estructurados para mejorar tus scrapes, respuestas y otras operaciones.
  • Sube archivos JSON de hasta 200MB
  • Los archivos se validan automáticamente para asegurar el formato JSON correcto
  • Usa archivos como contexto en scrapes, respuestas y otros endpoints
  • Los archivos expiran después de 30 días
  • Proceso de subida seguro con URL pre-firmada
Para detalles de la API, consulta la Referencia de la API del Endpoint de Archivos.

​
Instalación

# pip install requests

import requests

​
Subir un archivo

El proceso de subida de archivos consta de dos pasos:
  1. Crear URL de subida: Solicita una URL pre-firmada para subir tu archivo
  2. Completar subida: Sube tu archivo a la URL pre-firmada, luego llama al endpoint de completar para validar y finalizar

​
Paso 1: Crear URL de subida

Primero, crea una URL de subida proporcionando el nombre del archivo y un propósito opcional. El parámetro purpose solo admite dos valores: "context" (predeterminado) o "batch". 
import requests
import json

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

# Paso 1: Crear URL de subida
payload = {
    "filename": "my-data.json",
    "purpose": "context"  # Opcional, por defecto es "context". Valores soportados: "context" o "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))
# La respuesta incluye: id, upload_url, expires_in
La respuesta incluye una upload_url pre-firmada que expira en 10 minutos: 
{
  "id": "file_abc123xyz789",
  "object": "file.upload",
  "created": 1760329882,
  "upload_url": "https://olostep-files.s3.amazonaws.com/files/...",
  "expires_in": 600
}

​
Paso 2: Subir archivo y completar

Sube tu archivo JSON a la URL pre-firmada, luego llama al endpoint de completar para validar y finalizar la subida. 
import requests
import json

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

# Después de obtener upload_url del Paso 1
file_id = upload_data["id"]
upload_url = upload_data["upload_url"]

# Prepara tus datos JSON
json_data = {
    "users": [
        {"name": "John Doe", "email": "john@example.com"},
        {"name": "Jane Smith", "email": "jane@example.com"}
    ]
}

# Paso 2a: Subir archivo a URL pre-firmada
upload_response = requests.put(
    upload_url,
    data=json.dumps(json_data),
    headers={"Content-Type": "application/json"}
)
upload_response.raise_for_status()

# Paso 2b: Completar la subida
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))
El endpoint de completar valida el archivo JSON y devuelve los metadatos del archivo: 
{
  "id": "file_abc123xyz789",
  "object": "file",
  "created": 1760329882,
  "filename": "my-data.json",
  "bytes": 1024,
  "purpose": "context",
  "status": "completed"
}

​
Recuperar metadatos de archivo por ID

Recupera los metadatos de un archivo por su 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))

​
Recuperar objeto de archivo por ID

Obtén una URL pre-firmada para descargar el contenido JSON de un archivo completado. Opcionalmente, especifica el tiempo de expiración para la URL de descarga usando el parámetro de consulta expires_in (por defecto 600 segundos / 10 minutos). 
file_id = "file_abc123xyz789"
# Obtener URL de descarga (expiración por defecto: 600 segundos)
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"]

# Descargar el contenido del archivo usando la URL pre-firmada
file_response = requests.get(download_url)
file_content = file_response.json()
print(json.dumps(file_content, indent=2))

# Ejemplo con expiración personalizada (3600 segundos = 1 hora)
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"Download URL expires in: {download_info['expires_in']} seconds")
La respuesta incluye una download_url pre-firmada que expira después del tiempo especificado: 
{
  "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
}

​
Listar archivos

Lista todos los archivos completados para tu equipo. Opcionalmente, filtra por propósito (valores soportados: "context" o "batch"). 
# Listar todos los archivos
response = requests.get(
    f"{API_URL}/files",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
files = response.json()
print(json.dumps(files, indent=2))

# Listar archivos filtrados por propósito
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))
La respuesta incluye una lista de archivos: 
{
  "object": "list",
  "data": [
    {
      "id": "file_abc123xyz789",
      "object": "file",
      "created": 1760329882,
      "filename": "my-data.json",
      "bytes": 1024,
      "purpose": "context",
      "status": "completed"
    }
  ]
}

​
Eliminar un archivo

Elimina un archivo y sus datos asociados del almacenamiento. 
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))

​
Ejemplo de subida completa (propósito de contexto)

Aquí tienes un ejemplo completo que sube un archivo JSON con purpose="context": 
import requests
import json

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

# Paso 1: Crear URL de subida
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"]

# Paso 2: Preparar y subir datos 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()

# Paso 3: Completar la subida
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 uploaded successfully: {file_info['id']}")
print(f"File size: {file_info['bytes']} bytes")

​
Ejemplo de subida de archivo batch

Aquí tienes un ejemplo que sube un archivo JSON con purpose="batch" que contiene datos batch válidos que se pueden usar con el endpoint /v1/batches: 
import requests
import json

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

# Paso 1: Crear URL de subida con purpose="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"]

# Paso 2: Preparar datos JSON batch (formato válido para el endpoint /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()

# Paso 3: Completar la subida
complete_response = requests.post(
    f"{API_URL}/files/{file_id}/complete",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
file_info = complete_response.json()

print(f"Batch file uploaded successfully: {file_info['id']}")
print(f"File size: {file_info['bytes']} bytes")
print(f"Purpose: {file_info['purpose']}")
El archivo batch subido contiene una estructura JSON válida que coincide con el formato del endpoint /v1/batches:
  • items: Array de objetos con campos custom_id y url
  • parser: Configuración opcional del parser
  • country: Código de país opcional
Este archivo se puede usar como entrada para operaciones de procesamiento batch.

​
Requisitos de archivo

  • Formato de archivo: Solo se admiten archivos JSON (se requiere extensión .json)
  • Tamaño de archivo: Máximo 200MB por archivo
  • Expiración: Los archivos expiran después de 30 días
  • URL de subida: Las URLs pre-firmadas expiran después de 10 minutos
  • Parámetro de propósito: Solo admite valores "context" o "batch" (por defecto es "context")

​
Precios

Las subidas de archivos son gratuitas. Los archivos se almacenan de forma segura y expiran automáticamente después de 30 días.