Fichiers - Olostep Docs

Via le point d’accès 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 points d’accès
Les fichiers expirent après 30 jours
Processus de téléchargement sécurisé par URL pré-signée

Pour les détails de l’API, consulte la Référence de l’API du point d’accès 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 :

Créer une URL de téléchargement : Demande une URL pré-signée pour télécharger ton fichier
Compléter le téléchargement : Télécharge ton fichier vers l’URL pré-signée, puis appelle le point d’accès complet 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 une finalité optionnelle. Le paramètre purpose ne supporte 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 supportées : "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 vers l’URL pré-signée, puis appelle le point d’accès complet 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 vers 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))

Le point d’accès complet 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é. Spécifie éventuellement le temps d’expiration de 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. Filtre éventuellement par finalité (valeurs supportées : "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 finalité
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 (finalité contexte)

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 le point d’accès /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 le point d'accès /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"Finalité : {file_info['purpose']}")

Le fichier batch téléchargé contient une structure JSON valide qui correspond au format du point d’accès /v1/batches :

items : Tableau d’objets avec les champs custom_id et url
parser : Configuration optionnelle du parseur
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 supportés (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 de finalité : Ne supporte 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.

​Installation

​Télécharger un fichier

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

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

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

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

​Lister les fichiers

​Supprimer un fichier

​Exemple de téléchargement complet (finalité contexte)

​Exemple de téléchargement de fichier batch

​Exigences pour les fichiers

​Tarification