SDK TypeScript

@spicyapi/sdk est la bibliothèque officielle TypeScript et JavaScript de SpicyAPI. Cette page part du principe que vous ne l’avez jamais utilisée. Elle vous mène d’un dossier vide à une image enregistrée, puis décrit chaque fonction du paquet : à quoi elle sert, ce que vous lui passez, ce qu’elle renvoie, si elle coûte de l’argent et ce qui peut mal tourner.

Qu’est-ce que le SDK ?

Un SDK est une bibliothèque de code toute prête que vous ajoutez à votre propre programme. Sans lui, votre programme doit construire chaque requête HTTP à la main : joindre la clé API, transformer la réponse JSON en données, demander encore et encore si une tâche est terminée, réessayer quand le réseau coupe, téléverser les fichiers en trois étapes distinctes et vérifier la signature de chaque webhook. Le SDK fait tout cela pour vous, si bien qu’une génération complète tient en un seul appel :

const task = await client.run({ model: modelId, input: { prompt: "A paper lantern at night" } });

Il vous convient si vous écrivez, ou allez écrire, un programme Node.js (JavaScript ou TypeScript) qui s’exécute sur un serveur, dans un script sur votre propre ordinateur ou dans une tâche d’arrière-plan. Si vous utilisez TypeScript, vous bénéficiez en plus de l’autocomplétion et de la vérification des types pour chaque champ.

Est-ce le bon outil ?

Ce qu’il ne fait pas

• Il ne fonctionne ni dans un navigateur ni dans une application mobile. Il a besoin de Node.js, et votre clé API ne doit jamais quitter votre serveur : n’importe qui peut lire une clé dans une page web ou une application. Faites appeler votre propre backend par votre site, et laissez ce backend appeler SpicyAPI.
• Il ne gère pas les modèles de chat. La génération de texte passe par des points de terminaison compatibles OpenAI, et le paquet officiel openai le fait déjà très bien. Voir Texte et streaming.
• Il ne choisit pas le modèle et ne remplit pas les champs à votre place. Chaque modèle accepte ses propres champs. Le SDK vous fournit la liste des modèles et le schéma de chacun (la liste des champs qu’il accepte) ; c’est vous qui décidez quoi envoyer.
• Il ne peut pas annuler une tâche. Une fois qu’une tâche est acceptée par SpicyAPI, elle va jusqu’au bout. Arrêter votre programme n’arrête que votre attente.
• Il ne gère pas votre compte. Les recharges, la création de clés, les plafonds de dépense et les clés de signature des webhooks se règlent dans la console.

Vocabulaire de cette page

Ce que vous pouvez faire

Chaque fonction ci-dessous est une méthode du client (client.listModels()), sauf mention contraire. « Payant » signifie que l’appel peut entraîner un prélèvement sur votre solde.

Avant de commencer

Comptez une dizaine de minutes. Chaque étape explique ce que fait la commande, pour que rien ne s’exécute à l’aveugle.

node -v

mkdir spicy-demo
cd spicy-demo
npm init -y
npm pkg set type=module
npm install @spicyapi/sdk

# À définir pour cette fenêtre de terminal (collez votre propre clé)
export SPICY_API_KEY="sk-spicy-paste-your-key-here"

# Vérification : ceci doit afficher sk-spicy-
echo "${SPICY_API_KEY:0:9}"

import { SpicyClient } from "@spicyapi/sdk";

const client = new SpicyClient();
const status = await client.getStatus();

console.log(status.operational ? "SpicyAPI is up" : "SpicyAPI is not reachable right now");
console.log("Checked at", status.checkedAt);

node check.mjs

SpicyAPI is up
Checked at 2026-09-17T08:00:00.000Z

Votre premier résultat

Ce programme fait tout le parcours : il vérifie le service, choisit un modèle d’image que votre clé peut utiliser, demande le prix exact et s’arrête. Relancez-le avec --yes : il crée alors l’image, attend qu’elle soit prête et l’enregistre à côté du script.

import { randomUUID } from "node:crypto";
import { writeFile } from "node:fs/promises";
import { SpicyApiError, SpicyClient } from "@spicyapi/sdk";

// Lit votre clé dans la variable d’environnement SPICY_API_KEY.
const client = new SpicyClient();

async function main() {
  // Étape 1 — SpicyAPI est-il joignable ? Gratuit, et sans clé.
  const status = await client.getStatus();
  if (!status.operational) {
    throw new Error("SpicyAPI is not reachable right now. Try again in a few minutes.");
  }

  // Étape 2 — Quels modèles d’image cette clé peut-elle appeler ? Gratuit.
  const catalog = await client.listModels({ modality: "image", includeExamples: true });
  const model = catalog.items.find(
    (item) => item.enabled && item.available && item.examples?.length,
  );
  if (!model) throw new Error("No image model is available to this key right now.");
  console.log(`Model: ${model.displayName} (${model.model})`);

  // Étape 3 — Construire l’entrée. On part d’un exemple déjà validé par le serveur,
  // et on y met votre propre prompt si le modèle en accepte un.
  const input = { ...model.examples?.[0]?.input };
  if ("prompt" in input) input.prompt = "A paper lantern glowing on a rainy street at night";

  // Étape 4 — Demander le prix exact. Gratuit : rien n’est créé ni réservé.
  const request = { model: model.model, input };
  const quote = await client.quoteTask(request);
  console.log(`Price: $${quote.estimatedCost} USD`);

  if (!process.argv.includes("--yes")) {
    console.log("Nothing was charged. Run again with --yes to generate the image.");
    return;
  }

  // Étape 5 — Créer la tâche et l’attendre. C’est l’étape qui coûte de l’argent.
  const task = await client.run(
    { ...request, quoteId: quote.quoteId, expectedCost: quote.estimatedCost },
    {
      idempotencyKey: randomUUID(),
      onAccepted: (accepted) => console.log(`Task accepted: ${accepted.taskId}`),
      onUpdate: (update) => console.log(`State: ${update.state}`),
    },
  );

  // Étape 6 — Une tâche échouée reste une réponse normale. Vérifiez le règlement.
  if (task.state !== "succeeded") {
    console.log(`The task ended as ${task.state}: ${task.errorCode} ${task.errorMessage ?? ""}`);
    console.log("Check settled and cost for the final charge.");
    return;
  }

  // Étape 7 — Télécharger le résultat maintenant. Le lien expire au bout d’environ 20 minutes.
  const asset = task.output?.assets?.find((item) => item.url);
  if (!asset?.url) throw new Error("The task succeeded but its file is unavailable.");
  const download = await fetch(asset.url); // n’envoyez jamais votre clé API ici
  if (!download.ok) throw new Error(`Download failed with HTTP ${download.status}`);
  const extension = asset.mime?.split("/")[1] ?? "png";
  await writeFile(`result.${extension}`, Buffer.from(await download.arrayBuffer()));
  console.log(`Saved result.${extension}. Charged: $${task.cost}${task.settled ? "" : " (not final yet)"}`);
}

main().catch((error) => {
  if (error instanceof SpicyApiError) {
    console.error(`SpicyAPI error ${error.code}: ${error.message} (request_id ${error.requestId})`);
  } else {
    console.error(error);
  }
  process.exitCode = 1;
});

Lancez-le deux fois :

node first-result.mjs
node first-result.mjs --yes

Model: <display name> (<model ID>)
Price: $<amount> USD
Nothing was charged. Run again with --yes to generate the image.

Model: <display name> (<model ID>)
Price: $<amount> USD
Task accepted: job_…
State: running
State: succeeded
Saved result.png. Charged: $<amount>

Ce que fait chaque étape

1. getStatus() demande au point de terminaison de santé de SpicyAPI si le service fonctionne. Elle ne lève jamais d’erreur pour un problème réseau ; elle renvoie operational: false à la place.
2. listModels() renvoie le catalogue des modèles en direct (live catalog), avec les prix de votre compte. N’utilisez que les éléments dont enabled et available valent tous deux true. includeExamples: true ajoute des exemples d’entrées déjà validés par le serveur, le point de départ le plus sûr. La valeur que vous enverrez ensuite est le champ model de l’élément : l’identifiant de modèle.
3. L’entrée. Chaque modèle accepte des champs différents ; envoyer un champ que le modèle ne connaît pas est refusé avec l’erreur 400. Copier un exemple validé et ne changer que le prompt évite ce piège. Pour voir tous les champs qu’accepte un modèle, appelez getModel() et lisez son inputSchema.
4. quoteTask() calcule le prix de cette requête précise. Elle ne crée rien et ne réserve rien. Les montants sont des dollars américains écrits sous forme de texte, comme "0.04", pour éviter toute erreur d’arrondi.
5. run() crée la tâche, puis la surveille jusqu’à ce qu’elle se termine. Transmettre quoteId et expectedCost revient à dire « n’accepte cette tâche qu’au prix qu’on m’a montré » : si le prix a changé, l’appel échoue avec 40901 au lieu de facturer un autre montant. L’idempotencyKey rend sûre une nouvelle tentative après un problème réseau ; dans une vraie application, enregistrez-la avant l’appel, pour qu’un programme redémarré puisse la réutiliser. onAccepted vous donne l’identifiant de la tâche dès qu’elle existe : enregistrez-le, pour pouvoir consulter la tâche plus tard même si votre programme s’arrête.
6. L’état de la tâche. run() rend la main normalement, y compris pour les tâches échouées. Les tâches échouées ou expirées libèrent normalement toute la réservation. Certains refus de contenu sont facturés au devis accepté, uniquement si la page du modèle indique explicitement cette exception. Consultez settled et cost pour connaître le montant final.
7. Le téléchargement. Chaque résultat est fourni avec une url temporaire. Téléchargez-le sans votre clé API et gardez-en votre propre copie : le lien dure environ 20 minutes (rappelez getTask() pour en obtenir un nouveau), et SpicyAPI supprime les fichiers générés au bout d’environ 14 jours au plus. Voir Conservation et destruction.

La vidéo fonctionne de la même façon, mais peut prendre plusieurs minutes ; passez un timeoutMs plus long à run() (l’attente par défaut est de 10 minutes). Dans les extraits ci-dessous, l’identifiant de modèle apparaît sous la forme MODEL_ID_FROM_CATALOG : c’est un emplacement réservé, pas un vrai modèle. Remplacez-le par la valeur model d’un élément du catalogue en direct, obtenu avec listModels() dans le SDK ou avec le point de terminaison authentifié GET /api/v1/models, dont enabled et available valent tous deux true.

Référence de l’API

Chaque entrée ci-dessous indique à quoi sert la méthode, comment l’appeler, ce qu’elle renvoie, si elle peut coûter de l’argent et quelles erreurs attendre. Les classes d’erreur comme SpicyApiError sont expliquées dans Gérer les erreurs. Tous les montants sont des dollars américains écrits sous forme de texte ("0.04"), et toutes les dates sont des chaînes ISO 8601 en UTC.

Créer un client

new SpicyClient(options?: SpicyClientOptions)

La plupart des programmes ne passent rien : new SpicyClient() lit la clé dans SPICY_API_KEY et dialogue avec le service de production. Une option invalide lève immédiatement une TypeError, avant qu’aucune requête ne soit envoyée.

Nouvelles tentatives automatiques

Le SDK ne renvoie une requête de lui-même que lorsque cela ne peut pas vous coûter deux fois :

Une nouvelle tentative a lieu quand aucune réponse n’arrive (erreur réseau ou délai local dépassé) ou que la réponse est un HTTP 408, 429, 500, 502, 503 ou 504. La pause correspond à ce que demande l’en-tête Retry-After du serveur ; à défaut, 250 ms, puis 500 ms, puis 1 s, et ainsi de suite, chacune variant de 25 % au plus et plafonnée à maxRetryDelayMs. Si toutes les tentatives échouent, vous recevez la dernière erreur.

Arrêter un appel avec signal

Toutes les méthodes acceptent une option signal, un AbortSignal standard. Utilisez AbortSignal.timeout(5_000) pour fixer une échéance, ou un AbortController pour arrêter à la demande. L’appel lève alors la raison de l’interruption. Arrêter ne met fin qu’à votre requête ou à votre attente : une tâche déjà acceptée par SpicyAPI continue de s’exécuter et peut quand même être facturée.

getStatus()

Vérifie que SpicyAPI est joignable. Pratique en première ligne d’un script, ou comme vérification de santé dans votre propre supervision.

getStatus(options?: { signal?: AbortSignal }): Promise<ServiceStatus>

Payant : non. Clé requise : non. Erreurs : elle ne lève pas d’erreur pour les problèmes réseau ; vous obtenez operational: false et la cause dans health.error. Elle ne lève une erreur que si vous l’interrompez avec signal. Voir Lancer votre premier fichier pour un exemple.

listModels(options?)

Liste le catalogue des modèles en direct, avec les prix de votre compte. C’est de là que vient chaque identifiant de modèle.

listModels(options?: ListModelsOptions): Promise<ModelList>

Elle renvoie { total, items }. Les champs les plus utiles de chaque élément :

Payant : non. Clé requise : oui. Erreurs : SpicyApiError (par exemple 401 pour un problème de clé, 429 pour trop de requêtes), SpicyTransportError.

const { items } = await client.listModels({ modality: "video", task: "image-to-video" });

for (const item of items) {
  if (!item.enabled || !item.available) continue;
  const from = item.startingPrice ? `from $${item.startingPrice.price} ${item.startingPrice.unit}` : "";
  console.log(item.model, "|", item.displayName, "|", from);
}

Les lectures du catalogue utilisent le quota de lecture du compte, indépendamment de la création de tâches. Enregistrez la liste et rafraîchissez-la de temps en temps, ou après un 400 ou un 50301, plutôt que de la relire avant chaque tâche.

getModel(modelId)

Renvoie un modèle avec son schéma complet : la liste des champs d’entrée qu’il accepte, ceux qui sont obligatoires et les valeurs autorisées.

getModel(modelId: string, options?: { signal?: AbortSignal }): Promise<ApiModel>

Le résultat contient tous les champs décrits dans listModels, avec toujours inputSchema et examples. Le schéma est du JSON Schema standard : properties liste chaque champ avec son type et souvent enum (les valeurs autorisées), minimum / maximum et default ; required liste les champs que vous devez envoyer.

Payant : non. Clé requise : oui. Erreurs : SpicyApiError avec 404 quand aucun modèle ne porte cet identifiant ; TypeError si l’identifiant est vide.

const model = await client.getModel("MODEL_ID_FROM_CATALOG");

console.log("Required fields:", model.inputSchema?.required);
console.log(JSON.stringify(model.inputSchema?.properties, null, 2));
console.log("A request that is known to work:", model.examples?.[0]?.input);

quoteTask(request)

Donne le prix exact d’une requête sans rien créer. Servez-vous-en pour montrer un prix à quelqu’un, ou pour refuser un travail qui dépasse un budget.

quoteTask(request: { model: string; input: object; callBackUrl?: string }, options?: { signal?: AbortSignal }): Promise<TaskQuote>

Passez les mêmes model, input et callBackUrl facultative que ceux avec lesquels vous comptez créer la tâche.

Payant : non. Clé requise : oui. Erreurs : SpicyApiError, par exemple 400 quand l’entrée ne correspond pas au schéma du modèle, 50301 quand le modèle est indisponible, 429.

const request = { model: "MODEL_ID_FROM_CATALOG", input: { prompt: "A paper lantern at night" } };
const quote = await client.quoteTask(request);

console.log(`This will cost $${quote.estimatedCost}. Quote valid until ${quote.expiresAt}.`);

createTask(request, options?)

Lance une génération et rend la main immédiatement avec un identifiant de tâche. Elle n’attend pas le résultat : enchaînez avec waitForTask ou un webhook, ou utilisez run pour faire les deux en un seul appel.

createTask(request: CreateTaskInput, options?: CreateTaskOptions): Promise<CreateTaskResult>

La requête :

Les options :

Payant : oui. L’estimatedCost est réservé sur votre solde. Si la tâche réussit, vous êtes facturé selon l’usage réel, jamais plus que le montant réservé, et le reste est libéré. Les tâches échouées ou expirées libèrent normalement toute la réservation. Certains refus de contenu sont facturés au devis accepté, uniquement si la page du modèle indique explicitement cette exception. Consultez settled et cost pour connaître le montant final.

Erreurs :

Une SpicyTransportError ou une SpicyTimeoutError signifie qu’aucune réponse n’est arrivée : impossible de savoir si la tâche a été créée. Renvoyez la même requête avec la même clé d’idempotence : soit vous la créez, soit vous récupérez la tâche existante. Une TypeError signifie qu’une option était invalide (par exemple un retentionSeconds négatif) et que rien n’a été envoyé.

import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // dans une vraie application, enregistrez-la d’abord avec votre commande
const accepted = await client.createTask(
  { model: "MODEL_ID_FROM_CATALOG", input: { prompt: "A paper lantern at night" } },
  { idempotencyKey },
);

console.log(accepted.taskId, accepted.state, "on hold: $" + accepted.estimatedCost);

run(request, options?)

La façon la plus simple de générer quelque chose : elle appelle createTask, puis waitForTask, et renvoie la tâche terminée.

run(request: CreateTaskInput, options?: RunTaskOptions): Promise<TaskRecord>

request est identique à celle de createTask. Les options sont toutes celles qu’accepte createTask, plus :

Elle renvoie la tâche terminée, avec les champs décrits dans getTask. Pour une tâche réussie, elle attend aussi que la copie des fichiers de résultat soit terminée, pour que output.assets[].url soit prête à être téléchargée.

Payant : oui, exactement comme createTask. Une tâche échouée est renvoyée, pas levée comme erreur : vérifiez task.state.

Erreurs : tout ce que peut lever createTask, plus :

• SpicyWaitTimeoutError quand timeoutMs est écoulé après l’acceptation de la tâche. La tâche continue de s’exécuter chez SpicyAPI. Appelez plus tard waitForTask(error.taskId) pour la récupérer.
• SpicyTimeoutError quand le temps s’écoule avant que SpicyAPI ait confirmé la tâche. Renvoyez la même requête avec la même clé d’idempotence pour en avoir le cœur net.
• Toute erreur levée dans votre propre onAccepted ou onUpdate interrompt l’attente ; la tâche elle-même continue de s’exécuter.
• TypeError pour un timeoutMs ou un intervalMs invalide. Ces valeurs sont contrôlées avant toute création.

Voir Votre premier résultat pour un exemple complet.

getTask(taskId)

Consulte une tâche une fois : son état, ses liens de résultat et ce qu’elle a coûté.

getTask(taskId: string, options?: { signal?: AbortSignal }): Promise<TaskRecord>

Chaque élément de output.assets :

Un champ pour lequel SpicyAPI n’a pas de valeur est omis plutôt que mis à null : considérez donc chaque champ ci-dessus comme facultatif.

Payant : non. Erreurs : SpicyApiError avec 404 quand aucune tâche portant cet identifiant n’est visible pour votre clé.

const task = await client.getTask("job_01k3m8x9q2z4v7n5p6r8s0t1w3"); // l’identifiant que vous avez enregistré

if (task.state === "succeeded") {
  for (const asset of task.output?.assets ?? []) console.log(asset.mime, asset.url);
} else if (task.state === "queued" || task.state === "running") {
  console.log("Still working. On hold: $" + task.cost);
} else {
  console.log(`Finished as ${task.state}: ${task.errorCode}`);
}

waitForTask(taskId, options?)

Consulte une tâche à répétition jusqu’à ce qu’elle se termine, puis la renvoie. Utilisez-la pour une tâche créée précédemment, par exemple après le redémarrage de votre programme.

waitForTask(taskId: string, options?: WaitForTaskOptions): Promise<TaskRecord>

Options : timeoutMs (600000 par défaut, jusqu’à 86400000), intervalMs, onUpdate et signal, tous tels que décrits dans run.

Elle rend la main dès que state vaut succeeded, failed, expired ou canceled, et, pour une tâche réussie, dès qu’aucun fichier de résultat n’est plus pending. Chaque consultation est une requête getTask et compte dans la limite de débit de votre compte : c’est pourquoi l’intervalle par défaut s’allonge avec le temps.

Payant : non. Erreurs : SpicyWaitTimeoutError quand timeoutMs est écoulé. Elle contient taskId, timeoutMs et lastTask (le dernier état observé). La tâche n’est pas annulée ; vous pouvez simplement attendre de nouveau. Également SpicyApiError (par exemple 404) et SpicyTransportError.

const task = await client.waitForTask("job_01k3m8x9q2z4v7n5p6r8s0t1w3", {
  timeoutMs: 30 * 60_000,
  onUpdate: (update) => console.log(new Date().toISOString(), update.state),
});
console.log(task.state, task.output?.assets?.[0]?.url);

retryTask(taskId, options?)

Relance une tâche échouée, sous la forme d’une toute nouvelle tâche avec le même modèle et la même entrée. La tâche d’origine reste exactement telle qu’elle était, et la nouvelle pointe vers elle via sourceTaskId.

retryTask(taskId: string, options?: { idempotencyKey?: string; signal?: AbortSignal }): Promise<RetryTaskResult>

Elle fonctionne sur les tâches failed et expired (et les anciennes tâches canceled). Une tâche réussie ou encore en cours est refusée avec 409. Le prix, votre solde et les autorisations de la clé sont vérifiés de nouveau, et la nouvelle tâche reprend le réglage de conservation de la tâche d’origine.

Comme l’entrée est réutilisée telle quelle, une relance n’aide que si l’échec était temporaire. Lisez d’abord l’errorCode de la tâche d’origine : rate_limited, upstream_unavailable, timeout et upstream_failed justifient une relance après une pause ; generation_failed et invalid_asset demandent une requête modifiée, envoyée avec createTask ; content_rejected, invalid_request et unsupported_combination ne doivent pas être relancés sans modification. Voir Codes d’erreur courants et Erreurs.

Elle renvoie taskId (la nouvelle tâche), sourceTaskId (la tâche d’origine), state, estimatedCost et deadlineAt.

Payant : oui. La nouvelle tâche a sa propre réservation et est facturée séparément si elle réussit. Passez une idempotencyKey pour qu’exécuter deux fois votre code de relance ne crée qu’une seule relance.

Erreurs : 409 (la tâche ne peut pas être relancée), ainsi que les erreurs de solde, de plafond et de disponibilité listées dans createTask. Si l’entrée d’origine utilisait un fichier spicy:// téléversé, ce fichier n’est utilisable qu’un jour ; téléversez-le de nouveau et utilisez plutôt createTask.

Un exemple complet se trouve dans Relancer une tâche échouée.

listTasks(options?)

Liste les tâches créées avec cette clé API, des plus récentes aux plus anciennes, une page à la fois. Utile pour retrouver du travail après un redémarrage ou un webhook manqué.

listTasks(options?: ListTasksOptions): Promise<TaskList>

Elle renvoie items, hasMore et, quand il reste des pages, nextCursor. Chaque élément comporte taskId, model, state, cost, settled, createdAt, deadlineAt et completedAt. Les entrées, les résultats et les liens n’y figurent pas ; appelez getTask pour une tâche dont vous avez besoin.

Payant : non. Erreurs : SpicyApiError (par exemple 400 pour une plage de dates invalide), SpicyTransportError.

let cursor;
do {
  const page = await client.listTasks({
    from: "2026-09-01", // gardez les mêmes dates sur chaque page
    to: "2026-09-08",
    state: "failed",
    limit: 100,
    cursor,
  });
  for (const item of page.items) console.log(item.taskId, item.model, item.createdAt);
  cursor = page.hasMore ? page.nextCursor : undefined;
} while (cursor);

getBalance()

Indique combien d’argent contient votre compte.

getBalance(options?: { signal?: AbortSignal }): Promise<Balance>

Payant : non. Inutile de vérifier le solde avant chaque tâche : SpicyAPI le vérifie quand vous en créez une et répond 40201 s’il est insuffisant. Voir Facturation pour tous les champs de funding.

const balance = await client.getBalance();
console.log(`Available: $${balance.available} (on hold: $${balance.held})`);

getUsage(options?)

Indique ce que cette clé API a dépensé, regroupé par jour et par modèle.

getUsage(options?: { from?: string; to?: string; signal?: AbortSignal }): Promise<UsageReport>

from et to sont des dates UTC (YYYY-MM-DD) ; from est inclus, to ne l’est pas. Omettez les deux pour les sept derniers jours, aujourd’hui compris. La plage peut couvrir 92 jours au plus.

Payant : non. Ce rapport est plus lourd que les autres lectures : il est donc soumis à une limite supplémentaire de 30 requêtes par minute ; réservez-le aux rapports, pas à une boucle. Erreurs : SpicyApiError (429 au-delà de cette limite), SpicyTransportError.

const usage = await client.getUsage({ from: "2026-09-01", to: "2026-09-08" });
console.log(`${usage.totalCalls} tasks, $${usage.totalSpend} spent`);
for (const row of usage.models) console.log(row.model, row.calls, "$" + row.spend);

Téléverser des fichiers

Quand un modèle a besoin d’une image, d’une vidéo ou d’un son en entrée, vous pouvez placer directement dans le champ d’entrée un lien HTTPS public vers le fichier. Pour un fichier qui se trouve sur votre ordinateur, téléversez-le d’abord. Vous obtenez une adresse spicy://, que vous placez dans le champ d’entrée à la place. Le téléversement est gratuit.

• Images (JPEG, PNG, WebP, GIF) : jusqu’à 10 MiB.
• Vidéo (MP4, WebM) et audio (MP3, WAV) : jusqu’à 90 MiB et 600 secondes.
• Un modèle peut fixer une limite plus basse dans son schéma.
• Un fichier téléversé est utilisable pendant un jour, et uniquement par votre compte.

uploadFile(path, options?)

Téléverse un fichier depuis le disque.

uploadFile(path: string, options?: { contentType?: string; signal?: AbortSignal }): Promise<UploadedFile>

Le type de fichier est déduit de l’extension : .jpg, .jpeg, .png, .webp, .gif, .mp4, .webm, .mp3 ou .wav. Pour tout autre nom, passez contentType : image/jpeg, image/png, image/webp, image/gif, video/mp4, video/webm, audio/mpeg ou audio/wav.

Payant : non. Erreurs : TypeError quand le type ne peut pas être déduit (son message liste toutes les extensions reconnues : contentType is required unless the file extension is one of: gif, jpeg, jpg, png, webp, mp4, webm, mp3, wav) ; une erreur Node.js ENOENT quand le chemin est faux ; SpicyUploadError (avec status) quand le stockage a refusé les octets ou que le fichier dépasse la taille autorisée (413) ; SpicyApiError quand SpicyAPI a refusé le téléversement ; SpicyTimeoutError quand l’envoi a pris plus de temps que uploadTimeoutMs.

const file = await client.uploadFile("./photo.jpg");
console.log(file.uri, "can be used until", file.expiresAt);

uploadBytes(data, options)

Téléverse des octets que vous avez déjà en mémoire, comme un fichier qu’un utilisateur a envoyé à votre serveur. Un Buffer Node.js fonctionne.

uploadBytes(data: Uint8Array, options: { contentType: string; signal?: AbortSignal }): Promise<UploadedFile>

contentType est obligatoire. Le résultat et les erreurs sont les mêmes que pour uploadFile.

const response = await fetch("https://example.com/reference.png");
const bytes = new Uint8Array(await response.arrayBuffer());
const file = await client.uploadBytes(bytes, { contentType: "image/png" });

uploadBase64(value, options?)

Téléverse un fichier dont vous disposez sous forme de texte Base64 : soit une data URI comme data:image/png;base64,iVBOR…, soit du Base64 brut accompagné de contentType.

uploadBase64(value: string, options?: { contentType?: string; signal?: AbortSignal }): Promise<UploadedFile>

L’encodage et la taille sont d’abord vérifiés sur votre machine ; des données invalides ou trop volumineuses lèvent une TypeError sans rien téléverser. Le résultat est le même que pour uploadFile.

createUploadUrl et commitUploadedFile

Les trois fonctions ci-dessus reposent sur ces deux appels de plus bas niveau. Vous n’en avez besoin que pour envoyer les octets depuis un autre endroit que votre processus Node.js.

createUploadUrl(contentType: string, bytes: number, options?: { signal?: AbortSignal }): Promise<UploadTicket>
commitUploadedFile(fileId: string, options?: { signal?: AbortSignal }): Promise<UploadedFile>

1. createUploadUrl renvoie fileId, uploadUrl, method (PUT), headers, maxBytes et expiresAt.
2. Envoyez le fichier par un PUT vers uploadUrl, avec exactement les headers indiqués et sans en-tête Authorization. La taille déclarée doit correspondre au fichier.
3. commitUploadedFile(fileId) vérifie le fichier stocké et renvoie l’uri spicy://. Un fichier téléversé mais jamais validé ne peut pas être utilisé.

Le processus complet, téléversements depuis un navigateur compris, est décrit dans Médias.

createDownloadUrl(taskId, key?)

Crée un nouveau lien de téléchargement temporaire pour un fichier de résultat. Vous en aurez rarement besoin : getTask, waitForTask, run et les webhooks incluent déjà une url prête pour chaque résultat.

createDownloadUrl(taskId: string, key?: string, options?: { signal?: AbortSignal }): Promise<DownloadTicket>

Passez la key du fichier produit pour choisir un fichier, ou omettez-la pour obtenir le premier. Elle renvoie key, url et expiresAt (environ 20 minutes).

Payant : non. Erreurs : SpicyApiError avec 409 tant que le fichier est encore en cours de copie (attendez quelques secondes), ou 404 quand la tâche n’a pas réussi ou que la clé ne lui appartient pas.

purgeTask(taskId)

Supprime définitivement les médias générés, le résultat (les données de résultat stockées), le prompt et les autres textes d’entrée d’une tâche terminée, avant la fin de la durée de conservation. Utilisez-la quand un résultat ne doit pas être conservé.

purgeTask(taskId: string, options?: { signal?: AbortSignal }): Promise<PurgeTaskResult>

Payant : non, et ce n’est pas un remboursement. L’écriture comptable, le montant facturé, le modèle, l’état, les horodatages et l’identifiant de requête restent enregistrés. La suppression est irréversible. Rappeler la méthode sur la même tâche est sans risque. Erreurs : SpicyApiError avec 400 quand la tâche est encore queued ou running, 404 quand elle n’existe pas. Une tâche acceptée ne peut pas être annulée et aucune API d’annulation n’existe : attendez-la avec waitForTask, puis détruisez son contenu. Voir Conservation et destruction.

const result = await client.purgeTask("job_01k3m8x9q2z4v7n5p6r8s0t1w3");
console.log(result.contentState, "billing kept:", result.billingRetained);

Fonctions pour les webhooks

verifyWebhook et computeWebhookSignature sont des fonctions simples, pas des méthodes du client. Elles sont décrites, avec un exemple fonctionnel, dans Webhooks.

Utilitaires hors ligne et types

Ils fonctionnent sans connexion réseau et sans clé.

Les types TypeScript de chaque requête et de chaque réponse sont également exportés, par exemple import type { TaskRecord, ApiModel, Balance } from "@spicyapi/sdk".

Webhooks

Un webhook permet à SpicyAPI de vous prévenir quand une tâche est terminée, au lieu que votre programme pose la question toutes les quelques secondes. Vous donnez à chaque tâche une callBackUrl, une adresse sur votre propre serveur, et SpicyAPI y envoie l’enregistrement de la tâche terminée.

Pourquoi vérifier chaque webhook

L’adresse de votre webhook est une URL publique : quiconque la devine peut y envoyer un faux message du type « tâche réussie, voici le fichier ». Si votre code croit ce message, il risque de livrer le mauvais fichier à un client ou de marquer une commande comme terminée.

Chaque livraison authentique est signée avec une clé de signature secrète que seuls vous et SpicyAPI connaissez. verifyWebhook recalcule cette signature à partir des octets exacts que vous avez reçus et compare les deux. Elle vérifie aussi l’heure de livraison, pour qu’un attaquant ne puisse pas intercepter un message authentique et vous le renvoyer des heures plus tard. N’agissez sur un message qu’une fois cette vérification passée.

Mise en place

Un récepteur minimal

Ce récepteur n’utilise que le module http intégré à Node.js : il n’y a donc rien d’autre à installer. Enregistrez-le sous le nom receiver.mjs et lancez-le avec node receiver.mjs.

import { createServer } from "node:http";
import { SpicyWebhookVerificationError, verifyWebhook } from "@spicyapi/sdk/webhooks";

const secret = process.env.SPICY_WEBHOOK_SECRET;
if (!secret) throw new Error("Set SPICY_WEBHOOK_SECRET first");

// Identifiants des livraisons déjà traitées. En production, utilisez une table de base
// de données, pour que la liste survive à un redémarrage.
const handled = new Set();

const server = createServer(async (request, response) => {
  if (request.method !== "POST" || request.url !== "/hooks/spicy") {
    response.writeHead(404).end();
    return;
  }
  if (request.headers["x-webhook-payload-version"] !== "2") {
    response.writeHead(400).end();
    return;
  }

  // 1. Lire le corps sous forme d’octets bruts. Ne pas l’analyser avant la vérification.
  const chunks = [];
  for await (const chunk of request) chunks.push(chunk);
  const rawBody = Buffer.concat(chunks);

  // 2. Vérifier la signature et l’horodatage.
  let event;
  try {
    event = verifyWebhook({
      rawBody,
      secret,
      timestamp: String(request.headers["x-webhook-timestamp"] ?? ""),
      signature: String(request.headers["x-webhook-signature"] ?? ""),
      payloadVersion: 2,
    });
  } catch (error) {
    const reason = error instanceof SpicyWebhookVerificationError ? error.reason : String(error);
    console.warn("Rejected a webhook:", reason);
    response.writeHead(401).end();
    return;
  }

  // 3. Répondre vite. SpicyAPI attend 15 secondes au plus, puis réessaie.
  response.writeHead(204).end();

  // 4. Une même livraison peut arriver plusieurs fois. Ne traiter chacune qu’une fois.
  if (!event.deliveryId || handled.has(event.deliveryId)) return;
  handled.add(event.deliveryId);

  if (!("data" in event.payload)) return; // en version 2, le corps range la tâche sous data
  const task = event.payload.data; // les mêmes champs que ceux renvoyés par getTask()
  console.log("Task", task.taskId, "is", task.state);
  if (task.state === "succeeded") {
    console.log("Result:", task.output?.assets?.[0]?.url);
  }
});

server.listen(8080, () => console.log("Listening on http://localhost:8080/hooks/spicy"));

Les points importants :

• Des octets bruts. La signature porte sur les octets exacts envoyés par SpicyAPI. Si un framework analyse d’abord le JSON et que vous le reconvertissez en texte, les octets changent et chaque vérification échoue. Avec Express, utilisez express.raw({ type: "application/json" }) sur cette route.
• Répondre vite. Toute réponse 2xx signifie « reçu ». Sans réponse dans les 15 secondes, ou avec tout autre statut, SpicyAPI retente la livraison plusieurs fois au cours des heures suivantes. Faites le travail long après avoir répondu.
• Les doublons arrivent. Les nouvelles tentatives et les aléas du réseau peuvent livrer deux fois le même message. event.deliveryId reste identique d’une tentative à l’autre : mémorisez donc les identifiants déjà traités.
• La réussite se lit dans state. Une livraison pour une tâche échouée reste une livraison valide. Lisez task.state, jamais le code de l’enveloppe.
• En production, enregistrez d’abord l’événement vérifié dans votre base de données et ne répondez 2xx qu’une fois l’enregistrement réussi, et ignorez les identifiants de tâche que votre application n’a pas créés. Le guide Webhooks propose une version adossée à une base de données.

Tester votre récepteur avant la mise en production

computeWebhookSignature produit une vraie signature : vous pouvez donc vous envoyer une livraison de test signée. Avec receiver.mjs qui tourne dans un terminal et la même SPICY_WEBHOOK_SECRET définie dans un autre, lancez :

import { computeWebhookSignature } from "@spicyapi/sdk";

const secret = process.env.SPICY_WEBHOOK_SECRET;
if (!secret) throw new Error("Set SPICY_WEBHOOK_SECRET first");

const body = JSON.stringify({
  code: 200,
  msg: "success",
  request_id: "whd_local_test_1",
  data: {
    taskId: "job_local_test",
    state: "succeeded",
    cost: "0.01",
    settled: true,
    output: { assets: [{ url: "https://example.com/result.png" }] },
  },
});
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = computeWebhookSignature("job_local_test", timestamp, body, secret);

const response = await fetch("http://localhost:8080/hooks/spicy", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Webhook-Timestamp": timestamp,
    "X-Webhook-Signature": signature,
    "X-Webhook-Payload-Version": "2",
  },
  body,
});
console.log("Your receiver answered", response.status); // attendu : 204

Lancez-le deux fois : le récepteur n’affiche la tâche qu’une fois, car la seconde livraison a le même request_id. Modifiez un caractère de body après la signature, et le récepteur répond 401.

verifyWebhook(options)

verifyWebhook(options: VerifyWebhookOptions): VerifiedWebhook

Elle renvoie payload (le corps analysé ; en version 2, la tâche se trouve dans payload.data), payloadVersion, taskId, deliveryId (le request_id de la version 2, identique d’une tentative à l’autre) et timestamp. La fonction est synchrone : pas besoin d’await.

Quand la vérification échoue, elle lève une SpicyWebhookVerificationError, dont la reason vaut invalid_signature, stale_timestamp, invalid_timestamp, invalid_json, invalid_payload, body_too_large ou invalid_secret. Répondez 401 et n’agissez pas sur le message.

computeWebhookSignature(taskId, timestamp, rawBody, secret) renvoie la signature Base64 d’un corps. Vous n’en avez besoin que pour des tests comme celui ci-dessus. L’algorithme de signature complet, pour les autres langages, figure dans Webhooks.

Astuce TypeScript : payload est typé pour accepter l’un ou l’autre format. Affinez le type avec "data" in event.payload, comme le fait le récepteur, ou passez le type attendu : verifyWebhook<components["schemas"]["TaskRecordEnvelope"]>(…) avec import type { components } from "@spicyapi/sdk".

Gérer les erreurs

Les choses peuvent mal tourner de deux façons différentes, qui demandent chacune un traitement différent :

1. Un appel échoue. Le SDK lève une erreur : votre clé était mauvaise, votre solde était insuffisant, le réseau a coupé. Interceptez-la avec try / catch.
2. Une tâche échoue. L’appel a fonctionné, mais pas la génération. Aucune erreur n’est levée : la tâche renvoyée a state: "failed" et un errorCode. Les tâches échouées ou expirées libèrent normalement toute la réservation. Certains refus de contenu sont facturés au devis accepté, uniquement si la page du modèle indique explicitement cette exception. Consultez settled et cost pour connaître le montant final.

Les classes d’erreur

Décidez quoi faire d’après code, jamais d’après message : les messages s’adressent à des personnes, leur formulation peut changer et ils suivent le réglage de langue des erreurs de votre compte. Joignez toujours le requestId quand vous contactez l’assistance : il nous permet de retrouver la requête exacte.

import { randomUUID } from "node:crypto";
import {
  SpicyApiError,
  SpicyClient,
  SpicyTransportError,
  SpicyWaitTimeoutError,
} from "@spicyapi/sdk";

const client = new SpicyClient();
const MODEL_ID = "MODEL_ID_FROM_CATALOG"; // un vrai identifiant obtenu avec listModels()
if (MODEL_ID === "MODEL_ID_FROM_CATALOG") throw new Error("Replace MODEL_ID_FROM_CATALOG first");

const idempotencyKey = randomUUID(); // gardez-la : il vous faut la même pour réessayer

try {
  const task = await client.run(
    { model: MODEL_ID, input: { prompt: "A paper lantern on a rainy street" } },
    { idempotencyKey, onAccepted: ({ taskId }) => console.log("Task ID:", taskId) },
  );
  if (task.state === "succeeded") console.log("Done:", task.output?.assets?.[0]?.url);
  else console.log(`Finished as ${task.state} (${task.errorCode}). Cost: ${task.cost}; settled: ${task.settled}.`);
} catch (error) {
  if (error instanceof SpicyWaitTimeoutError) {
    // Votre attente est terminée, pas la tâche. Consultez-la plus tard avec le même identifiant.
    console.log(`Still running: ${error.taskId}. Call waitForTask() again later.`);
  } else if (error instanceof SpicyApiError) {
    console.log(`SpicyAPI said no: ${error.code} (HTTP ${error.status}) ${error.message}`);
    console.log(`Quote this if you contact support: ${error.requestId}`);
    if (error.code === 40201) console.log("Your balance is too low. Top up in the console.");
    if (error.code === 40202) console.log("A spend cap was reached. Raise it on the API keys page.");
    if (error.code === 429) console.log(`Too many requests. Wait ${error.retryAfterSeconds ?? 1} s.`);
  } else if (error instanceof SpicyTransportError) {
    // Panne réseau ou délai local dépassé : la tâche existe peut-être, peut-être pas.
    // Relancez la même requête avec la MÊME idempotencyKey pour le savoir sans risque.
    console.log(`Network problem (${error.message}). Retry with key ${idempotencyKey}.`);
  } else {
    throw error; // ici, une TypeError signale un bug dans l’appel lui-même, par exemple une clé manquante
  }
}

Codes d’erreur courants

Quand une tâche échoue, task.errorCode vaut invalid_request, unsupported_combination, content_rejected, rate_limited, upstream_unavailable, generation_failed, timeout, invalid_asset ou upstream_failed. retryTask renvoie l’entrée d’origine sans la modifier : choisissez donc l’étape suivante d’après le code :

Le tableau complet figure dans Erreurs.

Conserver vos résultats

• Une url de résultat fonctionne pendant environ 20 minutes. Rappelez getTask pour en obtenir une nouvelle.
• Les fichiers générés sont supprimés au bout d’environ 14 jours au plus, plus tôt si votre compte ou retentionSeconds le prévoit. Les fichiers d’entrée téléversés durent un jour, et les prompts stockés 30 jours.
• Téléchargez ce que vous voulez garder dans votre propre stockage dès qu’une tâche réussit. N’enregistrez pas l’url temporaire elle-même dans votre base de données. Détails : Conservation et destruction.

Recettes courantes

Les recettes utilisent MODEL_ID_FROM_CATALOG comme emplacement réservé. Avant d’en lancer une, remplacez-le par la valeur model d’un élément adapté du catalogue en direct (listModels() ou GET /api/v1/models) dont enabled et available valent tous deux true. Chaque recette s’arrête avec un message clair si vous oubliez.

Image vers vidéo : téléverser d’abord une image locale

import { randomUUID } from "node:crypto";
import { SpicyClient } from "@spicyapi/sdk";

const client = new SpicyClient();

// Remplacez par un identifiant de modèle image-to-video du catalogue en direct :
// await client.listModels({ modality: "video", task: "image-to-video" })
const MODEL_ID = "MODEL_ID_FROM_CATALOG";
if (MODEL_ID === "MODEL_ID_FROM_CATALOG") throw new Error("Replace MODEL_ID_FROM_CATALOG first");

// 1. Téléverser l’image locale. Gratuit. L’adresse spicy:// fonctionne pendant un jour.
const file = await client.uploadFile("./photo.jpg");
console.log("Uploaded:", file.uri);

// 2. Afficher le schéma du modèle : quel champ reçoit l’image, quels champs sont obligatoires.
const { inputSchema } = await client.getModel(MODEL_ID);
console.log(JSON.stringify(inputSchema, null, 2));

// 3. Créer la vidéo et l’attendre. Une vidéo prend souvent plusieurs minutes.
const task = await client.run(
  {
    model: MODEL_ID,
    input: {
      prompt: "Slow push-in, light rain, neon reflections on wet stone",
      image_url: file.uri, // utilisez le nom de champ indiqué par le schéma ci-dessus
    },
  },
  {
    idempotencyKey: randomUUID(),
    timeoutMs: 30 * 60_000,
    onAccepted: ({ taskId }) => console.log("Task ID (save it):", taskId),
  },
);

console.log(task.state, task.output?.assets?.[0]?.url ?? task.errorCode);

Le schéma affiché fait foi pour les noms de champs et les champs obligatoires ; un modèle vidéo peut aussi exiger une durée ou une résolution, et le prix en dépend souvent. Si votre image est déjà en ligne à une adresse HTTPS publique, sautez le téléversement et placez directement cette adresse dans le champ d’image. Lancez d’abord quoteTask avec la même requête si vous voulez voir le prix.

Lancer un lot en limitant la concurrence

Lancer des centaines de tâches d’un coup peut vous faire atteindre vos plafonds de dépense et votre limite de débit. Ce script traite une liste de prompts avec au plus deux tâches en cours à la fois.

import { SpicyApiError, SpicyClient } from "@spicyapi/sdk";

const client = new SpicyClient();

const MODEL_ID = "MODEL_ID_FROM_CATALOG"; // un vrai identifiant obtenu avec listModels()
if (MODEL_ID === "MODEL_ID_FROM_CATALOG") throw new Error("Replace MODEL_ID_FROM_CATALOG first");

// Changez le nom du lot chaque fois que vous changez les prompts.
const BATCH_NAME = "lanterns-2026-09-17";
const prompts = [
  "A paper lantern on a rainy street",
  "A paper lantern floating on a lake",
  "A paper lantern in a snowy forest",
  "A paper lantern above a night market",
];
const CONCURRENCY = 2; // nombre de tâches qui peuvent s’exécuter en même temps

const results = prompts.map((prompt) => ({ prompt, outcome: "not started", detail: "" }));
let nextIndex = 0;

async function worker() {
  while (nextIndex < prompts.length) {
    const index = nextIndex++;
    try {
      const task = await client.run(
        { model: MODEL_ID, input: { prompt: prompts[index] } },
        {
          // Même nom de lot + même position = même clé. Si le script plante et que vous
          // le relancez dans les 24 heures, vous récupérez les tâches existantes au lieu
          // de les payer deux fois.
          idempotencyKey: `${BATCH_NAME}-${index}`,
          timeoutMs: 20 * 60_000,
        },
      );
      results[index].outcome = task.state;
      results[index].detail = task.output?.assets?.[0]?.url ?? task.errorCode ?? "";
    } catch (error) {
      results[index].outcome = "error";
      results[index].detail = error instanceof Error ? error.message : String(error);
      // Solde épuisé (40201) ou plafond de dépense dépassé (40202) : ne plus lancer de nouvelles tâches.
      if (error instanceof SpicyApiError && (error.code === 40201 || error.code === 40202)) {
        nextIndex = prompts.length;
      }
    }
  }
}

await Promise.all(Array.from({ length: CONCURRENCY }, () => worker()));
console.table(results);

• Pourquoi les clés sont construites à partir du nom du lot. Une clé d’idempotence liée à « ce lot, élément 3 » fait qu’une nouvelle exécution après un plantage réutilise les tâches déjà créées. Une clé aléatoire à chaque exécution paierait de nouveau la même image.
• Pourquoi le nom du lot doit changer avec les prompts. Réutiliser une clé pour une requête différente est refusé avec 409.
• Choisir CONCURRENCY. Chaque tâche en cours réserve une partie de votre solde, et chaque consultation d’état compte dans la limite de débit de votre compte. Commencez petit et augmentez la valeur une fois que le lot tourne sans accroc.

Recevoir les résultats par webhook plutôt que par polling

Dans une application web ou un processus d’arrière-plan, attendre à l’intérieur d’une requête est du gaspillage. Créez la tâche avec une callBackUrl, enregistrez l’identifiant de la tâche, et laissez le récepteur traiter le résultat quand il arrive.

import { randomUUID } from "node:crypto";
import { SpicyClient } from "@spicyapi/sdk";

const client = new SpicyClient();
const MODEL_ID = "MODEL_ID_FROM_CATALOG"; // un vrai identifiant obtenu avec listModels()
if (MODEL_ID === "MODEL_ID_FROM_CATALOG") throw new Error("Replace MODEL_ID_FROM_CATALOG first");

// Dans une vraie application, enregistrez cette clé avec la commande du client avant l’appel.
const idempotencyKey = randomUUID();

const accepted = await client.createTask(
  {
    model: MODEL_ID,
    input: { prompt: "A paper lantern on a rainy street" },
    callBackUrl: "https://your-app.example.com/hooks/spicy",
  },
  { idempotencyKey },
);

console.log(`Accepted ${accepted.taskId}; $${accepted.estimatedCost} is on hold.`);
// Enregistrez accepted.taskId maintenant. Quand la tâche se termine, SpicyAPI appelle votre récepteur.

Gardez un filet de sécurité pour les livraisons qui n’arrivent jamais, par exemple parce que votre serveur était en panne pendant toutes les tentatives : de temps en temps, appelez getTask pour les tâches enregistrées qui ont largement dépassé leur deadlineAt sans webhook, ou parcourez listTasks. L’historique des livraisons de webhooks, avec un bouton pour renvoyer manuellement une livraison, se trouve sur la page Webhooks de la console.

Relancer une tâche échouée

import { SpicyClient } from "@spicyapi/sdk";

const client = new SpicyClient();

const taskId = process.argv[2]; // à lancer ainsi : node retry.mjs job_...
if (!taskId) throw new Error("Usage: node retry.mjs <taskId>");

// Une relance renvoie l’entrée d’origine sans la modifier : seuls les échecs temporaires en valent la peine.
// Pour tous les autres codes, modifiez la requête et utilisez plutôt createTask.
const WORTH_ONE_RETRY = new Set(["rate_limited", "upstream_unavailable", "timeout", "upstream_failed"]);

const source = await client.getTask(taskId);

if (
  (source.state !== "failed" && source.state !== "expired") ||
  !WORTH_ONE_RETRY.has(source.errorCode ?? "")
) {
  console.log(`Not retrying: the task is ${source.state} (${source.errorCode ?? "no error code"}).`);
} else {
  // Une clé fixe par tentative de relance : lancer ce script deux fois crée une relance, pas deux.
  const retry = await client.retryTask(source.taskId, {
    idempotencyKey: `retry-${source.taskId}-attempt-1`,
  });
  console.log(`New task ${retry.taskId}; $${retry.estimatedCost} is on hold.`);

  const finished = await client.waitForTask(retry.taskId, { timeoutMs: 20 * 60_000 });
  console.log("The retry finished as", finished.state);
}

Le script ne relance que les échecs qui peuvent se passer autrement la fois suivante (un service surchargé ou temporairement indisponible, un dépassement de délai ou une erreur inconnue), et une seule fois, avec une clé d’idempotence fixe. Pour invalid_asset, téléversez de nouveau le fichier et créez une nouvelle tâche, car la relance réutiliserait le téléversement expiré. Pour generation_failed, modifiez le prompt ou l’image et créez une nouvelle tâche. Pour content_rejected, invalid_request et unsupported_combination, modifiez la requête plutôt que de la relancer. Si l’unique relance échoue elle aussi, arrêtez-vous et examinez l’erreur ; pour un timeout répété, essayez une durée plus courte ou une résolution plus basse avec createTask. Voir Erreurs.

Dépannage et FAQ

Le code source

Le paquet est sous licence MIT et développé au grand jour sur github.com/spicyapi-ai/spicy-sdk. C’est là qu’on lit le code derrière chaque méthode de cette page, qu’on signale un comportement qui s’écarte de ce qui est décrit ici et qu’on propose une modification.

Étapes suivantes