SDK Go

spicy-go est le SDK Go officiel de SpicyAPI. Il place la génération d’images, de vidéos et de sons derrière un seul *spicy.Client : il joint votre clé API, décode l’enveloppe de réponse en structures typées, attend une tâche avec une temporisation bornée, téléverse les fichiers locaux en un seul appel et donne à chaque échec un type d’erreur unique, que vous reconnaissez avec errors.As.

Il demande Go 1.23 ou plus récent et n’utilise que la bibliothèque standard. C’est délibéré : ce paquet entre dans votre graphe de dépendances, et chaque module qu’il y entraînerait serait une chose de plus à auditer.

Est-ce le bon outil ?

L’installer

Go résout les modules directement depuis leur dépôt : il n’y a donc aucune étape de registre et rien à attendre. Cette commande fonctionne dès aujourd’hui :

go get github.com/spicyapi-ai/spicy-go

Placez ensuite votre clé dans l’environnement, pour qu’elle n’apparaisse jamais dans votre code ni dans le fichier d’historique de votre shell :

export SPICY_API_KEY="sk-spicy-..."

Votre premier résultat

Demandez le prix, décidez, créez la tâche, attendez, lisez les fichiers. Le devis est gratuit et ne réserve rien.

client, err := spicy.New(spicy.Options{}) // lit SPICY_API_KEY dans l’environnement
if err != nil {
    return err
}

request := spicy.CreateTaskInput{
    Model: "MODEL_ID_FROM_CATALOG",
    Input: map[string]any{"prompt": "a lantern in fog"},
}

quote, err := client.Quote(ctx, request)
if err != nil {
    return err
}
log.Printf("this will cost at most %s", quote.MaxCharge)

// Enregistrez cette clé à côté de votre propre trace du travail avant d’envoyer
// quoi que ce soit : toute sa raison d’être est d’exister encore après la panne
// qui a fait perdre la réponse.
key, err := spicy.NewIdempotencyKey()
if err != nil {
    return err
}

request.Model = quote.Model
request.QuoteID = quote.QuoteID
request.ExpectedCost = quote.EstimatedCost

task, err := client.CreateTask(ctx, request, key, spicy.CreateTaskOptions{})
if err != nil {
    return err
}

final, err := client.WaitForTerminal(ctx, task.TaskID, spicy.WaitOptions{})
if err != nil {
    return err
}
for _, asset := range final.ReadyAssets() {
    log.Println(asset.URL)
}

MODEL_ID_FROM_CATALOG est un emplacement réservé. Prenez un vrai identifiant dans le catalogue authentifié — client.ListModels, c’est-à-dire GET /api/v1/models — et jamais de mémoire ni d’une page ancienne : des modèles sont ajoutés, suspendus et retirés. Construisez Input à partir de l’inputSchema propre à ce modèle, que renvoie ListModels ; chaque modèle accepte des champs différents.

Les montants sont des chaînes décimales en dollars américains, jamais des flottants, parce qu’un flottant binaire ne peut pas contenir exactement la plupart des montants décimaux. Il n’y a ni crédits ni points nulle part dans cette API.

Un état final n’est pas pour autant un succès : failed, canceled et expired mettent tous fin à l’attente. Vérifiez final.State.

Sauter la première interrogation

WaitSeconds demande au service de garder la connexion ouverte jusqu’à la fin de la tâche : sur un modèle rapide, le résultat arrive donc avec la soumission.

seconds := 30
task, err := client.CreateTask(ctx, request, key, spicy.CreateTaskOptions{WaitSeconds: &seconds})
if err != nil {
    return err
}

// Task vaut nil dès que l’attente a expiré. C’est le déroulement ordinaire, pas
// une erreur : la génération continue, il suffit d’interroger à partir d’ici.
final := task.Task
if final == nil {
    final, err = client.WaitForTerminal(ctx, task.TaskID, spicy.WaitOptions{})
    if err != nil {
        return err
    }
}
log.Println(final.State, final.Cost)

C’est une optimisation, jamais une garantie. Un code qui lit task.Task sans le test à nil marche parfaitement jusqu’à la première génération plus lente que le budget, puis provoque un panic en production.

Partir d’un fichier local

L’image vers vidéo, le remplacement de personne et la retouche d’image demandent tous que votre matière première soit d’abord chez nous. UploadFile réalise le téléversement en trois temps — ticket, PUT vers le stockage, validation — en un seul appel et renvoie une URI spicy://. C’est cette URI qui part dans Input.

uploaded, err := client.UploadFile(ctx, "/path/to/reference.png", "")
// uploaded.URI -> "spicy://f/fil_..."

Une URL HTTPS publiquement joignable peut aller directement dans l’entrée, sans aucun téléversement. Les images sont acceptées jusqu’à 10 Mio, l’audio et la vidéo jusqu’à 90 Mio ; voir Médias.

Solde, consommation et historique

Les trois sont limités à la clé API appelante : les clés sœurs du même compte, et les générations lancées dans la console web, n’y figurent pas, et leur absence n’est pas un défaut.

balance, err := client.GetBalance(ctx)
if err != nil {
    return err
}
log.Printf("%s available, %s held by accepted tasks", balance.Available, balance.Held)

usage, err := client.GetUsage(ctx, spicy.UsageOptions{From: "2026-09-01", To: "2026-09-08"})
if err != nil {
    return err
}
log.Printf("%d calls, %s settled over [%s,%s)", usage.TotalCalls, usage.TotalSpend, usage.From, usage.To)

// EachTask répète chaque filtre sur chaque page et ne fait bouger que le curseur.
if err := client.EachTask(ctx, spicy.ListTasksOptions{From: "2026-09-01", To: "2026-09-08"},
    func(task spicy.TaskListItem) bool {
        log.Println(task.TaskID, task.State, task.Cost)
        return true // renvoyez false pour arrêter avant la fin
    }); err != nil {
    return err
}

Les dates sont des jours calendaires UTC, dans un intervalle semi-ouvert [from, to) de 92 jours au maximum. Fixez From et To sur tout parcours susceptible de franchir minuit UTC. Laissés vides, le serveur recalcule sa propre fenêtre — to vaut demain en UTC — à chaque page : un parcours qui commence à 23:59 et se poursuit à 00:01 pose donc deux questions différentes et recolle les réponses. Rien ne le signale.

GetUsage sert au rapprochement comptable, pas au suivi d’avancement. Il est soumis à un budget d’appels valable pour tout le compte et partagé par toutes les clés, et ce limiteur se ferme en cas de doute : l’interroger en boucle peut priver toutes les autres clés de leurs propres rapports. Suivez plutôt une tâche avec WaitForTerminal. Le règlement peut aussi arriver en retard : un chiffre lu aujourd’hui peut donc encore changer demain.

Erreurs

Les échecs reviennent sous la forme d’une *spicy.APIError, que vous atteignez avec errors.As :

var apiErr *spicy.APIError
if errors.As(err, &apiErr) {
    log.Println(apiErr.Status, apiErr.Code, apiErr.RequestID, apiErr.RetryAfter)
}

Branchez sur Code, jamais sur le message : les messages sont traduits, les codes non. Le statut HTTP 503 est partagé par trois codes métier différents : le statut seul ne suffit donc pas à décider quoi faire.

Tous les codes sont listés dans Erreurs. Citez RequestID quand vous contactez le support.

Deux choses qui vous feront économiser

Gardez une clé d’idempotence par soumission. Réutilisez-la pour chaque renvoi, y compris après un dépassement de délai. Une réponse perdue ne prouve pas que la tâche n’a pas été créée : une clé neuve transforme un résultat inconnu en une seconde tâche payante. C’est exactement pour cela que CreateTask exige la clé. Voir Idempotence.

Une tâche qui réussit est facturée, même si le résultat déçoit. Quote ne réserve rien : demandez donc un devis d’abord quand le prix compte.

Ce que ce paquet ne fait pas

• Les modèles de texte. Ils parlent les formats réseau d’OpenAI, d’Anthropic et de Gemini : les clients Go établis pour ces formats fonctionnent déjà avec https://api.spicyapi.ai/v1 et la même clé. Voir Texte et streaming.
• Les applications côté client. N’embarquez jamais cette clé dans un binaire que vous distribuez. Appelez depuis votre serveur.
• Choisir un modèle ou remplir ses champs. Il vous fournit le catalogue et le schéma de chaque modèle ; c’est vous qui décidez quoi envoyer.
• Annuler une tâche. Une fois acceptée, une tâche va jusqu’au bout. Annuler le context n’arrête que votre attente.

Le code source

Le module est sous licence MIT et développé au grand jour sur github.com/spicyapi-ai/spicy-go. Son README est la visite guidée la plus courte et la plus complète du client ; cette page y ajoute les notions qui l’entourent.

Étapes suivantes