Passer au contenu principal
Grâce à l’endpoint Olostep /v1/files, tu peux télécharger des fichiers JSON qui peuvent être utilisés comme contexte dans tes requêtes API. Cela te permet de fournir des données structurées pour améliorer tes extractions, réponses et autres opérations.
  • Télécharge des fichiers JSON jusqu’à 200 Mo
  • Les fichiers sont automatiquement validés pour un format JSON correct
  • Utilise les fichiers comme contexte dans les extractions, réponses et autres endpoints
  • Les fichiers expirent après 30 jours
  • Processus de téléchargement sécurisé via URL pré-signée
Pour les détails de l’API, consulte la Référence de l’API de l’Endpoint Fichiers.

​
Installation

# pip install requests

import requests

​
Télécharger un fichier

Le processus de téléchargement de fichier se compose de deux étapes :
  1. Créer une URL de téléchargement : Demande une URL pré-signée pour télécharger ton fichier
  2. Compléter le téléchargement : Télécharge ton fichier à l’URL pré-signée, puis appelle l’endpoint de complétion pour valider et finaliser

​
Étape 1 : Créer une URL de téléchargement

Tout d’abord, crée une URL de téléchargement en fournissant le nom du fichier et un objectif optionnel. Le paramètre purpose ne prend en charge que deux valeurs : "context" (par défaut) ou "batch". 
import requests
import json

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

# Étape 1 : Créer une URL de téléchargement
payload = {
    "filename": "my-data.json",
    "purpose": "context"  # Optionnel, par défaut "context". Valeurs prises en charge : "context" ou "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 réponse inclut : id, upload_url, expires_in
La réponse inclut une upload_url pré-signée qui expire dans 10 minutes : 
{
  "id": "file_abc123xyz789",
  "object": "file.upload",
  "created": 1760329882,
  "upload_url": "https://olostep-files.s3.amazonaws.com/files/...",
  "expires_in": 600
}

​
Étape 2 : Télécharger le fichier et compléter

Télécharge ton fichier JSON à l’URL pré-signée, puis appelle l’endpoint de complétion pour valider et finaliser le téléchargement. 
import requests
import json

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

# Après avoir obtenu upload_url de l'étape 1
file_id = upload_data["id"]
upload_url = upload_data["upload_url"]

# Prépare tes données JSON
json_data = {
    "users": [
        {"name": "John Doe", "email": "john@example.com"},
        {"name": "Jane Smith", "email": "jane@example.com"}
    ]
}

# Étape 2a : Télécharger le fichier à l'URL pré-signée
upload_response = requests.put(
    upload_url,
    data=json.dumps(json_data),
    headers={"Content-Type": "application/json"}
)
upload_response.raise_for_status()

# Étape 2b : Compléter le téléchargement
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))
L’endpoint de complétion valide le fichier JSON et renvoie les métadonnées du fichier : 
{
  "id": "file_abc123xyz789",
  "object": "file",
  "created": 1760329882,
  "filename": "my-data.json",
  "bytes": 1024,
  "purpose": "context",
  "status": "completed"
}

​
Récupérer les métadonnées d’un fichier par ID

Récupère les métadonnées d’un fichier par son 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))

​
Récupérer l’objet fichier par ID

Obtiens une URL pré-signée pour télécharger le contenu JSON d’un fichier complété. Tu peux éventuellement spécifier le temps d’expiration pour l’URL de téléchargement en utilisant le paramètre de requête expires_in (par défaut à 600 secondes / 10 minutes). 
file_id = "file_abc123xyz789"
# Obtenir l'URL de téléchargement (expiration par défaut : 600 secondes)
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"]

# Télécharger le contenu du fichier en utilisant l'URL pré-signée
file_response = requests.get(download_url)
file_content = file_response.json()
print(json.dumps(file_content, indent=2))

# Exemple avec expiration personnalisée (3600 secondes = 1 heure)
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"L'URL de téléchargement expire dans : {download_info['expires_in']} secondes")
La réponse inclut une download_url pré-signée qui expire après le temps spécifié : 
{
  "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
}

​
Lister les fichiers

Liste tous les fichiers complétés pour ton équipe. Tu peux éventuellement filtrer par objectif (valeurs prises en charge : "context" ou "batch"). 
# Lister tous les fichiers
response = requests.get(
    f"{API_URL}/files",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
files = response.json()
print(json.dumps(files, indent=2))

# Lister les fichiers filtrés par objectif
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 réponse inclut une liste de fichiers : 
{
  "object": "list",
  "data": [
    {
      "id": "file_abc123xyz789",
      "object": "file",
      "created": 1760329882,
      "filename": "my-data.json",
      "bytes": 1024,
      "purpose": "context",
      "status": "completed"
    }
  ]
}

​
Supprimer un fichier

Supprime un fichier et ses données associées du stockage. 
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))

​
Exemple de téléchargement complet (objectif context)

Voici un exemple complet qui télécharge un fichier JSON avec purpose="context" : 
import requests
import json

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

# Étape 1 : Créer une URL de téléchargement
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"]

# Étape 2 : Préparer et télécharger les données 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()

# Étape 3 : Compléter le téléchargement
complete_response = requests.post(
    f"{API_URL}/files/{file_id}/complete",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
file_info = complete_response.json()

print(f"Fichier téléchargé avec succès : {file_info['id']}")
print(f"Taille du fichier : {file_info['bytes']} octets")

​
Exemple de téléchargement de fichier batch

Voici un exemple qui télécharge un fichier JSON avec purpose="batch" contenant des données batch valides pouvant être utilisées avec l’endpoint /v1/batches : 
import requests
import json

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

# Étape 1 : Créer une URL de téléchargement avec 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"]

# Étape 2 : Préparer les données JSON batch (format valide pour l'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()

# Étape 3 : Compléter le téléchargement
complete_response = requests.post(
    f"{API_URL}/files/{file_id}/complete",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
file_info = complete_response.json()

print(f"Fichier batch téléchargé avec succès : {file_info['id']}")
print(f"Taille du fichier : {file_info['bytes']} octets")
print(f"Objectif : {file_info['purpose']}")
Le fichier batch téléchargé contient une structure JSON valide qui correspond au format de l’endpoint /v1/batches :
  • items : Tableau d’objets avec les champs custom_id et url
  • parser : Configuration optionnelle du parser
  • country : Code de pays optionnel
Ce fichier peut être utilisé comme entrée pour les opérations de traitement par lots.

​
Exigences pour les fichiers

  • Format de fichier : Seuls les fichiers JSON sont pris en charge (extension .json requise)
  • Taille de fichier : Maximum 200 Mo par fichier
  • Expiration : Les fichiers expirent après 30 jours
  • URL de téléchargement : Les URL pré-signées expirent après 10 minutes
  • Paramètre purpose : Ne prend en charge que les valeurs "context" ou "batch" (par défaut "context")

​
Tarification

Les téléchargements de fichiers sont gratuits. Les fichiers sont stockés en toute sécurité et expirent automatiquement après 30 jours.