Modèles et médias

Cette page couvre le catalogue des modèles et tous les endpoints média. Les modèles de chat sont ceux que vous passez en ai_model_id aux conversations et aux exécutions. La vidéo, la voix, la musique et la transcription ont chacune leur propre catalogue de modèles et suivent un même schéma de tâches.

Tous les chemins sont relatifs à https://api.stickyprompts.com/api/v1, et chaque requête porte Authorization: Bearer $STICKY_API_KEY.

Conventions

• ID et slugs. Chaque génération et chaque transcription possède un ID numérique et un slug de 8 caractères. GET /<resource>/:id et POST /<resource>/:id/retry acceptent l’un ou l’autre. DELETE /<resource>/:id n’accepte que l’ID numérique.
• Les décimaux sont des chaînes. Les prix et coûts en crédits (credit_cost, credit_cost_per_*, multiplier) sont renvoyés sous forme de chaînes JSON, comme "0.000015".
• Casse des champs. Les enregistrements présentent ID, CreatedAt, UpdatedAt, DeletedAt en PascalCase à côté de champs en snake_case. Voir Erreurs, pagination et quotas.
• Les listes sont paginées avec page (par défaut 1) et size (par défaut 10), les éléments les plus récents en premier, avec les headers X-Total-Count, X-Page et X-Page-Size. Le corps est un simple tableau.
• Quota. Les routes qui lancent un travail facturé répondent 429 {"error":"Quota exceeded","reason":"..."} lorsque l’abonnement a atteint sa limite.
• Modèles soumis à restriction. Si une règle de l’espace de travail bloque le modèle choisi, les appels de création répondent 403 {"error":"the selected model has been restricted by your organization"}.

Modèles de chat

Les modèles de chat sont identifiés par leur ID numérique. name est un nom d’affichage, pas un identifiant. Avec une clé API, les règles d’accès aux modèles et la politique de résidence des données de votre espace de travail s’appliquent : les modèles que vous ne pouvez pas utiliser sont renvoyés avec selectable: false et un restriction_reason.

GET /ai_model

Liste le catalogue des modèles de chat dans l’ordre d’affichage. Les modèles obsolètes sont inclus, sauf si vous passez legacy=false.

curl "https://api.stickyprompts.com/api/v1/ai_model?legacy=false&flagship=true" \
  -H "Authorization: Bearer $STICKY_API_KEY"

import os, requests

r = requests.get(
    "https://api.stickyprompts.com/api/v1/ai_model",
    params={"legacy": "false", "flagship": "true"},
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
)
usable = [m for m in r.json() if m["selectable"]]
for m in usable:
    print(m["ID"], m["name"], m["multiplier"])

const res = await fetch(
  "https://api.stickyprompts.com/api/v1/ai_model?legacy=false&flagship=true",
  { headers: { Authorization: `Bearer ${process.env.STICKY_API_KEY}` } },
);
const models = (await res.json()).filter((m) => m.selectable);
console.log(models.map((m) => [m.ID, m.name]));

Réponse 200 (un seul élément affiché, valeurs données à titre d’illustration) :

[
  {
    "ID": 42,
    "name": "Claude Sonnet 5",
    "description": "Balanced model for everyday work.",
    "powered_by": "Anthropic",
    "version": "claude-sonnet-x",
    "multiplier": "1.6",
    "credit_cost_per_input_token": "0.0003",
    "credit_cost_per_output_token": "0.0015",
    "flagship": true,
    "premium": false,
    "deprecated": false,
    "thinking_model": true,
    "reasoning_efforts": ["low", "medium", "high"],
    "default_reasoning_effort": "medium",
    "tools": ["file_upload", "web_search", "remote_mcp"],
    "tags": ["analysis", "coding"],
    "best_for": "Writing, analysis and code",
    "knowledge_cutoff": "2026-01-01T00:00:00Z",
    "supported_file_extensions": [],
    "successor": null,
    "selectable": true
  }
]

Champs utiles : tools liste les capacités (file_upload, file_generation, image_generation, web_search, web_fetch, code_execution, remote_mcp, etc.), reasoning_efforts liste les niveaux de raisonnement autorisés, successor indique le modèle qui remplace un modèle obsolète, et supported_file_extensions restreint les pièces jointes (une liste vide signifie aucune restriction). Le catalogue ne comporte aucun champ de taille de fenêtre de contexte, de prix en USD ni de benchmark.

GET /ai_model/:id

Renvoie un modèle à partir de son ID numérique. successor n’est pas chargé ici.

GET /ai_model/filters

Renvoie les valeurs distinctes selon lesquelles vous pouvez filtrer le catalogue :

{
  "powered_by": ["Anthropic", "Google", "OpenAI", "xAI"],
  "tools": ["code_execution", "file_upload", "image_generation", "web_search"],
  "tags": ["analysis", "coding", "creative_writing", "reasoning"]
}

Une liste vaut null plutôt que [] lorsqu’aucun modèle n’a de valeur pour ce critère.

GET /ai_model/restricted

Obsolète. Ne signale que les modèles bloqués par une règle portant sur un modèle précis dans votre espace de travail. Utilisez plutôt l’indicateur selectable de GET /ai_model.

Génération d’images

La génération d’images est synchrone : l’appel rend la main une fois l’image créée. Le serveur utilise le modèle d’image configuré par StickyPrompts ; le prompt est le seul levier de contrôle (pas de paramètre de taille, de nombre d’images ni de format).

POST /image_generation

curl -X POST https://api.stickyprompts.com/api/v1/image_generation \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Product photo of a laptop on an oak desk showing a retail dashboard with yellow charts, morning light"}'

import os, requests

r = requests.post(
    "https://api.stickyprompts.com/api/v1/image_generation",
    headers={"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"},
    json={"prompt": "Product photo of a laptop on an oak desk showing a retail dashboard"},
    timeout=180,
)
image = r.json()
print(image["ID"], image["path"])

const res = await fetch("https://api.stickyprompts.com/api/v1/image_generation", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STICKY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ prompt: "Product photo of a laptop on an oak desk showing a retail dashboard" }),
});
const image = await res.json();
console.log(image.ID, image.path);

Réponse 200, un enregistrement de fichier :

{
  "ID": 9812,
  "name": "image_0.png",
  "path": "https://<storage-host>/<bucket>/123/Xk3...q9.png",
  "user_id": 123,
  "fileType": "code_interpreter_output",
  "partial": false
}

L’image se trouve à path, une URL de stockage directe. Conservez l’ID : il sert de file_id pour la retouche, de première image d’une vidéo, et dans les endpoints de fichiers. Notez le fileType en camelCase.

Erreurs : 400 sans prompt ; 500 {"error":"image generation produced no output file"} lorsque le modèle ne renvoie rien ; 500 avec le message d’erreur lorsque le modèle échoue ou que la résidence des données bloque le fournisseur. Prévoyez un délai d’expiration généreux côté client.

POST /image_generation/edit

Retouche une image qui vous appartient et renvoie un nouveau fichier. Le fichier source n’est pas modifié.

Réponse 200 : un nouvel enregistrement de fichier. 404 {"error":"file not found or access denied"} si le fichier ne vous appartient pas.

Tâches en arrière-plan : vidéo, voix, musique, transcription

Ces quatre ressources suivent le même schéma :

1. Choisir un modèle

   GET /<kind>_model renvoie le catalogue de ce type de ressource. Choisissez un modèle par son ID numérique. L’indicateur default: true signale le modèle présélectionné dans l’application, mais l’API ne s’y rabat pas : envoyez toujours l’ID du modèle.

2. Créer la tâche

   POST /<kind> valide la requête, vérifie le quota et les accès, puis répond 201 avec la tâche en statut queued.

3. Interroger jusqu'à la fin

   Appelez GET /<kind>/:id jusqu’à ce que status vaille done ou error. Il n’existe ni webhook ni flux d’événements pour ces tâches ; interrogez l’API toutes les quelques secondes.

4. Récupérer le résultat

   Vidéo, voix et musique : le fichier se trouve à output_file_data.path. Transcription : text et segments figurent dans l’enregistrement lui-même.

import os, time, requests

API = "https://api.stickyprompts.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['STICKY_API_KEY']}"}

job = requests.post(f"{API}/music_generation", headers=H, json={
    "music_generation_model_id": 7,          # from GET /music_generation_model
    "prompt": "Upbeat product-launch track, electric piano, 112 BPM, no vocals",
    "duration_seconds": 30,
    "instrumental": True,
}).json()

while job["status"] not in ("done", "error"):
    time.sleep(5)
    job = requests.get(f"{API}/music_generation/{job['slug']}", headers=H).json()

print(job["status"], job.get("output_file_data", {}).get("path"), job["credit_cost"])

const API = "https://api.stickyprompts.com/api/v1";
const H = { Authorization: `Bearer ${process.env.STICKY_API_KEY}`, "Content-Type": "application/json" };

let job = await (await fetch(`${API}/music_generation`, {
  method: "POST",
  headers: H,
  body: JSON.stringify({
    music_generation_model_id: 7, // from GET /music_generation_model
    prompt: "Upbeat product-launch track, electric piano, 112 BPM, no vocals",
    duration_seconds: 30,
    instrumental: true,
  }),
})).json();

while (!["done", "error"].includes(job.status)) {
  await new Promise((r) => setTimeout(r, 5000));
  job = await (await fetch(`${API}/music_generation/${job.slug}`, { headers: H })).json();
}
console.log(job.status, job.output_file_data?.path, job.credit_cost);

Règles communes aux quatre ressources :

• L’ID du modèle est obligatoire. L’omettre ou envoyer un ID inconnu renvoie un 500 "Failed to create ..." générique, et non un 400.
• Coût. GET /<kind>/:id inclut credit_cost, les crédits facturés pour la tâche. Les réponses de liste y affichent toujours "0".
• Résidence des données. Si la politique de résidence de votre espace de travail interdit le fournisseur du modèle, la tâche est acceptée puis échoue, avec le message de la politique dans error. Ces modèles apparaissent avec selectable: false dans le catalogue : vérifiez donc au préalable.
• Nouvelle tentative. POST /<kind>/:id/retry remet en file d’attente une tâche en statut error (sinon 400 "Only failed ... can be retried"), en revérifiant les accès et le quota.
• Suppression. DELETE /<kind>/:id (ID numérique) renvoie 204, y compris lorsque rien ne correspond. Il s’agit d’une suppression logique, qui n’efface pas le fichier produit.
• Filtrez les listes avec ?status=<value>.

Chaque modèle média possède ID, name, powered_by, version, description, multiplier, default, sort, selectable et, le cas échéant, restriction_reason. Les catalogues ne sont pas paginés.

Génération de vidéos

Statut : queued, puis processing, puis done ou error.

GET /video_generation_model

Les modèles vidéo ajoutent : supported_aspect_ratios (une liste vide signifie tous les formats), supported_resolutions (la première est la valeur par défaut), resolution_duration_limits (par résolution, avec "*" comme valeur de repli, sous la forme {min_duration_seconds, max_duration_seconds}, où 0 signifie sans limite), resolution_pricing (credit_cost_per_second par résolution), interpolation_support (none, start_only ou full), max_reference_images et reference_types.

POST /video_generation

curl -X POST https://api.stickyprompts.com/api/v1/video_generation \
  -H "Authorization: Bearer $STICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_generation_model_id": 4,
    "prompt": "Slow dolly shot across a bright retail store at opening time, warm morning light",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration_seconds": 8
  }'

Réponse 201 (extrait) :

{
  "ID": 311,
  "slug": "a8Kd02Lq",
  "video_generation_model_id": 4,
  "prompt": "Slow dolly shot across a bright retail store at opening time, warm morning light",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration_seconds": 8,
  "status": "queued",
  "error": "",
  "content_policy_violation": false,
  "output_file_data_id": null,
  "credit_cost": "0"
}

Une fois la tâche en done, output_file_data.path pointe vers le .mp4, et actual_duration_seconds et credit_cost sont renseignés. content_policy_violation: true signifie que le filtre de sécurité du fournisseur a refusé la requête.

Les erreurs de validation renvoient 400 avec un message précis, par exemple "resolution is not supported by this video generation model", "requested duration exceeds this video generation model's maximum", "a last frame image requires a starting image" ou "attached file must be an image". Utiliser le fichier d’une autre personne renvoie 403 "you do not have permission to use this file".

GET /video_generation, GET /video_generation/:id

Listez vos tâches vidéo (page, size, status) ou récupérez-en une par ID ou slug, credit_cost compris. 404 {"error":"Video generation not found"}.

POST /video_generation/:id/retry

DELETE /video_generation/:id

Synthèse vocale

Statut : queued, puis processing, puis done ou error.

GET /tts_generation_model

Les modèles de synthèse vocale ajoutent supported_languages (une liste vide signifie toutes les langues) et un tts_voice_set dont chaque élément de voices comporte un voice_id (la valeur à envoyer dans voice), name, gender, language, accent, description, preview_audio_url et default.

POST /tts_generation

Répond 201 avec la tâche. Une fois celle-ci en done, l’audio (.wav ou .mp3, selon ce que le fournisseur a renvoyé) se trouve à output_file_data.path. Erreurs : 400 "voice is not supported by this tts generation model", 400 "language is not supported by this tts generation model".

GET /tts_generation, GET /tts_generation/:id

POST /tts_generation/:id/retry

DELETE /tts_generation/:id

Génération de musique

Statut : queued, puis processing, puis done ou error.

GET /music_generation_model

Les modèles de musique ajoutent min_duration_seconds et max_duration_seconds (0 signifie sans limite), supported_output_formats (le premier est la valeur par défaut), credit_cost_per_generation et credit_cost_per_second.

POST /music_generation

Une fois la tâche en done, le morceau se trouve à output_file_data.path et les éventuelles paroles dans lyrics. L’extension du fichier suit ce que le fournisseur a réellement renvoyé : elle peut donc différer de output_format. Erreurs : 400 pour une durée hors limites ou un format non pris en charge.

GET /music_generation, GET /music_generation/:id

POST /music_generation/:id/retry

DELETE /music_generation/:id

Transcription

Statut : queued, fetching, preparing, processing, puis done ou error. status_progress va de 0 à 100 ; il n’avance par paliers que pour les modèles qui traitent l’audio par morceaux.

GET /transcription_model

Les modèles de transcription ajoutent response_format (seuls les modèles diarized_json identifient les intervenants), supported_languages et des prix en crédits par token et par seconde.

POST /transcription

Cette route n’accepte pas d’envoi multipart : envoyez d’abord le fichier audio ou vidéo avec POST /file, ou fournissez une URL. Pour les fichiers vidéo, la piste audio est extraite automatiquement.

Un enregistrement terminé (extrait) :

{
  "ID": 77,
  "slug": "Qm7tR2xa",
  "status": "done",
  "status_progress": 100,
  "text": "Hi team, quick update before Tuesday's launch...",
  "segments": [
    { "start": 0.0, "end": 28.4, "text": "Hi team, quick update before Tuesday's launch...", "speaker": "speaker_0" },
    { "start": 29.0, "end": 37.0, "text": "Thanks Darian. One question from support...", "speaker": "speaker_1" }
  ],
  "speakers": [
    { "label": "speaker_0", "name": "", "color": "#F59E0B" },
    { "label": "speaker_1", "name": "", "color": "#10B981" }
  ],
  "language": "en",
  "duration_seconds": 42.1,
  "credit_cost": "4.22"
}

Les segments consécutifs d’un même intervenant sont fusionnés, et un silence de deux secondes ou plus apparaît comme un segment à part entière, avec une valeur pause et un text vide. speaker vaut null pour les modèles qui ne distinguent pas les intervenants.

Erreurs : 400 "Either file_data_id or source_url is required", 400 "Can't set both file_data_id and source_url", 400 "language is not supported by this transcription model".

GET /transcription, GET /transcription/:id

Listez vos transcriptions (page, size, status) ou récupérez-en une par ID ou slug, credit_cost compris. N’envoyez pas de paramètre de requête workspace_id à la liste.

PATCH /transcription/:id/speakers

Renomme les intervenants ou change leur couleur, comme le fait Speakers dans l’application. Seuls les champs envoyés sont modifiés ; un libellé inconnu est ajouté comme nouvel intervenant.

{
  "speakers": {
    "speaker_0": { "name": "Darian", "color": "#3B82F6" },
    "speaker_1": { "name": "Sam" }
  }
}

Renvoie 200 avec la transcription complète.

POST /transcription/:id/retry

DELETE /transcription/:id

Statistiques d’utilisation

Les routes /statistics/* et /credits/* nécessitent statistics_get, une autorisation que seul le personnel de StickyPrompts peut accorder. Les clés des clients ne peuvent donc pas les appeler. L’utilisation de votre espace de travail est consultable dans l’application (voir Utilisation, crédits et facturation), et chaque tâche média indique son propre credit_cost.

Voir aussi