# ObscuraGate API — documentation d'intégration > API compatible OpenAI (Chat Completions) donnant accès aux modèles DeepSeek V4. > Solde prépayé en USD, rechargeable en stablecoins. Version web : https://api.obscuragate.com/docs/ ## Connexion - URL de base : `https://api.obscuragate.com/v1` - Authentification : en-tête `Authorization: Bearer ` (clé au format `sk-…`) - Format : identique à l'API OpenAI Chat Completions. Tout SDK OpenAI fonctionne en changeant `base_url` et `api_key`. - Lire la clé depuis une variable d'environnement (ex. `OBSCURAGATE_API_KEY`). Ne jamais l'écrire en dur ni l'exposer côté navigateur. ## Modèles et tarifs (USD par million de tokens) | Modèle | Entrée | Entrée en cache | Sortie | Usage | |---|---|---|---|---| | `deepseek-v4.1-flash` (recommandé) | 0.105 | 0.00315 | 0.315 | chat, agents, extraction, gros volumes | | `deepseek-v4-flash` | 0.105 | 0.00315 | 0.315 | génération précédente du modèle rapide | | `deepseek-v4-pro` | 0.33 | 0.0098 | 0.65 | raisonnement difficile, code, qualité maximale | | `deepseek-v4.1-flash-1017`, `deepseek-v4-flash-0731` | 0.105 | pas de cache | 0.315 | versions datées, figées | | `deepseek-v4-pro-0813` | 0.33 | pas de cache | 0.65 | version datée, figée, du modèle pro | - Liste à jour : `GET /v1/models` (accessible même avec un solde nul). - Coût d'une requête = entrée hors cache × prix entrée + entrée en cache × prix cache + sortie × prix sortie. - Les modèles raisonnent avant de répondre : les tokens de raisonnement sont inclus dans `completion_tokens` (détail : `completion_tokens_details.reasoning_tokens`) et facturés au prix de sortie. Prévoir un `max_tokens` suffisant pour le raisonnement ET la réponse. ## Choisir la source : variantes `:p1` et `:p2` `deepseek-v4.1-flash` et `deepseek-v4-pro` sont servis par deux sources d'inférence indépendantes. Même prix pour toutes les variantes. | Nom demandé | Comportement | |---|---| | `deepseek-v4.1-flash` | automatique (recommandé) : source 1, bascule sur la source 2 si indisponible/saturée | | `deepseek-v4.1-flash:p1` | source 1 uniquement, cache de prompt actif | | `deepseek-v4.1-flash:p2` | source 2 uniquement, PAS de cache (entrée toujours au prix normal) | | `deepseek-v4-pro` | automatique (recommandé) : source 2, bascule sur la source 1 | | `deepseek-v4-pro:p1` / `deepseek-v4-pro:p2` | source imposée ; cache actif sur `:p2` | Avec `:p1`/`:p2` il n'y a PAS de bascule : source saturée → HTTP 503 (réessayer ou utiliser le nom sans suffixe). Les variantes servent à comparer les sources (latence, qualité, stabilité) ou à garder un comportement constant. Le champ `model` de la réponse reprend le nom demandé. ## Cache de prompt (automatique) Quand le début d'une requête est identique à celui d'une requête récente, ces tokens sont facturés au prix "cache" (~33× moins cher). Pour en profiter : - contenu stable au début (prompt système, instructions, documents, exemples) ; - contenu variable à la fin (question, horodatage, identifiants) ; - en conversation, renvoyer l'historique tel quel et ajouter les nouveaux messages à la fin ; - ne pas mettre de date ou d'identifiant unique dans le prompt système. ## Exemples Python : ```python from openai import OpenAI import os client = OpenAI(base_url="https://api.obscuragate.com/v1", api_key=os.environ["OBSCURAGATE_API_KEY"]) resp = client.chat.completions.create( model="deepseek-v4.1-flash", messages=[{"role": "system", "content": "Tu es un assistant concis."}, {"role": "user", "content": "Bonjour !"}], ) print(resp.choices[0].message.content, resp.usage) ``` Node.js : ```js import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.obscuragate.com/v1", apiKey: process.env.OBSCURAGATE_API_KEY }); const resp = await client.chat.completions.create({ model: "deepseek-v4.1-flash", messages: [{ role: "user", content: "Bonjour !" }] }); console.log(resp.choices[0].message.content); ``` curl : ```bash curl https://api.obscuragate.com/v1/chat/completions \ -H "Authorization: Bearer $OBSCURAGATE_API_KEY" -H "Content-Type: application/json" \ -d '{"model":"deepseek-v4.1-flash","messages":[{"role":"user","content":"Bonjour !"}]}' ``` ## POST /v1/chat/completions Paramètres : `model` (obligatoire), `messages` (obligatoire ; rôles system/user/assistant/tool), `max_tokens`, `temperature`, `top_p`, `stream`, `tools`, `tool_choice`, `response_format` (`{"type":"json_object"}`), `stop`. Réponse : ```json { "id": "42dcb00613e20659ae05b8ce95c8ba15", "object": "chat.completion", "model": "deepseek-v4.1-flash", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Bonjour !"}, "finish_reason": "stop"}], "usage": { "prompt_tokens": 5922, "prompt_tokens_details": {"cached_tokens": 5760}, "prompt_cache_hit_tokens": 5760, "prompt_cache_miss_tokens": 162, "completion_tokens": 12, "completion_tokens_details": {"reasoning_tokens": 5}, "total_tokens": 5934 } } ``` Champs d'usage : `prompt_tokens` = entrée totale ; `prompt_tokens_details.cached_tokens` (= `prompt_cache_hit_tokens`) = part en cache ; `prompt_cache_miss_tokens` = part hors cache ; `completion_tokens` = sortie, raisonnement compris. ## Streaming `"stream": true` → Server-Sent Events (`data: {…}`), terminé par `data: [DONE]`. Le dernier événement contient `usage` (ajouté automatiquement, `stream_options` inutile). ```python stream = client.chat.completions.create(model="deepseek-v4.1-flash", messages=[{"role": "user", "content": "Haïku sur la mer"}], stream=True) for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True) if chunk.usage: print(chunk.usage) ``` ## Solde `GET /v1/billing/balance` → `{"balance_usd": 250.0, "client": "clt_…"}` Chaque requête réussie est débitée de son coût exact. Solde épuisé → HTTP 402 (`insufficient_balance`) jusqu'à la recharge. ## Recharge en stablecoins Minimum 20 $ (certains réseaux un peu plus), maximum 10 000 $. Crédit automatique après confirmation on-chain (quelques minutes). Liste complète des réseaux : `GET /v1/billing/currencies`. Codes courants : `usdttrc20` (USDT Tron), `usdtbsc` (USDT BSC), `usdtsol` (USDT Solana), `usdterc20` (USDT Ethereum), `usdcsol` (USDC Solana), `usdcbase` (USDC Base), `usdcbsc` (USDC BSC), `usdcerc20` (USDC Ethereum). Option A, adresse de dépôt par API — `POST /v1/billing/topup` avec `{"amount_usd": 50, "pay_currency": "usdttrc20"}` : ```json {"payment_id": "5223464798", "pay_address": "T…", "pay_amount": "50.21", "pay_currency": "usdttrc20", "network": "trx", "payin_extra_id": "", "amount_usd": 50, "status": "waiting", "expires_at": "2026-11-18T10:00:00.000Z"} ``` Envoyer exactement `pay_amount` sur le réseau indiqué avant `expires_at`. Si `payin_extra_id` n'est pas vide (memo/tag), il est obligatoire. Une adresse = un paiement. Un envoi incomplet n'est pas crédité automatiquement. Option B, lien de paiement — `POST /v1/billing/invoice` avec `{"amount_usd": 50}` (`pay_currency` facultatif) → `{"invoice_id": "…", "payment_url": "https://…", "amount_usd": 50}`. Payer uniquement avec un stablecoin de la liste. Suivi : interroger `GET /v1/billing/balance`. ## Erreurs Format : `{"error": {"type": "…", "message": "…"}}` (messages en français). | Code | Cause | Action | |---|---|---| | 400 | requête invalide ou modèle inconnu | vérifier le JSON et `/v1/models` | | 401 | clé absente, invalide ou désactivée | vérifier `Authorization: Bearer …` | | 402 | solde épuisé | recharger | | 429 | trop de requêtes | réessayer avec backoff exponentiel | | 500/502/503/504 | modèle momentanément indisponible (`service_unavailable`) | réessayer, ou utiliser le nom sans suffixe (bascule auto) ou l'autre variante ; une requête en échec n'est pas facturée | Délai max par requête : 10 min. Taille max : 32 Mo. ## Confidentialité Le contenu des requêtes et réponses n'est pas enregistré par la passerelle ; seuls les compteurs de tokens et le coût sont conservés. La clé est stockée hachée (non récupérable) : en cas de perte ou fuite, demander une nouvelle clé. Connexions HTTPS uniquement.