OpenAPI et index des points de terminaison
Contrat OpenAPI 3.1 téléchargeable, points de terminaison publics et guides associés, en-têtes communs et origine de production.
Le contrat public lisible par machine est disponible en YAML OpenAPI 3.1. Utilisez-le pour générer un client ou vérifier votre intégration avec les points de terminaison publics actuels.
Origine de l’API de production
https://api.spicyapi.ai est la seule origine de production déclarée par servers[0].url dans OpenAPI. Les API de tâches utilisent /api/v1 ; la compatibilité de protocole utilise /v1 et /v1beta.
Ces API de plateforme permettent de choisir les modèles, d’obtenir des estimations et de suivre les dépenses sans ouvrir la console. Le catalogue des modèles inclut les tarifs du compte ; utilisez un devis basé sur l’entrée exacte lorsque le tarif dépend des paramètres. L’historique des tâches et l’utilisation sont limités à la clé API utilisée pour l’appel. La création et la rotation des clés ainsi que les budgets restent dans la console. Chaque tableau renvoie au guide qui explique entièrement le point de terminaison.
Découverte des modèles, tarifs et API de compte
| Méthode | Chemin | Fonction | Guide |
|---|---|---|---|
GET | /console/v1/catalog/models | Catalogue public d’évaluation : sans clé API, tarifs standard, limitation par adresse source | Démarrage rapide |
GET | /api/v1/models | Lire les modèles appelables, les tarifs du compte et les schémas facultatifs | Catalogue des modèles |
GET | /api/v1/models/{model} | Lire un modèle et son JSON Schema complet | Catalogue des modèles |
POST | /api/v1/jobs/quote | Obtenir un devis valable cinq minutes pour la requête exacte, sans créer de tâche ni réserver de fonds | Devis |
GET | /api/v1/chat/credit | Lire le solde disponible, réservé et total | Facturation |
GET | /api/v1/usage | Lire les appels de la clé actuelle et les dépenses USD réglées, par date et par modèle | Facturation |
API de génération et de tâches
| Méthode | Chemin | Fonction | Guide |
|---|---|---|---|
GET | /api/v1/jobs | Lister l’historique des tâches de la clé API actuelle, avec pagination par curseur | Tâches |
POST | /api/v1/jobs/createTask | Créer une tâche de génération asynchrone | Tâches |
GET | /api/v1/jobs/recordInfo | Lire une tâche créée avec la clé API utilisée pour l’appel | Tâches |
POST | /api/v1/jobs/retry | Créer une tâche depuis une source échouée ou expirée ; les anciennes traces annulées restent compatibles | Actions sur les tâches |
POST | /api/v1/jobs/purge | Détruire les fichiers et le prompt d’une tâche terminée ; la trace de facturation reste inchangée | Conservation |
POST | /api/v1/jobs/stream | Exécuter un modèle de texte et diffuser la réponse en SSE | Texte et streaming |
API de médias
| Méthode | Chemin | Fonction | Guide |
|---|---|---|---|
POST | /api/v1/common/upload-url | Émettre un ticket d’envoi direct de média | Médias |
POST | /api/v1/files/{fileId}/commit | Vérifier et valider un envoi direct, puis renvoyer l’URI spicy:// utilisable dans une tâche | Médias |
POST | /api/v1/files/import | Importer un fichier de poids LoRA depuis un lien, avec un jeton d’accès facultatif utilisé une seule fois et jamais conservé ; renvoie une URI spicy:// utilisable dans une tâche | Poids d’adaptateur |
POST | /api/v1/common/download-url | Émettre une URL de téléchargement temporaire pour une sortie de tâche (facultatif : les tâches terminées en incluent déjà une) | Médias |
POST | /api/v1/assets | Enregistrer un fichier dans la bibliothèque d’assets (Idempotency-Key obligatoire) | Médias |
GET | /api/v1/assets | Lister vos assets enregistrés (filtres favorite, collectionId, q ; tri avec sort) | Médias |
GET | /api/v1/assets/usage | Consulter le forfait, l’utilisation et les limites de la bibliothèque d’assets | Médias |
GET | /api/v1/assets/{assetId} | Obtenir un asset avec un nouveau lien d’aperçu privé | Médias |
PATCH | /api/v1/assets/{assetId} | Renommer un asset ou modifier son indicateur favorite | Médias |
DELETE | /api/v1/assets/{assetId} | Supprimer un asset | Médias |
GET | /api/v1/assets/entities | Lister les personnages de votre bibliothèque d’assets (lecture seule) | Médias |
GET | /api/v1/assets/entities/{entityId} | Obtenir un personnage avec ses images dans l’ordre (lecture seule) | Médias |
Authentification et enveloppes
Tous les points de terminaison, sauf le catalogue public, exigent votre clé API sous la forme Authorization: Bearer sk-spicy-…. Les points de terminaison compatibles (/v1, /v1beta) acceptent aussi x-api-key, envoyé par les SDK Anthropic, et x-goog-api-key, envoyé par les SDK Google GenAI. Une clé dans les paramètres de l’URL n’est jamais acceptée. Les tâches, relances, destructions et liens de téléchargement sont visibles uniquement avec la clé API qui a créé la tâche ; voir Authentification.
Les réponses JSON des API de tâches partagent l’enveloppe {code,msg,data,request_id} ; les points de terminaison compatibles emploient les formats de leurs propres protocoles. Le résultat d’une tâche est exprimé par data.state, pas par le code de l’enveloppe. Voir Erreurs.
En-têtes utilisés par plusieurs points de terminaison
| En-tête | Destination | Fonction |
|---|---|---|
Authorization: Bearer … | Tout sauf le catalogue public | Votre clé API |
Idempotency-Key | jobs/createTask, jobs/retry, jobs/stream, POST /v1/videos et les points de terminaison de texte /v1 et /v1beta | Sécurise un renvoi après une erreur réseau. Sur les API de tâches, renvoie la tâche originale ; sur les API de texte, empêche une seconde facturation mais ne peut restituer une réponse perdue. Voir Idempotence |
X-Spicy-Retention | jobs/createTask, jobs/stream | Raccourcit la conservation des sorties et du prompt de cette tâche, en secondes. Voir Conservation |
Accept-Language | Tous | Langue des messages d’erreur ; les codes ne changent jamais. Voir Erreurs |
Utiliser le fichier OpenAPI
- Essayer des requêtes sans écrire de code : importez le fichier OpenAPI lié en haut de page dans un client API tel que Postman, Insomnia ou Bruno, puis définissez votre clé API comme jeton bearer. N’oubliez pas que la création de tâches coûte de l’argent.
- Générer un client : fournissez le même fichier à un générateur de code OpenAPI 3.1 pour votre langage.
Évolution du contrat
- Ne conservez pas les paramètres de modèles comme une copie figée et codée en dur ; lisez
inputSchemadepuis/models/{model}. - Tolérez les champs inconnus dans les réponses, mais ne devinez jamais les champs inconnus d’une requête.
- Fournissez le YAML OpenAPI à la génération de code ou aux tests de contrat avant une publication.
Points de terminaison compatibles
| Méthode | Chemin | Protocole |
|---|---|---|
GET | /v1/models | Models |
POST | /v1/chat/completions | Chat Completions |
POST | /v1/responses | Responses |
POST | /v1/messages | Messages |
POST | /v1beta/models/{model}:generateContent | Gemini generateContent |
POST | /v1beta/models/{model}:streamGenerateContent | Gemini streamGenerateContent |
POST | /v1/videos | Videos |
GET | /v1/videos/{videoId} | État de la vidéo |
GET | /v1/videos/{videoId}/content | Contenu de la vidéo |
Les points de terminaison de texte sont décrits dans Texte et streaming ; leurs tarifs le sont dans Devis et compatibilité.
Le package TypeScript officiel est @spicyapi/sdk. Pour Python et Go, ou si vous ne pouvez pas ajouter de dépendance, les clients de référence copiables ci-dessous appellent ces points de terminaison avec le seul environnement d’exécution du langage. Le client Python gère seul un traitement média complet : envoyer et valider une référence, confirmer le tarif par un devis, créer la tâche et l’interroger jusqu’à un état terminal, lire un résultat sous forme de fichiers ou de texte, renouveler un lien de sortie expiré, détruire ensuite le contenu stocké et vérifier une signature de webhook. Le client Go couvre la même chaîne avec un contexte pour chaque appel et une erreur typée récupérable par errors.As. Le client TypeScript couvre la création de tâches, la relance, la lecture des états et une attente bornée ; pour les envois de fichiers et le reste des API dans Node.js, utilisez le SDK.
Clients de référence copiables
Exemples sans dépendance couvrant la découverte des modèles, la création de tâches, la relance d’une tâche en échec, le suivi des états, l’attente bornée, l’idempotence et les erreurs. Une tâche acceptée ne peut plus être annulée.
Ce sont des exemples de documentation, pas des paquets npm ou PyPI ni des modules Go publiés. Dix minutes est une limite locale, pas un SLA.
