Modelli e media

Questa pagina descrive il catalogo dei modelli e tutti gli endpoint multimediali. I modelli di chat sono quelli che passi come ai_model_id alle conversazioni e alle esecuzioni. Video, sintesi vocale, musica e trascrizione hanno ciascuno il proprio catalogo di modelli e seguono uno schema comune per i job.

Tutti i percorsi sono relativi a https://api.stickyprompts.com/api/v1 e ogni richiesta include Authorization: Bearer $STICKY_API_KEY.

Convenzioni

• ID e slug. Ogni generazione e ogni trascrizione ha un ID numerico e uno slug di 8 caratteri. GET /<resource>/:id e POST /<resource>/:id/retry accettano l’uno o l’altro. DELETE /<resource>/:id accetta solo l’ID numerico.
• I decimali sono stringhe. Prezzi e costi in crediti (credit_cost, credit_cost_per_*, multiplier) vengono restituiti come stringhe JSON, per esempio "0.000015".
• Maiuscole e minuscole nei campi. I record riportano ID, CreatedAt, UpdatedAt, DeletedAt in PascalCase accanto a campi in snake_case. Vedi Errori, paginazione e quote.
• Gli elenchi sono paginati con page (predefinito 1) e size (predefinito 10), dal più recente, con gli header X-Total-Count, X-Page e X-Page-Size. Il corpo è un semplice array.
• Quota. Le route che avviano lavoro a pagamento rispondono 429 {"error":"Quota exceeded","reason":"..."} quando il piano non ha più margine.
• Modelli soggetti a restrizioni. Se una regola del workspace blocca il modello che hai scelto, le chiamate di creazione rispondono 403 {"error":"the selected model has been restricted by your organization"}.

Modelli di chat

I modelli di chat sono identificati dal loro ID numerico. name è un nome visualizzato, non un identificatore. Con una chiave API vengono applicate le regole di Accesso a modelli e provider e la policy di Residenza dei dati del tuo workspace: i modelli che non puoi usare vengono restituiti con selectable: false e un restriction_reason.

GET /ai_model

Elenca il catalogo dei modelli di chat nell’ordine di visualizzazione. I modelli deprecati sono inclusi, a meno che tu non passi 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]));

Risposta 200 (è mostrato un solo elemento, con valori indicativi):

[
  {
    "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
  }
]

Campi utili: tools elenca le capacità (file_upload, file_generation, image_generation, web_search, web_fetch, code_execution, remote_mcp e altre), reasoning_efforts elenca i livelli di ragionamento consentiti, successor indica il modello che sostituisce un modello deprecato e supported_file_extensions limita gli allegati (se è vuoto, non c’è alcun limite). Il catalogo non contiene campi per la dimensione della finestra di contesto, il prezzo in USD o i benchmark.

GET /ai_model/:id

Restituisce un modello in base al suo ID numerico. Qui successor non viene caricato.

GET /ai_model/filters

Restituisce i valori distinti con cui puoi filtrare il catalogo:

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

Un elenco vale null anziché [] quando nessun modello ha un valore per quel filtro.

GET /ai_model/restricted

Deprecato. Segnala solo i modelli bloccati da una regola a livello di modello nel tuo workspace. Usa invece il flag selectable di GET /ai_model.

Generazione di immagini

La generazione di immagini è sincrona: la chiamata risponde quando l’immagine esiste. Il server usa il modello di immagini configurato da StickyPrompts; il prompt è l’unico parametro di controllo (non ci sono parametri per dimensioni, numero di immagini o proporzioni).

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);

Risposta 200, un record di file:

{
  "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’immagine si trova in path, un URL diretto dello storage. Conserva l’ID: funziona come file_id per la modifica, come fotogramma iniziale di un video e negli endpoint dei file. Nota fileType in camelCase.

Errori: 400 senza prompt; 500 {"error":"image generation produced no output file"} quando il modello non restituisce nulla; 500 con il messaggio di errore quando il modello non riesce o la residenza dei dati blocca il provider. Imposta un timeout del client generoso.

POST /image_generation/edit

Modifica un’immagine di tua proprietà e restituisce un nuovo file. Il file di origine non viene modificato.

Risposta 200: un nuovo record di file. 404 {"error":"file not found or access denied"} se il file non è tuo.

Job in background: video, voce, musica, trascrizione

Queste quattro risorse seguono uno schema comune:

1. Scegli un modello

   GET /<kind>_model restituisce il catalogo di quel tipo. Scegli un modello in base al suo ID numerico. Il flag default: true indica il modello preselezionato nell’app, ma l’API non lo usa come ripiego: invia sempre l’ID del modello.

2. Crea il job

   POST /<kind> convalida la richiesta, verifica quota e accesso e risponde 201 con il job in stato queued.

3. Interroga lo stato fino al completamento

   Chiama GET /<kind>/:id finché status non vale done o error. Per questi job non esistono webhook né stream di eventi: controlla lo stato ogni pochi secondi.

4. Recupera il risultato

   Video, voce e musica: il file si trova in output_file_data.path. Trascrizione: text e segments si trovano nel record stesso.

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);

Regole comuni a tutte e quattro:

• L’ID del modello è obbligatorio. Se lo ometti o invii un ID sconosciuto, ottieni un generico 500 "Failed to create ...", non un 400.
• Costo. GET /<kind>/:id include credit_cost, i crediti addebitati per il job. Nelle risposte di elenco questo campo vale sempre "0".
• Residenza dei dati. Se la policy di residenza del tuo workspace vieta il provider del modello, il job viene accettato e poi fallisce con il messaggio della policy in error. Questi modelli compaiono nel catalogo con selectable: false, quindi verifica prima.
• Nuovo tentativo. POST /<kind>/:id/retry rimette in coda un job in stato error (altrimenti 400 "Only failed ... can be retried"), verificando di nuovo accesso e quota.
• Eliminazione. DELETE /<kind>/:id (ID numerico) restituisce 204, anche quando non trova nulla. È un’eliminazione logica (soft delete) e non rimuove il file di output.
• Filtra gli elenchi con ?status=<value>.

Ogni modello multimediale ha ID, name, powered_by, version, description, multiplier, default, sort, selectable e, quando pertinente, restriction_reason. I cataloghi non sono paginati.

Generazione di video

Stati: queued, poi processing, poi done o error.

GET /video_generation_model

I modelli video aggiungono: supported_aspect_ratios (se è vuoto, qualsiasi proporzione), supported_resolutions (la prima è quella predefinita), resolution_duration_limits (per risoluzione, con "*" come ripiego, {min_duration_seconds, max_duration_seconds} dove 0 significa senza limite), resolution_pricing (credit_cost_per_second per risoluzione), interpolation_support (none, start_only o full), max_reference_images e 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
  }'

Risposta 201 (abbreviata):

{
  "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"
}

Quando lo stato è done, output_file_data.path è il file .mp4 e actual_duration_seconds e credit_cost sono valorizzati. content_policy_violation: true significa che il filtro di sicurezza del provider ha rifiutato la richiesta.

Gli errori di convalida sono 400 con un messaggio preciso, per esempio "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" o "attached file must be an image". Se usi il file di qualcun altro ottieni 403 "you do not have permission to use this file".

GET /video_generation, GET /video_generation/:id

Elenca i tuoi job video (page, size, status) o recuperane uno per ID o slug, credit_cost compreso. 404 {"error":"Video generation not found"}.

POST /video_generation/:id/retry

DELETE /video_generation/:id

Sintesi vocale

Stati: queued, poi processing, poi done o error.

GET /tts_generation_model

I modelli di sintesi vocale aggiungono supported_languages (se è vuoto, qualsiasi lingua) e un tts_voice_set le cui voices hanno ciascuna un voice_id (il valore da inviare come voice), name, gender, language, accent, description, preview_audio_url e default.

POST /tts_generation

Risponde 201 con il job. Quando lo stato è done, l’audio (.wav o .mp3, a seconda di ciò che ha restituito il provider) si trova in output_file_data.path. Errori: 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

Generazione di musica

Stati: queued, poi processing, poi done o error.

GET /music_generation_model

I modelli musicali aggiungono min_duration_seconds e max_duration_seconds (0 significa senza limite), supported_output_formats (il primo è quello predefinito), credit_cost_per_generation e credit_cost_per_second.

POST /music_generation

Quando lo stato è done, il brano si trova in output_file_data.path e gli eventuali testi in lyrics. L’estensione del file corrisponde a ciò che il provider ha effettivamente restituito, quindi può essere diversa da output_format. Errori: 400 per una durata fuori dai limiti o per un formato non supportato.

GET /music_generation, GET /music_generation/:id

POST /music_generation/:id/retry

DELETE /music_generation/:id

Trascrizione

Stati: queued, fetching, preparing, processing, poi done o error. status_progress va da 0 a 100; avanza a scatti solo per i modelli che elaborano l’audio a blocchi.

GET /transcription_model

I modelli di trascrizione aggiungono response_format (solo i modelli diarized_json etichettano i parlanti), supported_languages e i prezzi in crediti per token e per secondo.

POST /transcription

Questa route non accetta upload multipart: carica prima l’audio o il video con POST /file, oppure fornisci un URL. Per i file video, la traccia audio viene estratta automaticamente.

Un record completato (abbreviato):

{
  "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"
}

I segmenti adiacenti dello stesso parlante vengono uniti, e una pausa di due secondi o più compare come segmento a sé, con un valore pause e text vuoto. speaker vale null per i modelli che non distinguono i parlanti.

Errori: 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

Elenca le tue trascrizioni (page, size, status) o recuperane una per ID o slug, credit_cost compreso. Non inviare all’elenco un parametro di query workspace_id.

PATCH /transcription/:id/speakers

Rinomina i parlanti o cambiane il colore, come fai con Speakers nell’app. Cambiano solo i campi che invii; un’etichetta sconosciuta viene aggiunta come nuovo parlante.

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

Restituisce 200 con la trascrizione completa.

POST /transcription/:id/retry

DELETE /transcription/:id

Statistiche di utilizzo

Le route /statistics/* e /credits/* richiedono statistics_get, un’autorizzazione che può concedere solo lo staff di StickyPrompts. Le chiavi dei clienti non possono chiamarle. L’utilizzo del tuo workspace è disponibile nell’app, come descritto in Utilizzo, crediti e fatturazione, e ogni job multimediale riporta il proprio credit_cost.

Pagine correlate