Guía de producción: panel, MCP y API
Cómo se hace cada tarea de la pantalla Producción en el panel, en clientes MCP como Claude o ChatGPT y con la API REST: presupuesto → confirmación → producción → estado → descarga, recetas, precios y créditos, límites, códigos de error y consentimiento para el avatar de una persona real.
Tres vías, las mismas reglas
- Panel: la pantalla Producción (
/uretim). Elige una tarjeta, completa el formulario y usa "Ver el precio" y "Confirmar y producir". - MCP: en Claude, ChatGPT y otros asistentes la dirección del conector es
https://tecrube.com/mcp. Usted describe lo que quiere y el asistente llama a las herramientas de abajo. - API REST: los endpoints
https://tecrube.com/api/v1/production/...con la cabeceraAuthorization: Bearer tk_.... El panel usa los mismos endpoints. - Las tres vías llaman a las mismas funciones internas: precio, control de créditos, reserva de saldo, límite mensual, límites de frecuencia y validaciones son idénticos. No existe una vía más barata o sin reglas por MCP o por la API.
Inventario de funciones
Cada función de la pantalla Producción y sus equivalentes. Los parámetros y créditos de las herramientas se generan desde el código en la página Herramientas de producción; los esquemas de los endpoints están en la referencia OpenAPI.
| Función | En el panel | Herramienta MCP | Endpoint REST |
|---|---|---|---|
| Tipos, recetas, niveles de calidad y precios | Formulario de nueva producción | get_production_options | GET /production/overview · GET /production/formats |
| Sugerencias de frase de apertura (hook) | Formulario › Sugerencias de apertura | suggest_production_hooks | POST /production/hooks |
| Presupuesto: qué, por cuánto, hasta cuándo | Ver el precio | quote_production | POST /production/quotes |
| Variaciones (2–4) | Formulario › Número de variaciones | quote_production variations | POST /production/quotes/batch |
| Leer un presupuesto | Tarjeta del presupuesto | get_production_quote | GET /production/quotes/{id} |
| Iniciar un presupuesto confirmado | Confirmar y producir | start_production | POST /production/jobs · POST /production/jobs/batch |
| Generación simple en un paso (sin confirmación) | — | generate_content | — |
| Biblioteca: búsqueda, filtros, paginación | Pestaña Producciones | list_productions | GET /production/jobs |
| Todo sobre una producción | Tarjeta de producción | list_productions production_id | GET /production/jobs/{id} |
| Cancelar un trabajo en cola | Tarjeta › Cancelar | cancel_production | POST /production/jobs/{id}/cancel |
| Reintentar un trabajo fallido con los mismos ajustes | Tarjeta › Reintentar | retry_production | POST /production/jobs/{id}/retry |
| Favorito | Tarjeta › Estrella | set_production_favorite | PUT /production/jobs/{id}/favorite |
| Eliminar (también varios) | Tarjeta › Eliminar · Seleccionar › Eliminar seleccionados | delete_production | DELETE /production/jobs/{id} |
| Descarga (PNG / JPG / WEBP) | Tarjeta › Descargar | get_production_download | GET /production/jobs/{id}/download |
| Empezar desde una página de producto | Empezar desde una página de producto | import_production_from_url | POST /production/import-url |
| Subir su propia imagen | Subir imagen | upload_production_image | POST /production/assets |
| Adaptar a formatos publicitarios | Tarjeta › Adaptar a formatos | adapt_production_formats | POST /production/jobs/{id}/formats |
| Revisión previa a la publicación | Tarjeta › Revisión previa | production_preflight | GET /production/jobs/{id}/preflight |
| Copia máster para TV / TV conectada | Tarjeta › Calidad de emisión | get_production_masters · create_production_master · delete_production_master | GET / POST /production/jobs/{id}/masters · DELETE /production/masters/{id} |
| Escenas del vídeo de marca y nuevo montaje | Tarjeta › Editar escenas | get_production_film · edit_production_film | GET /production/jobs/{id}/film · POST /production/jobs/{id}/film/edit |
| Regenerar una sola escena | Escenas › Regenerar esta escena | quote_production recipe: scene | POST /production/quotes recipe: scene |
| Producir más como este | Resultado publicitario › Más como este | quote_production like_production_id | GET /production/jobs/{id} → POST /production/quotes (hook, angle) |
| Enlace de revisión, decisión y comentarios | Tarjeta › Compartir | create_production_share · get_production_share · revoke_production_share | POST / GET / DELETE /production/jobs/{id}/share |
| Personajes (influencer IA, avatar IA) | Pestaña Personajes | get_production_options topic: characters · create_production_character · delete_production_character | GET / POST /production/characters · DELETE /production/characters/{id} |
| Saldo, créditos y movimientos | Recuadro de saldo | get_production_wallet | GET /production/wallet · GET /production/wallet/ledger |
| Límite de gasto mensual | Saldo › Límite mensual | set_production_monthly_limit | PUT /production/wallet/limit |
| Añadir una producción a una campaña | Chat · creatividades de la campaña | add_production_to_campaign | POST /production/jobs/{id}/campaign |
| Resultado publicitario y mejor variación | Tarjeta › Resultado publicitario · Variaciones | list_productions (performance, batch_result, review) | GET /production/jobs (performance, batch_result, review) |
Tipos y recetas
Cinco tipos básicos y ocho recetas listas; todas se piden con quote_production (MCP) y POST /production/quotes (REST). La receta es el campo recipe.
| Receta | Qué obtiene | Tipo (`kind`) | Necesita |
|---|---|---|---|
| — | Tipos básicos: imagen, vídeo corto, vídeo UGC, locución, guion. | image · short_video · ugc_video · voice · script | brief |
product | Imagen o vídeo a partir de una foto de producto; el producto se mantiene y cambia la escena (style). | image · short_video · ugc_video | reference_id, style |
edit | Nueva versión de un archivo listo; brief es el cambio que se quiere. | image · short_video · ugc_video | reference_id, brief |
persona | Retrato con IA para guardarlo como personaje. | image | brief |
influencer | Contenido coherente con un personaje virtual guardado. | image · short_video · ugc_video | character_id (virtual) |
avatar | Contenido con el personaje de una persona real con consentimiento. | image · short_video · ugc_video | character_id (real) |
film | Vídeo de marca de varias escenas con subtítulos y tarjeta de cierre con su logotipo. | short_video | scenes, captions, end_card |
scene | Una escena de un vídeo listo; solo se cobra esa escena, scene: 1 + hook cambia solo la apertura. | short_video | reference_id, scene, hook |
dubbing | Un vídeo listo en otro idioma. | short_video · ugc_video | reference_id, language |
pack | Formatos publicitarios a partir de una imagen principal y, si se quiere, un vídeo corto. | image | formats, video |
De principio a fin con MCP
Basta con lenguaje natural; el asistente trabaja en este orden.
- Opciones:
get_production_optionslee tipos, niveles y precios (sin cifras inventadas). - Presupuesto:
quote_productiondevuelve qué se producirá y el precio. No se produce nada ni se gastan créditos. - Confirmación: el asistente le muestra el precio y espera su aprobación.
- Inicio: cuando usted confirma,
start_productioninicia el presupuesto; el importe se reserva en este paso. - Estado y archivo:
list_productionsda el estado y la dirección del archivo listo;get_production_downloadcrea una dirección de descarga en el tipo que quiera.
Ejemplo de petición: "Haz un cartel de otoño 4:5 en tonos cálidos para mi cafetería. Dime primero el precio y prodúcelo si lo apruebo."
// quote_production
{ "kind": "image", "brief": "Autumn coffee campaign poster, warm tones", "aspect": "4:5", "tier": "balanced" }
// result (nothing produced or charged yet)
{ "ok": true, "status": "awaiting_confirmation", "started": false,
"quote": { "quote_id": "6f0c…", "kind": "image", "pricing": "credits", "price": { "credits": 24 },
"credits_remaining": 5810, "enough_credits": true, "expires_at": "2026-11-18T10:30:00+00:00" },
"confirm_with": { "tool": "start_production", "arguments": { "quote_id": "6f0c…" } } }// start_production — only after the user confirmed the price
{ "quote_id": "6f0c…" }
// → { "ok": true, "production_id": "a1b2…", "status": "queued", … }
// list_productions — repeat until status is "ready"
{ "production_id": "a1b2…" }
// → { "items": [ { "id": "a1b2…", "status": "ready", "url": "https://tecrube.com/medya/…", "file": { "width": 1080, "height": 1350 } } ] }
// get_production_download — a JPG copy at a signed address that expires
{ "production_id": "a1b2…", "format": "jpg" }Ejemplos de recetas (argumentos MCP)
// From a product page: page facts + the main image into the library
{ "url": "https://shop.example.com/product/123", "confirm_rights": true } // import_production_from_url
// Product video from that photo, three variations (the total price comes back)
{ "kind": "short_video", "recipe": "product", "reference_id": "<image id>", "brief": "…", "variations": 3 } // quote_production
// Dub a ready video into German
{ "kind": "short_video", "recipe": "dubbing", "reference_id": "<video id>", "language": "de" } // quote_production
// "More like this": the winner's settings, a new aspect
{ "like_production_id": "<winner id>", "aspect": "9:16" } // quote_productionDe principio a fin con la API REST
El mismo flujo con curl. El id de la respuesta del presupuesto es el id del presupuesto; el id de la respuesta de POST /production/jobs es el id de la producción.
API=https://tecrube.com/api/v1
KEY=tk_your_key
# 1) Quote — nothing is produced or charged (Idempotency-Key returns the same quote on retry)
curl -X POST $API/production/quotes \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: autumn-poster-1" \
-d '{"kind":"image","brief":"Autumn coffee campaign poster, warm tones","aspect":"4:5","tier":"balanced"}'
# → {"id":"<quote_id>","mode":"credits","credits":24,"price_usd":0,"expires_at":"…",…}
# 2) Confirm and start (the same quote_id never starts a second production)
curl -X POST $API/production/jobs \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"quote_id":"<quote_id>"}'
# 3) Status — repeat until "status":"ready" (running jobs carry "eta")
curl $API/production/jobs/<job_id> -H "Authorization: Bearer $KEY"
# 4) Download as JPG (png | jpg | webp; images only)
curl -o poster.jpg "$API/production/jobs/<job_id>/download?format=jpg" -H "Authorization: Bearer $KEY"Ejemplos de otros endpoints
# Library: search, filter, paginate
curl "$API/production/jobs?q=autumn&kind=image&status=ready&favorite=true&limit=20&offset=0" -H "Authorization: Bearer $KEY"
# Variations: 2–4 quotes in one request, then one confirmation
curl -X POST $API/production/quotes/batch -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"kind":"image","brief":"New collection","variations":3,"hooks":["Autumn is here","New season"]}'
curl -X POST $API/production/jobs/batch -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"quote_ids":["<q1>","<q2>","<q3>"]}'
# Adapt a ready image to ad formats (format ids: GET /production/formats?platform=meta&type=image)
curl -X POST $API/production/jobs/<job_id>/formats -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"formats":[12,14],"headline":"New season","cta":"Shop now","logo":true}'
# Review link for 14 days, then read the decision and comments
curl -X POST $API/production/jobs/<job_id>/share -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"days":14}'
curl $API/production/jobs/<job_id>/share -H "Authorization: Bearer $KEY"
# TV master copy (ProRes 422 HQ, 30 s, PAL)
curl -X POST $API/production/jobs/<job_id>/masters -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"profile":"tv_pal","codec":"prores","seconds":30}'
# Use it in a campaign
curl -X POST $API/production/jobs/<job_id>/campaign -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"campaign_id":"<campaign_id>"}'Precios y créditos
- Modo de cobro: las producciones se pagan con créditos del plan (
pricing: credits) o con el saldo de producción (pricing: balance, USD); el modo activo aparece enget_production_optionsyGET /production/overview. - Primero el precio: cada presupuesto indica qué se producirá, el importe y su validez (
expires_at). Un presupuesto caducado no se puede iniciar; uno nuevo se calcula con el precio de hoy. - Cuándo se cobra: en modo saldo el importe se reserva al iniciar y se cobra cuando el archivo está listo; si el trabajo falla o se cancela, la reserva se devuelve. En modo créditos, al iniciar se comprueba que los créditos restantes cubren el trabajo y los créditos se gastan cuando se produce el archivo.
- Si no alcanza, no empieza: si los créditos o el saldo no lo cubren, o se superaría el límite mensual, el trabajo no empieza; la respuesta indica el importe necesario y el restante.
- Mismo precio en todas partes: los precios se fijan para que cada trabajo cubra su coste, y el panel, MCP y la API aplican el mismo precio.
- Tarifa de herramientas MCP: llamar a las herramientas de producción no cuesta nada extra (0 créditos); solo leer una página de producto, subir una imagen desde una dirección y las sugerencias de apertura cuestan 1 crédito. El precio de la producción es el importe de su presupuesto.
Confirmación: ¿cuándo se cobra?
quote_productionyretry_productionsolo crean un presupuesto; no producen ni cobran nada.start_productionreserva el importe o gasta créditos; el asistente solo debe llamarla después de que usted haya visto el precio y lo haya aprobado de forma explícita. La herramienta está marcada en los clientes como una que pide confirmación (destructiva).- El chat del panel no inicia un presupuesto obtenido en el mismo turno (
confirmation_required): la aprobación debe llegar después del mensaje en el que vio el precio. - Iniciar dos veces el mismo presupuesto no abre una segunda producción; se devuelve la primera. En REST,
Idempotency-Keydevuelve el mismo presupuesto.
Después de la producción
- Adaptar a formatos: una imagen lista se convierte a las proporciones de hasta 12 ubicaciones; titular, llamada a la acción y logotipo quedan en la zona segura. Gratis.
- Revisión previa: sin objetivo, lista las ubicaciones y los perfiles de emisión; con
format_idoprofilese mide el propio archivo y vuelve una lista de aprobado / atención / no aprobado. - Calidad de emisión: a partir de un vídeo listo, una copia máster ProRes 422 HQ o H.264 para TV PAL (1080p25, −23 LUFS), TV NTSC (1080p29,97, −24 LKFS) o TV conectada, con un informe técnico. Gratis; no garantiza la aceptación de la emisora.
- Motor de vídeo: en vídeo puede elegir el modelo por su nombre en lugar de un nivel de calidad (Seedance 2.0 y 2.5 en 1080p; 2.5 Flash, 2.0 Fast y 2.0 Mini en 720p, todos con audio). Escriba el id del modelo en
tier, p. ej.bytedance/seedance-2.0; la lista y los precios llegan conget_production_optionsoGET /production/overview›tiersconengine_name. Un motor desactivado se rechaza conengine_unavailableen lugar de cotizarse con otro modelo. - Vídeo de marca: el orden de escenas, los subtítulos y la tarjeta de cierre se vuelven a montar gratis como una nueva versión; la anterior se conserva. Regenerar una sola escena tiene coste y pasa por un presupuesto.
- Compartir: un enlace de revisión sin inicio de sesión, válido de 1 a 90 días; la dirección solo se muestra una vez al crearla y se cierran los enlaces anteriores de la producción. La decisión y los comentarios se leen con
get_production_share; puede cerrar el enlace cuando quiera. - Añadir a una campaña: la producción pasa a ser una tarjeta de creatividad en borrador de la campaña. En Meta y Google el archivo se usa al publicar la campaña; un anuncio activo no cambia por sí solo.
- Resultado publicitario: una producción usada en anuncios muestra las cifras de la campaña (
performance) y, en las variaciones, la comparación (batch_result). "Mejor resultado" solo se marca en una comparación justa. - Eliminar: es permanente y no se puede deshacer. No se elimina el contenido usado en una campaña (
in_use) ni el que aún se produce (active). El asistente solo debe usar las herramientas de eliminación cuando usted lo pida de forma explícita.
Avatar de una persona real y consentimiento
- Para un personaje virtual (influencer IA) basta una imagen de rostro lista.
- El avatar de una persona real solo se guarda con una declaración de consentimiento: el nombre de la persona, la base (
self: usted es la persona de la foto ·written: la persona dio permiso por escrito) y la confirmación explícita (confirmed: true). La declaración se guarda con su cuenta y la hora. - La declaración solo la da usted. El asistente no puede rellenar estos campos en su nombre; el chat del panel nunca crea el personaje de una persona real y le remite al formulario.
- Eliminar el personaje retira el consentimiento; los archivos producidos antes quedan en la biblioteca.
// create_production_character (MCP) · POST /production/characters (REST)
{ "name": "Ayşe", "type": "real", "image_id": "<photo id>",
"consent": { "person_name": "Ayşe Yılmaz", "basis": "self", "confirmed": true } }Límites
| Tema | Límite |
|---|---|
| Subida de imágenes | PNG, JPEG o WEBP; hasta 12 MB; lados de 200 a 4.096 px; hasta 500 subidas en la biblioteca |
Texto de la petición (brief) | Hasta 2.000 caracteres; frase de apertura hasta 160 caracteres |
| Variaciones | 2–4 (la administración de la plataforma puede bajar el máximo) |
| Sugerencias de apertura | 5–8 por llamada |
| Adaptación a formatos | Hasta 12 formatos por petición |
| Eliminación múltiple (MCP) | Hasta 24 producciones por llamada |
| Enlace de revisión | 1–90 días (14 por defecto) |
| Vídeo de marca | Hasta 12 escenas; hasta 12 versiones por producción |
| Copia máster de emisión | Duración del spot 10, 15, 20, 30, 45 o 60 s; la fuente se alarga 3 s como máximo; vídeo fuente de hasta 185 s; hasta 8 copias por producción |
| Personajes | Hasta 50 por cuenta |
| Límites de frecuencia (por hora y cuenta) | Presupuestos 120 · subidas 60 · adaptación 120 · personajes 40 · copias máster 20 · revisión previa 180 · nuevo montaje 30 · sugerencias de apertura 40 · página de producto 20 · compartir 60 · descarga 240 |
Códigos de error
| Código | REST | Significado y qué hacer |
|---|---|---|
credits_exhausted | 402 | Los créditos del plan no cubren este trabajo; la respuesta indica needed y remaining. Mejore el plan o compre créditos extra en la pantalla Plan. |
insufficient_balance | 402 | El saldo de producción no alcanza; recárguelo en la pantalla Producción. |
monthly_limit | 402 | Se superaría su límite mensual; cámbielo o espere al mes siguiente. |
quote_expired · quote_cancelled | 410 · 409 | El presupuesto caducó o se canceló; pida uno nuevo (el precio puede haber cambiado). |
not_found | 404 | El id no existe en esta cuenta (un registro de otra cuenta se ve igual). Tome el id de la herramienta o el endpoint de lista. |
read-only · read_only | 403 | Una clave con alcance de lectura o el rol de lector no pueden hacer tareas de escritura. |
needs_provider | — | Es un estado de producción: no hay proveedor de IA conectado y solo se escribió el guion; se puede reintentar cuando haya un proveedor. |
rate_limited | 429 | Se alcanzó el límite por hora; vuelva a intentarlo tras retry_after segundos. |
reference_required · reference · character_required · language · formats | 422 | Falta o no es válido el origen, personaje, idioma o formato que necesita la receta; hint en la respuesta indica qué hacer. |
rendering · in_use · active · not_ready | 409 | Un trabajo que ya está en el proveedor no se puede detener; el contenido de una campaña o en producción no se elimina; un archivo que no está listo no se añade a una campaña. |
consent | 422 | Falta la declaración de derechos (página de producto) o la de consentimiento (persona real). |
unsafe · unsafe_url | 422 | No se leen direcciones internas o locales; indique una dirección http(s) pública. |
Próximos pasos
- Herramientas de producciónImágenes, vídeos, locuciones y guiones: presupuesto y confirmación, todas las recetas, biblioteca, adaptación a formatos, calidad de emisión, enlaces de revisión y personajes.
- API y clientesAutenticación con clave de API en el plan Enterprise: permisos, límites de uso, referencia OpenAPI, clientes de Python y JavaScript y conexión con los SDK de MCP.
- Créditos y usoCada llamada a una herramienta gasta unos créditos: leer es barato, los cambios en vivo cuestan más. 100 créditos de por vida en el plan Inicial, créditos renovados cada mes en los planes de pago; las llamadas fallidas se reembolsan.