Modelos y multimedia

Esta página trata el catálogo de modelos y todos los endpoints multimedia. Los modelos de chat son los que indicas como ai_model_id en las conversaciones y las ejecuciones. El vídeo, la voz, la música y la transcripción tienen cada uno su propio catálogo de modelos y siguen un mismo patrón de trabajos.

Todas las rutas son relativas a https://api.stickyprompts.com/api/v1 y todas las solicitudes llevan Authorization: Bearer $STICKY_API_KEY.

Convenciones

• IDs y slugs. Cada generación y cada transcripción tiene un ID numérico y un slug de 8 caracteres. GET /<resource>/:id y POST /<resource>/:id/retry aceptan cualquiera de los dos. DELETE /<resource>/:id solo acepta el ID numérico.
• Los decimales son cadenas. Los precios y costes en créditos (credit_cost, credit_cost_per_*, multiplier) se devuelven como cadenas JSON, por ejemplo "0.000015".
• Mayúsculas en los campos. Los registros muestran ID, CreatedAt, UpdatedAt y DeletedAt en PascalCase junto a campos en snake_case. Consulta Errores, paginación y cuotas.
• Las listas se paginan con page (1 de forma predeterminada) y size (10 de forma predeterminada), del elemento más reciente al más antiguo, con los headers X-Total-Count, X-Page y X-Page-Size. El cuerpo es un array sin envoltorio.
• Cuota. Las rutas que inician trabajo de pago responden 429 {"error":"Quota exceeded","reason":"..."} cuando el plan no tiene margen.
• Modelos restringidos. Si una regla del espacio de trabajo bloquea el modelo que has elegido, las llamadas de creación responden 403 {"error":"the selected model has been restricted by your organization"}.

Modelos de chat

Los modelos de chat se identifican por su ID numérico. name es un nombre para mostrar, no un identificador. Con una clave de API se aplican las reglas de acceso a modelos y la política de residencia de datos de tu espacio de trabajo: los modelos que no puedes usar se devuelven con selectable: false y un restriction_reason.

GET /ai_model

Lista el catálogo de modelos de chat en el orden de visualización. Los modelos obsoletos se incluyen, salvo que envíes 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]));

Respuesta 200 (se muestra un elemento; los valores son ilustrativos):

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

Campos útiles: tools enumera las capacidades (file_upload, file_generation, image_generation, web_search, web_fetch, code_execution, remote_mcp y más), reasoning_efforts enumera los niveles de razonamiento permitidos, successor indica qué modelo sustituye a uno obsoleto y supported_file_extensions restringe los adjuntos (vacío significa sin restricción). El catálogo no incluye ningún campo de tamaño de la ventana de contexto, precio en USD ni resultados de benchmarks.

GET /ai_model/:id

Devuelve un modelo por su ID numérico. Aquí no se carga successor.

GET /ai_model/filters

Devuelve los distintos valores por los que puedes filtrar el catálogo:

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

Una lista es null, y no [], cuando ningún modelo tiene un valor para ella.

GET /ai_model/restricted

Obsoleto. Solo informa de los modelos bloqueados por una regla a nivel de modelo en tu espacio de trabajo. Usa en su lugar el indicador selectable de GET /ai_model.

Generación de imágenes

La generación de imágenes es síncrona: la llamada responde cuando la imagen ya existe. El servidor usa el modelo de imagen que StickyPrompts tiene configurado; el prompt es el único control (no hay parámetros de tamaño, cantidad ni relación de aspecto).

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

Respuesta 200, un registro de archivo:

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

La imagen está en path, una URL directa del almacenamiento. Guarda el ID: sirve como file_id para editar, como fotograma inicial de un vídeo y en los endpoints de archivos. Atención a fileType, en camelCase.

Errores: 400 sin prompt; 500 {"error":"image generation produced no output file"} cuando el modelo no devuelve nada; 500 con el mensaje correspondiente cuando el modelo falla o la residencia de datos bloquea al proveedor. Configura un tiempo de espera generoso en el cliente.

POST /image_generation/edit

Edita una imagen de la que eres propietario y devuelve un archivo nuevo. El archivo de origen no se modifica.

Respuesta 200: un registro de archivo nuevo. 404 {"error":"file not found or access denied"} si el archivo no es tuyo.

Trabajos en segundo plano: vídeo, voz, música y transcripción

Estos cuatro recursos comparten un mismo patrón:

1. Elige un modelo

   GET /<kind>_model devuelve el catálogo de ese tipo. Elige un modelo por su ID numérico. El indicador default: true marca el modelo que la aplicación preselecciona, pero la API no lo usa como alternativa: envía siempre el ID del modelo.

2. Crea el trabajo

   POST /<kind> valida la solicitud, comprueba la cuota y el acceso, y responde 201 con el trabajo en estado queued.

3. Consulta hasta que termine

   Llama a GET /<kind>/:id hasta que status sea done o error. Estos trabajos no tienen webhooks ni streams de eventos; consulta cada pocos segundos.

4. Recoge el resultado

   Vídeo, voz y música: el archivo está en output_file_data.path. Transcripción: text y segments están en el propio registro.

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

Reglas comunes a los cuatro:

• El ID del modelo es obligatorio. Si lo omites o envías un ID desconocido, recibes un 500 "Failed to create ..." genérico, no un 400.
• Coste. GET /<kind>/:id incluye credit_cost, los créditos cobrados por el trabajo. Las respuestas de listado siempre muestran "0" en ese campo.
• Residencia de datos. Si la política de residencia de tu espacio de trabajo no permite al proveedor del modelo, el trabajo se acepta y después falla con el mensaje de la política en error. Esos modelos aparecen con selectable: false en el catálogo, así que compruébalo antes.
• Reintento. POST /<kind>/:id/retry vuelve a poner en cola un trabajo en estado error (en otro caso, 400 "Only failed ... can be retried") y comprueba de nuevo el acceso y la cuota.
• Eliminación. DELETE /<kind>/:id (ID numérico) devuelve 204, también cuando no coincide nada. Es una eliminación lógica (soft delete) y no borra el archivo de salida.
• Filtra las listas con ?status=<value>.

Todos los modelos multimedia tienen ID, name, powered_by, version, description, multiplier, default, sort, selectable y, cuando corresponde, restriction_reason. Los catálogos no están paginados.

Generación de vídeo

Estado: queued, después processing y, por último, done o error.

GET /video_generation_model

Los modelos de vídeo añaden: supported_aspect_ratios (vacío significa cualquiera), supported_resolutions (la primera es la predeterminada), resolution_duration_limits (por resolución, con "*" como valor de reserva, {min_duration_seconds, max_duration_seconds}, donde 0 significa sin límite), resolution_pricing (credit_cost_per_second por resolución), interpolation_support (none, start_only o full), max_reference_images y 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
  }'

Respuesta 201 (abreviada):

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

Cuando el estado es done, output_file_data.path es el .mp4 y se rellenan actual_duration_seconds y credit_cost. content_policy_violation: true significa que el filtro de seguridad del proveedor rechazó la solicitud.

Los errores de validación son 400 con un mensaje preciso, por ejemplo "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". Usar el archivo de otra persona devuelve 403 "you do not have permission to use this file".

GET /video_generation, GET /video_generation/:id

Lista tus trabajos de vídeo (page, size, status) u obtén uno por ID o slug, con su credit_cost. 404 {"error":"Video generation not found"}.

POST /video_generation/:id/retry

DELETE /video_generation/:id

Texto a voz

Estado: queued, después processing y, por último, done o error.

GET /tts_generation_model

Los modelos de voz añaden supported_languages (vacío significa cualquiera) y un tts_voice_set cuyas voices tienen cada una un voice_id (el valor que se envía como voice), name, gender, language, accent, description, preview_audio_url y default.

POST /tts_generation

Responde 201 con el trabajo. Cuando el estado es done, el audio (.wav o .mp3, según lo que haya devuelto el proveedor) está en output_file_data.path. Errores: 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

Generación de música

Estado: queued, después processing y, por último, done o error.

GET /music_generation_model

Los modelos de música añaden min_duration_seconds y max_duration_seconds (0 significa sin límite), supported_output_formats (el primero es el predeterminado), credit_cost_per_generation y credit_cost_per_second.

POST /music_generation

Cuando el estado es done, la pista está en output_file_data.path y la letra, si la hay, en lyrics. La extensión del archivo corresponde a lo que el proveedor devolvió realmente, así que puede no coincidir con output_format. Errores: 400 si la duración está fuera de los límites o el formato no es compatible.

GET /music_generation, GET /music_generation/:id

POST /music_generation/:id/retry

DELETE /music_generation/:id

Transcripción

Estado: queued, fetching, preparing, processing y, por último, done o error. status_progress va de 0 a 100; solo avanza por etapas en los modelos que procesan el audio por fragmentos.

GET /transcription_model

Los modelos de transcripción añaden response_format (solo los modelos diarized_json identifican a los hablantes), supported_languages y precios en créditos por token y por segundo.

POST /transcription

Esta ruta no admite subidas multipart: sube antes el audio o el vídeo con POST /file, o indica una URL. En los archivos de vídeo, la pista de audio se extrae automáticamente.

Un registro terminado (abreviado):

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

Los segmentos contiguos del mismo hablante se fusionan, y una pausa de dos segundos o más aparece como un segmento propio con un valor pause y text vacío. speaker es null en los modelos que no separan a los hablantes.

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

Lista tus transcripciones (page, size, status) u obtén una por ID o slug, con su credit_cost. No envíes un parámetro de consulta workspace_id al listado.

PATCH /transcription/:id/speakers

Cambia el nombre o el color de los hablantes, igual que con Speakers en la aplicación. Solo cambian los campos que envías; una etiqueta desconocida se añade como un hablante nuevo.

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

Devuelve 200 con la transcripción completa.

POST /transcription/:id/retry

DELETE /transcription/:id

Estadísticas de uso

Las rutas /statistics/* y /credits/* requieren statistics_get, un permiso que solo puede conceder el personal de StickyPrompts. Las claves de los clientes no pueden llamarlas. El uso de tu espacio de trabajo está disponible en la aplicación, como se explica en Uso, créditos y facturación, y cada trabajo multimedia informa de su propio credit_cost.

Contenido relacionado