Clé API OCR : obtention, création et sécurisation (2026)

La clé d'une interface OCR n'est qu'un identifiant d'identité, mais l'usage de l'OCR a ses particularités : traitement par lots de factures, de pièces d'identité et de scans, tâches souvent exécutées en arrière-plan. Si la clé fuit, ce sont vos quotas qui sont consommés, et ce sont parfois des données clients qui sont exposées. Beaucoup d'équipes réutilisent aussi directement une clé de test en production.

Cet article suit l'ordre réel d'intégration : distinguer les types de clés, dérouler l'inscription et la création, traiter droits, quotas et variables d'environnement, diagnostiquer un 401, choisir entre accès direct et passerelle, puis organiser la rotation et la réponse à une fuite.

Remarque : OpenAI, Google, Microsoft, Alibaba Cloud, Tencent Cloud, Baidu et les autres marques citées appartiennent à leurs détenteurs respectifs. Cet article est purement technique et n'implique aucun lien d'affiliation avec ces sociétés ; interfaces, droits et règles de facturation font foi dans la documentation officielle et sur les pages du site.

1. Distinguer les trois modes d'authentification OCR

Les clés OCR n'obéissent pas à un standard unique. Identifiez la catégorie de la plateforme avant l'intégration, sinon vous risquez le classique « la clé est bonne mais j'obtiens 401 » :

• Clé Bearer : la plus courante sur les interfaces compatibles OpenAI, avec l'en-tête Authorization: Bearer sk-.... Chat, vision et OCR partagent généralement la même authentification.
• Access Key + Secret Key : utilisée par certains fournisseurs cloud ; la requête doit être signée selon la documentation, et le Secret ne doit jamais apparaître dans le front-end ni dans un journal.
• API Key + Secret Key contre un jeton : la clé et le secret servent d'abord à obtenir un access_token de courte durée, puis le jeton appelle l'OCR ; il faut le renouveler à expiration.

Sur une même plateforme, l'OCR peut partager une clé avec les modèles de chat. L'accès dépend des droits du compte, des droits sur les modèles et du solde, pas du type de clé. Avant de créer la clé, vérifiez si la console propose une liste blanche de modèles ou des droits de sous-compte.

2. Inscription et création de la clé

Avec ZSQH AI Gateway, le processus est le suivant :

1. Ouvrez https://ai.zhongshangqihang.com ou directement le lien d'inscription, inscrivez-vous par e-mail et validez le compte.
2. Connectez-vous à la console et ouvrez la page « Clés API » pour voir les clés existantes.
3. Vérifiez le solde dans « Portefeuille » ; en phase de test, rechargez un petit montant.
4. Cliquez sur « Nouvelle clé », renseignez le nom, le plafond de quota et la date d'expiration ; si la plateforme le permet, limitez les modèles disponibles.
5. Copiez immédiatement la clé complète après l'enregistrement. La plupart des plateformes ne l'affichent qu'une fois ; ensuite, seul un masque reste visible.
6. Validez une requête avec une image de test, puis vérifiez dans « Journal d'usage » que le modèle, le nombre d'appels et le coût sont enregistrés correctement.

Si vous utilisez l'OCR natif d'un fournisseur cloud, créez un sous-compte limité aux droits OCR. N'utilisez pas l'Access Key du compte principal pour les tests et la production.

3. Comment remplir nom, quota et expiration

Le nom de la clé doit permettre de comprendre la facture six mois plus tard. Utilisez une combinaison « usage + environnement », par exemple ocr-prod-batch, ocr-staging, ocr-dev-zhang, et évitez les noms du type « test1 ».

Commencez avec un plafond bas, puis augmentez après avoir mesuré la consommation d'un lot réel. Adaptez l'expiration à l'usage : 7 ou 30 jours pour un script temporaire, et un cycle de rotation fixe même pour une clé de production. Une répartition applicable :

Scénario	Nom de clé	Quota	Stockage	Rotation
Développement local	ocr-dev-nom	Minimal	.env local	30 jours
Environnement de test	ocr-staging	Faible	Secret CI/CD	60 jours
Production par lots	ocr-prod-batch	Selon budget	Gestionnaire de secrets	90 jours
Production temps réel	ocr-prod-realtime	Selon budget	Gestionnaire de secrets	90 jours

Si la plateforme permet de restreindre par modèle, ne cochez que les modèles OCR ou vision nécessaires. Si elle ne permet que l'isolation par projet, séparez au moins les projets et les quotas. N'utilisez jamais la même clé pour le débogage local, l'environnement de test et la production.

4. Quatre principes de conception des droits

• Une clé par usage : séparez reconnaissance par lots, interface temps réel et scripts d'administration. En cas d'anomalie sur un type de tâche, vous pouvez désactiver la clé correspondante sans affecter le reste.
• Moindre privilège : n'ouvrez que l'OCR si possible, utilisez un sous-compte plutôt que la clé du compte principal, limitez au projet plutôt qu'au compte.
• Pas de clé dans le front-end : une clé dans un navigateur, une application ou un mini-programme est facile à extraire. L'envoi d'image et la requête OCR doivent passer par votre propre back-end, qui détient la clé.
• Isolation production/test : une fuite de clé de test n'affecte pas la facture de production et le trafic de test ne pollue pas les relevés de production.

L'OCR touche souvent à des factures, des contrats et des pièces d'identité. Les droits de la clé sont proches de droits d'accès aux données : outre le contrôle des appels, vérifiez si la plateforme conserve l'image d'origine, pendant combien de temps et si elle l'utilise pour l'entraînement. Activez la liste blanche IP en production lorsqu'elle existe et conservez les traces d'audit.

5. Placer la clé dans les variables d'environnement

Ne codez pas la clé en dur et ne la commitez pas dans Git. Un projet Python peut la lire ainsi :

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model=os.environ["OCR_MODEL"],  # nom du modèle acceptant les images, page tarifs
    messages=[{"role": "user", "content": "Réponds seulement OK"}],
)
print(resp.choices[0].message.content)

Ce code valide seulement la correspondance entre clé, URL de base et nom de modèle ; une fois la connexion confirmée, remplacez le message par une requête avec une vraie image.

En local, ajoutez .env à .gitignore et ne commitez que .env.example. En production, privilégiez les secrets de conteneur, la gestion de clés du cloud ou un service comme Vault ; n'écrivez pas la clé dans un Dockerfile, une couche d'image, un bundle front-end ou un journal CI. Après modification d'une variable, redémarrez le processus : beaucoup de cas « 401 en ligne, OK en local » viennent d'une variable ancienne encore lue ou d'une plateforme de déploiement qui ne l'injecte pas dans l'environnement d'exécution.

6. Ordre de diagnostic d'un 401

Face à 401 Unauthorized, procédez ainsi ; quelques minutes suffisent généralement :

1. Vérifiez l'en-tête Authorization: Bearer sk-... : un seul espace entre Bearer et la clé.
2. Recopiez la clé et vérifiez l'absence d'espace, de saut de ligne, de guillemet ou de caractère invisible.
3. Vérifiez que la clé n'a pas été supprimée, désactivée ou expirée.
4. Vérifiez que la clé et l'URL de base appartiennent à la même plateforme ; ne mélangez pas les clés de deux plateformes.
5. Affichez la longueur de la variable dans le processus (pas son contenu) pour confirmer qu'une valeur est bien lue.
6. Vérifiez qu'un reverse proxy, une passerelle ou le SDK ne réécrit pas l'en-tête Authorization ; les formulaires multipart le perdent facilement.
7. Si seules certaines requêtes échouent, vérifiez si une clé a été exposée côté front-end et désactivée par le contrôle des risques.

Distinguez aussi les types d'erreur : 401 est un problème d'identité, 403 relève souvent des droits ou d'une restriction régionale, 413 d'une image trop lourde, 429 de la fréquence ou du quota. En OCR, un 400 vient souvent du format d'image, de l'encodage Base64 ou d'un fichier corrompu : ne l'attribuez pas systématiquement à la clé.

7. Clé directe ou clé de passerelle

Les deux voies fonctionnent ; la différence porte surtout sur l'achat, le réseau et la maintenance.

• Accès direct : compte, facturation et modèles gérés par l'éditeur d'origine ; convient aux équipes capables de payer, de gérer le réseau et la conformité. Avec un seul service OCR, le parcours est le plus court ; avec plusieurs fournisseurs, il faut maintenir autant d'authentifications et de factures.
• Accès par passerelle : une URL de base et une clé pour plusieurs modèles, un accès national et un règlement en RMB simplifiés, des journaux et quotas centralisés. En contrepartie, une dépendance supplémentaire : vérifiez la politique de données, la disponibilité, le mode de notification des incidents et la facturation du prestataire.

Ne choisissez pas uniquement sur le prix. Vérifiez au minimum : conservation des images et des résultats, facturation, annonce des retraits de modèles, export de l'usage, contact en cas d'incident. Les modèles et prix exacts figurent sur la page Tarifs des modèles ; les tarifs changent, ne budgétez pas sur des chiffres d'anciens articles.

8. Rotation et réponse à une fuite

Faites de la rotation une opération régulière, pas une réaction à l'incident :

1. Créez une nouvelle clé avec les mêmes droits sur la plateforme d'origine.
2. Mettez à jour la valeur dans les variables ou le gestionnaire de secrets.
3. Redémarrez ou redéployez le service, puis envoyez une image de test pour confirmer.
4. Surveillez les journaux d'usage pendant 24 à 48 heures pour détecter des appels anormaux.
5. Désactivez et supprimez l'ancienne clé, puis notez la date et l'opérateur.

En cas de soupçon de fuite, inversez l'ordre : désactivez d'abord l'ancienne clé, consultez les journaux d'usage et l'origine des appels, inspectez l'historique du dépôt, les journaux CI et les couches d'image, puis créez une nouvelle clé. Supprimer une chaîne dans le code ne suffit pas : la clé a pu être copiée ailleurs. Si le compte contient un solde, évaluez aussi une réduction temporaire du quota.

Questions fréquentes

La clé OCR est-elle la même que celle des modèles de chat ?

Sur une plateforme compatible OpenAI, l'authentification est généralement commune : une même clé appelle le chat et les modèles vision acceptant des images. L'accès dépend des droits du compte et des droits sur les modèles, pas du type de clé.

Peut-on revoir la clé complète après sa création ?

Généralement non. La clé complète n'est affichée qu'à la création, puis seul un masque subsiste. Si vous ne l'avez pas conservée, supprimez-la et recréez-en une ; ne tentez pas de la récupérer dans les journaux ou le cache du navigateur.

Pourquoi l'appel fonctionne-t-il en local mais renvoie 401 sur le serveur ?

Vérifiez trois choses en priorité : la variable est-elle injectée, le reverse proxy conserve-t-il l'en-tête Authorization, la clé en ligne est-elle supprimée ou expirée. Vérifiez ensuite que l'URL de base pointe vers la bonne plateforme.

L'OCR facture-t-il à l'image ou au jeton ?

Les deux existent. L'OCR traditionnel facture souvent à l'image ou à la page ; un modèle multimodal facture les jetons issus de l'image d'entrée plus les jetons de sortie. Les règles exactes figurent dans la documentation de la plateforme et sur la page Tarifs des modèles.

Supprimer la clé suffit-il après une fuite ?

Non. Désactivez d'abord la clé, consultez les journaux pour détecter des appels anormaux, inspectez le dépôt, les journaux CI et l'historique des images, puis faites tourner toutes les clés potentiellement concernées. Si des pièces d'identité ou des factures clients sont impliquées, évaluez la nécessité d'une notification selon le processus de sécurité interne.

Étape suivante

Si vous n'avez pas encore de compte, commencez par la page d'inscription, créez une clé à faible quota et validez l'authentification avec une image de test. Consultez ensuite la page Tarifs des modèles pour choisir le modèle de production. Le traitement des champs structurés est décrit dans le guide d'intégration.

Pour aller plus loin :

• Intégrer une API OCR : envoi d'images et champs structurés
• Prix et facturation d'une API OCR : pages, champs et lots
• OCR gratuit : quotas, limites et cas d'usage

Remarque : OpenAI, Google, Microsoft, Alibaba Cloud, Tencent Cloud et Baidu sont des marques de leurs détenteurs respectifs. Cet article est purement technique et n'implique aucun lien d'affiliation avec ces sociétés ; interfaces, droits et règles de facturation font foi dans la documentation officielle.