SDK officiels
Des SDK officiels pour cinq langages
Installez un paquet et appelez les modèles d’image, de vidéo et d’audio depuis votre propre serveur. Le SDK gère l’authentification et l’attente des résultats : vous n’écrivez que la requête et lisez la réponse.
Ce que le SDK fait pour vous
Vous écrivez un seul appel de fonction. Le SDK signe la requête, envoie vos fichiers, attend le résultat et vous le rend sous forme de données typées.
- Votre codeUn seul appel de fonction
- SDK officielSigne les requêtes, envoie les fichiers, attend les résultats
- Modèles d’image, de vidéo et d’audioMêmes modèles et mêmes tarifs que sur le site
Idéal pour
- Services backendGénérez des médias au sein de votre propre API ou file de tâches.
- Scripts et traitements par lotsCréez de nombreuses tâches depuis un tableur ou un job planifié.
- Applis avec serveurGardez la clé côté serveur et envoyez les fichiers terminés à vos utilisateurs.
Démarrez en trois étapes
- Étape 1
Créez une clé API
Générez-en une dans la console et stockez-la sous SPICY_API_KEY sur votre serveur.
- Étape 2
Installez le paquet
Choisissez votre langage ci-dessous et lancez la ligne d’installation.
- Étape 3
Créez une tâche, lisez le résultat
Envoyez un prompt, attendez la tâche, puis enregistrez le fichier renvoyé.
Choisissez votre langage
Chaque SDK est publié sur le registre principal de son langage et s’appuie sur la même API. Changez d’onglet pour voir la ligne d’installation et une requête complète.
TypeScript
@spicyapi/sdkNécessite Node.js 22.13+
Votre serveur crée les tâches et stocke les résultats. Installer, exporter la clé, exécuter.
npm install @spicyapi/sdk
export SPICY_API_KEY="injected from your secret manager"import { randomUUID } from "node:crypto";
import { SpicyClient } from "@spicyapi/sdk";
const client = new SpicyClient();
const model = await client.getModel("MODEL_ID_FROM_CATALOG");
const task = await client.run(
{ model: model.model, input: { prompt: "A cinematic night portrait" } },
{ idempotencyKey: randomUUID() },
);
console.log(task.state, task.output?.assets?.[0]?.url);Python
spicyapiNécessite Python 3.11+
Le même enchaînement, écrit en Python : estimation du prix, création, attente de l’état final.
pip install spicyapi
export SPICY_API_KEY="injected from your secret manager"import uuid
from spicyapi import SpicyClient, output_assets
client = SpicyClient() # reads SPICY_API_KEY from the environment
model = client.get_model("MODEL_ID_FROM_CATALOG")
quote = client.quote_task(
model=model["model"],
input_data={"prompt": "A cinematic night portrait"},
)
print(quote["estimatedCost"], quote["maxCharge"]) # decide before you spend
task = client.create_task(
model=model["model"],
input_data={"prompt": "A cinematic night portrait"},
idempotency_key=str(uuid.uuid4()),
quote_id=quote["quoteId"],
expected_cost=quote["estimatedCost"],
)
final = client.wait_for_terminal(task["taskId"])
for asset in output_assets(final):
print(asset["url"])Go
github.com/spicyapi-ai/spicy-goNécessite Go 1.23+
Bibliothèque standard uniquement : rien de neuf n’entre dans votre graphe de modules. Disponible tout de suite avec go get.
go get github.com/spicyapi-ai/spicy-go
export SPICY_API_KEY="injected from your secret manager"client, err := spicy.New(spicy.Options{}) // reads SPICY_API_KEY from the environment
if err != nil {
return err
}
request := spicy.CreateTaskInput{
Model: "MODEL_ID_FROM_CATALOG",
Input: map[string]any{"prompt": "A cinematic night portrait"},
}
quote, err := client.Quote(ctx, request)
if err != nil {
return err
}
request.QuoteID = quote.QuoteID
request.ExpectedCost = quote.EstimatedCost
// Store this next to your own record of the job before sending it: its whole
// purpose is to still be there after the crash that lost the response.
key, err := spicy.NewIdempotencyKey()
if err != nil {
return err
}
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)
}PHP
spicyapi/spicyapiNécessite PHP 8.1+, ext-json, ext-hash
Tableaux associatifs et arguments nommés, sans la moindre dépendance.
composer require spicyapi/spicyapiuse SpicyApi\SpicyClient;
$client = new SpicyClient(); // reads SPICY_API_KEY from the environment
$quote = $client->quote('MODEL_ID_FROM_CATALOG', ['prompt' => 'A cinematic night portrait']);
printf("at most %s\n", $quote['maxCharge']); // decide before you spend
$task = $client->createTask(
model: $quote['model'],
input: ['prompt' => 'A cinematic night portrait'],
idempotencyKey: SpicyClient::idempotencyKey(),
quoteId: $quote['quoteId'],
expectedCost: $quote['estimatedCost'],
);
$final = $client->waitForTerminal($task['taskId']);
foreach (SpicyClient::readyAssets($final) as $asset) {
echo $asset['url'], "\n";
}Java
ai.spicyapi:spicyapi-java:0.1.0Nécessite Java 17+, Jackson
Des records et Jackson ; run() enchaîne création et attente.
<dependency>
<groupId>ai.spicyapi</groupId>
<artifactId>spicyapi-java</artifactId>
<version>0.1.0</version>
</dependency>SpicyClient client = SpicyClient.builder().apiKeyFromEnvironment().build();
CreateTaskRequest request = CreateTaskRequest.of(
"MODEL_ID_FROM_CATALOG",
Map.of("prompt", "A cinematic night portrait"));
TaskQuote quote = client.quote(request); // free; reserves nothing
System.out.println("this will cost at most " + quote.maxCharge());
TaskRecord task = client.run( // createTask + waitForTerminal
request.withQuote(quote), UUID.randomUUID().toString());
// Transcription and similar endpoints answer in text and return no files at all.
task.outputText().ifPresent(System.out::println);
for (TaskAsset asset : task.assets()) {
asset.url().ifPresent(System.out::println);
}Ce qui se passe après l’envoi
La génération d’images et de vidéos se poursuit après la réponse à l’appel de création. Enregistrez l’ID de la tâche, puis laissez un webhook ou une vérification de statut limitée dans le temps vous dire quand c’est terminé.
- createTaskEnvoyez avec une clé d’idempotence : une même génération n’est acceptée qu’une fois.
- taskIdLa réponse revient immédiatement pendant que la tâche continue.
- Webhook / recordInfoPrivilégiez un webhook signé ; gardez un polling limité pour la récupération.
- output.assetsDes URL directement exploitables. Copiez ce que vous voulez conserver.
Appeler depuis un navigateur ou une appli mobile
Une clé placée dans une appli cliente est une clé publique. Gardez-la sur votre serveur : @spicyapi/proxy ajoute l’identifiant aux requêtes de votre front-end, et l’appli ne le voit jamais.
- Clé dans l’appliN’importe qui peut la lire et dépenser votre solde.
- Appli avec la clé à l’intérieur
- SpicyAPI
- Clé sur votre serveurL’appli parle à votre serveur, et le proxy ajoute la clé.
- Navigateur ou téléphone
- Votre serveur + proxy
- SpicyAPI
npm install @spicyapi/proxy// app/api/spicy/proxy/route.ts
export { GET, POST } from "@spicyapi/proxy/nextjs";
export const runtime = "nodejs";Avant la mise en ligne
- 01Confirmer la disponibilité actuelle du modèle.
- 02Valider les champs exacts de sa fiche.
- 03Garder la clé API côté serveur.
- 04Afficher l’estimation avant l’envoi.
- 05Conserver l’ID de tâche hors de la session du navigateur.
- 06Vérifier la signature webhook ou la limite des vérifications.
- 07Traiter toute tâche acceptée comme non annulable.
Corriger les erreurs courantes
La plupart des problèmes du début sont l’un de ces trois-là. Chaque carte montre ce que vous voyez et l’unique chose à changer.
- 401
Clé API invalide
L’API n’a reçu aucune clé valide. Définissez SPICY_API_KEY dans le même environnement que celui qui exécute votre code.
- attente
Tâche toujours en cours
Une vidéo peut prendre quelques minutes. Attendez avec une limite de temps ou utilisez un webhook. Renvoyer sans la même Idempotency-Key crée une seconde tâche payante.
- lien
Lien de résultat expiré
Les liens de téléchargement sont éphémères. Demandez un nouveau lien pour la tâche plutôt que de conserver l’ancien.
