API Fichiers

Téléversez un document une fois, réutilisez-le autant de fois que vous voulez. CloudZIR en extrait le texte à l'enregistrement : vous récupérez ce texte et l'injectez dans vos prompts, sans réenvoyer le fichier à chaque requête.

Téléverser#

POST https://api.cloudzir.com/v1/files : multipart, champs file et purpose.

from openai import OpenAI

client = OpenAI(api_key="zir_ai_...", base_url="https://api.cloudzir.com/v1")

with open("facture.txt", "rb") as fichier:
    envoi = client.files.create(file=fichier, purpose="assistants")

print(envoi.id, envoi.status)     # 9f2c1a7b-… processed

import fs from "node:fs";

const envoi = await client.files.create({
  file: fs.createReadStream("facture.txt"),
  purpose: "assistants",
});

console.log(envoi.id, envoi.status);

curl https://api.cloudzir.com/v1/files \
  -H "Authorization: Bearer $CLOUDZIR_API_KEY" \
  -F purpose=assistants \
  -F file=@facture.txt

Réponse#

{
  "id": "9f2c1a7b-…",
  "object": "file",
  "bytes": 4821,
  "created_at": 1766400000,
  "filename": "facture.txt",
  "purpose": "assistants",
  "status": "processed",
  "status_details": null,
  "tokens": 1204
}

tokens est l'estimation de ce que le document coûtera en jetons d'entrée quand vous l'injecterez, de quoi anticiper la facture avant même d'appeler un modèle.

Utiliser le document#

Récupérez le texte extrait, puis mettez-le dans votre prompt :

import httpx

texte = httpx.get(
    f"https://api.cloudzir.com/v1/files/{envoi.id}/content",
    headers={"Authorization": f"Bearer {cle}"},
).text

reponse = client.chat.completions.create(
    model="mina-low",
    messages=[
        {"role": "system", "content":
         "Réponds UNIQUEMENT à partir du document. Si l'information n'y est pas, dis-le."},
        {"role": "user", "content": f"DOCUMENT :\n{texte}\n\nQUESTION : quel est le total ?"},
    ],
)

Pourquoi cette étape explicite

Vous voyez exactement ce que le modèle reçoit, et vous gardez la main : extraire un passage, découper, résumer. Un document injecté à l'aveugle est la première cause de factures surprises.

Gérer ses fichiers#

Appel	Effet
`GET /v1/files`	Liste vos fichiers (filtre `?purpose=`, `?limit=`).
`GET /v1/files/{id}`	Métadonnées d'un fichier.
`GET /v1/files/{id}/content`	Texte extrait (`text/plain`).
`DELETE /v1/files/{id}`	Supprime le fichier et son contenu stocké.

Vos fichiers ne sont visibles que par votre compte : l'identifiant d'un fichier d'un autre client renvoie 404, jamais son contenu.

Formats et limites#

Contrainte	Valeur
Formats à extraction directe	txt, md, csv, tsv, json, jsonl, xml, yaml, html, srt, vtt et la plupart des fichiers de code
PDF	Texte extrait automatiquement (un PDF scanné, sans couche texte, est signalé). La lecture est interrompue au-delà de 20 s de calcul (PDF trop complexe) et le texte extrait est plafonné à 2 000 000 caractères : le fichier porte alors `status: "error"` et un message explicite
Taille par fichier	10 Mo
Volume total par compte	100 Mo
Nombre de fichiers	200
`purpose`	`assistants`, `user_data`, `batch`

Quand un fichier n'est pas lisible#

Le téléversement réussit quand même, mais le fichier porte status: "error" et un status_details qui dit précisément pourquoi :

{
  "id": "…", "status": "error",
  "status_details": "Type de fichier non supporté (application/octet-stream). Formats acceptés : texte, code, csv, json, markdown, pdf."
}

Demander le contenu d'un tel fichier renvoie un 400 portant le même message, jamais un document vide qui donnerait des réponses inventées.

Documents scannés

Un PDF sans couche texte (photo ou scan) ne peut pas être extrait. Convertissez les pages en images et envoyez-les au modèle : voir Vision.

Découper les gros documents#

Un document plus long que la fenêtre du modèle doit être découpé. Voir Jeton et utilisation pour les fenêtres disponibles, et pensez à la mise en cache : en gardant le document au début de vos requêtes, il pourra être facturé à tarif réduit dès la deuxième question posée dessus, quand le cache le reconnaît (la réponse l'indique dans usage).

Suppression#

Pour supprimer explicitement un fichier, appelez DELETE /v1/files/{file_id}. Cette requête supprime le contenu et l'objet de stockage; une trace technique de suppression demeure. Aucune expiration automatique n'est appliquée à ces fichiers. Ils comptent dans votre quota de stockage, mais le stockage lui-même n'est pas facturé : seuls les jetons consommés lors de vos appels le sont.