Orshot-HQ/orshot-openclaw

Orshot: automatiza la generación de video, PDF e imágenes a partir de plantillas y la publicación en redes sociales

Orshot es una API para la generación automatizada de imágenes, PDF y video a partir de plantillas. Diseña una plantilla una vez en el estudio de Orshot (o impórtala desde Canva o Figma), luego renderízala con nuevo texto, imágenes y video en cada llamada, y publica el resultado en cuentas de redes sociales conectadas en la misma solicitud. El renderizado es determinista: la misma plantilla más los mismos datos dan la misma salida cada vez.

• Documentación: https://orshot.com/docs (añade .md a cualquier URL de documentación para obtener markdown)
• Servidor MCP alojado: https://mcp.orshot.com/mcp (más de 100 herramientas orshot_*)
• Base REST: https://api.orshot.com/v1
• Plan gratuito: 100 créditos al mes, sin tarjeta de crédito.

Conéctate primero (MCP, sin clave que pegar)

El servidor MCP alojado es la ruta más rápida y la única que devuelve vistas previas en línea, tarjetas de publicación visual y comprobaciones de diseño. Añádelo, inicia sesión con la cuenta de Orshot del usuario en el navegador, y cada herramienta a continuación funcionará.

openclaw mcp add orshot --url https://mcp.orshot.com/mcp --transport streamable-http --auth oauth
openclaw mcp login orshot

¿Aún no tienes una cuenta de Orshot? La página de inicio de sesión ofrece registro; el plan gratuito comienza con 100 créditos al mes. Claude Code: claude mcp add --transport http orshot https://mcp.orshot.com/mcp. Cursor, Windsurf, VS Code, Codex y ChatGPT aceptan la misma URL como un servidor MCP remoto.

Confírmalo con orshot_get_account. Devuelve el perfil, los espacios de trabajo y los créditos. Si dice que la suscripción está inactiva o que se alcanzó un límite del plan, eso es un estado de facturación, no un error de autenticación: dirige al usuario a la página de facturación de su espacio de trabajo en https://orshot.com/pricing y deja de reintentar.

Plan B sin interfaz gráfica: REST con una clave API. Solo cuando el agente no pueda ejecutar MCP (un trabajo cron, un script del lado del servidor, n8n).

export ORSHOT_API_KEY=...   # Configuración del Espacio de Trabajo > Claves API
curl -s https://api.orshot.com/v1/me -H "Authorization: Bearer $ORSHOT_API_KEY"

No continúes hasta que uno de los dos métodos funcione.

Lo que puedes hacer con ello

Cada línea nombra primero la herramienta MCP y segundo la ruta REST.

• Renderiza cualquier plantilla con tus datos: OG images, creatividades publicitarias, certificados, facturas, carruseles, reels. orshot_render_template o POST /v1/studio/render.
• Crea y refina plantillas de estudio a partir de un brief, con vistas previas en línea y comprobaciones de diseño. orshot_create_template_design, orshot_update_template_design, orshot_patch_template_elements (lee primero orshot://template-design-spec; la habilidad orshot-social-media-content contiene las reglas de diseño).
• Renderiza video real: animaciones y transiciones por elemento, bandas sonoras del kit de marca, previsualizaciones de movimiento gratuitas antes de un render de pago. Misma herramienta de render con format: "mp4".
• Comienza con plantillas de utilidad prediseñadas: capturas de tweets, capturas de sitios web, gráficos de barras y comparativos, capturas de pantalla de la App Store, maquetas de teléfono, eliminación de fondos. orshot_render_library_template o POST /v1/generate/:renderType.
• Redimensiona un diseño a todos los formatos sociales en una sola llamada (Redimensionado Inteligente). size y extraSizes en el render.
• Renderiza por lotes variaciones personalizadas, como certificados para una lista de nombres. orshot_batch_render_template.
• Mantén la coherencia de marca: colores, fuentes, imágenes, videos y audio del kit de marca. orshot_get_brand_kit, orshot_import_brand_website.
• Organiza: carpetas, uso compartido de plantillas, cambio entre espacios de trabajo de clientes. orshot_list_template_folders, orshot_set_active_workspace.
• Crea URLs dinámicas firmadas para OG images e incrustaciones. orshot_create_dynamic_url o POST /v1/signed-url/create.
• Redacta, programa y publica publicaciones en redes sociales, aprende el mejor momento para publicar a partir de los datos de interacción del usuario, lee estadísticas de alcance e interacción. orshot_publish_social_post, orshot_get_best_time_to_post, orshot_get_social_analytics. La habilidad orshot-social-media-scheduler contiene el ciclo completo.
• Construye y ejecuta flujos de trabajo de automatización que sigan produciendo contenido periódicamente. orshot_create_workflow, orshot_run_workflow.

Ejemplos de indicaciones que se asignan directamente a estas herramientas:

• "Renderiza la plantilla de lanzamiento como una OG image con el título 'Acabamos de lanzar'"
• "Crea una plantilla de publicación de Instagram con un titular, un subtítulo y una imagen de producto"
• "Redimensiona mi diseño de lanzamiento para Instagram story, cuadrado y OG en una sola llamada"
• "Genera certificados para esta lista de 40 nombres como PDFs"
• "Captura este tweet" / "Captura orshot.com como una imagen" / "Haz un gráfico de barras con estos números"
• "Publica este render en Instagram en el mejor momento y muéstrame cómo rindieron las publicaciones de la semana pasada"

Flujo de trabajo principal

1. Conéctate (arriba).
2. Encuentra la plantilla. orshot_list_studio_templates (busca por nombre y etiquetas) o GET /v1/studio/templates/all?page=1&limit=10. ¿Aún no hay plantilla? Usa las más de 2.000 plantillas de la biblioteca (orshot_list_library_templates) o diseña una con orshot_create_template_design.
3. Lee sus parámetros. orshot_get_studio_template_modifications o GET /v1/studio/templates/:id. Las modificaciones se clavean por parameterId, nunca por nombre de capa. Nunca adivines las claves.
4. Renderiza. orshot_render_template con modifications, o POST /v1/studio/render con response: { type: "url", format: "png" }.
5. Entrega o publica. Muestra al usuario la URL de salida. Añade publish para publicarla en redes sociales en la misma llamada.
6. Automatiza. Pon la llamada en n8n, Make, Zapier o cron que el usuario ya ejecute, o crea un Flujo de Trabajo de Orshot.
7. Verifica. orshot_list_workspace_logs o GET /v1/workspace/logs muestra el render y su source. Muestra la salida antes de darlo por terminado.

Reglas de seguridad para agentes

• Confirma antes de que algo salga del espacio de trabajo. Publicar una publicación social, ejecutar un flujo de trabajo (gasta créditos y puede entregar o publicar) y eliminar una plantilla, flujo de trabajo o activo de marca necesitan una aprobación explícita. Di qué se publicará, dónde y cuándo.
• Las publicaciones sociales por defecto son borradores. "Prepara", "borrador", "déjame ver primero" significan status: "draft". Un borrador no llega a nadie hasta que se publica.
• Muestra el costo antes del trabajo masivo. Los renders gastan créditos, las modificaciones .prompt gastan créditos de IA, y cada cuenta de red social conectada es un complemento de pago. Dilo antes de un bucle de cientos de renders.
• Nunca pegues la clave API en el chat, archivos o URLs. Léela del entorno. Prefiere MCP, que no tiene ninguna clave.
• No elimines nada para "limpiar" por tu cuenta.

Errores comunes (léelos antes de renderizar)

1. Las modificaciones se clavean por parameterId, no por nombre de capa. Si se ignora un valor, la clave es incorrecta. Obtén la plantilla en lugar de adivinar.
2. Las plantillas de varias páginas necesitan un prefijo pageN@. "page1@title", "page2@title". Un "title" desnudo solo afecta a la página 1.
3. El templateId del estudio es un número entero; el templateId de utilidad es una cadena (/v1/generate/:renderType toma un slug como "website-screenshot").
4. La salida de video no necesita capas de video. format: "mp4", "webm" o "gif" renderiza cualquier plantilla. Los renders de video largos deben usar response.mode: "async" y sondear orshot_get_render_job o GET /v1/studio/render-jobs/:id, o el cliente se agotará.
5. Las URLs de imagen y video en las modificaciones deben ser públicas. El renderizador las obtiene del lado del servidor; localhost, las URLs firmadas caducadas y las URLs protegidas por autenticación fallarán.
6. Las anulaciones de estilo usan notación de puntos en el parameterId: "title.fontSize": "48px".
7. La forma de la respuesta difiere según el número de páginas. Una página: data es un objeto (data.content). Varias páginas: data es un array de { page, content }.
8. base64 y binary no se combinan. binary transmite un solo archivo.
9. Los créditos y los créditos de IA son separados. Las modificaciones .prompt gastan créditos de IA adicionales.
10. En 429, retrocede usando Retry-After.
11. Los PDFs no se pueden publicar en redes sociales. Las imágenes no pueden ir a TikTok o YouTube (solo video). El video no puede ir a Google Business.
12. Los ids de las cuentas de redes sociales son números. Dos cuentas en la misma plataforma tienen ids diferentes. Publica siempre por id, nunca por nombre de plataforma.
13. La publicación social es un complemento de pago. Los espacios de trabajo del plan gratuito no pueden conectar cuentas. La publicación en sí no gasta créditos adicionales.

Aspectos esenciales del renderizado

Referencia completa de campos: references/render-configuration.md y references/api-reference.md.

await fetch("https://api.orshot.com/v1/studio/render", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({
    templateId: 123,
    modifications: {
      title: "Día de lanzamiento",             // texto
      hero_image: "https://.../a.png", // url de imagen
      "title.fontSize": "56px",        // anulación de estilo
      "page2@title": "Diapositiva dos",      // varias páginas
    },
    response: { type: "url", format: "png", size: "instagram-story",
                extraSizes: ["1080x1080", "1200x630"] },
  }),
});

El mismo objeto es la entrada de orshot_render_template a través de MCP.

• format: png, jpg, webp, pdf, mp4, webm, gif.
• size renderiza el diseño en otro preajuste o WIDTHxHEIGHT; extraSizes añade más copias en una sola llamada (Redimensionado Inteligente). Preajustes: orshot://formats.
• response.mode: "async" devuelve un trabajo; sondéalo o pasa webhook_url. Úsalo para video.
• Muchas variantes a la vez: orshot_batch_render_template, o itera la llamada de render a través de REST.
• URLs firmadas: POST /v1/signed-url/create para una URL de render que puedes incrustar sin exponer la clave.

SDKs para uso sin interfaz gráfica: npm install [email protected], pip install orshot==0.2.0, composer require rishimohan/orshot:0.2.0, gem install orshot -v 0.2.0.

import { Orshot } from "orshot";
const orshot = new Orshot(apiKey); // lee de tu entorno
const res = await orshot.renderFromTemplate({
  templateId: "open-graph-image-1",
  modifications: { title: "Hola Mundo" },
  responseType: "url",
  responseFormat: "png",
});

Publicación social (la versión corta)

Orshot publica renders en más de 13 plataformas: X, Instagram, Facebook, LinkedIn, TikTok, YouTube, Pinterest, Reddit, Bluesky, Threads, Telegram, Snapchat, Google Business. La habilidad orshot-social-media-scheduler maneja la programación, borradores, estadísticas y mejor momento; esto es el núcleo.

1. Cuentas. orshot_list_social_accounts o GET /v1/social/accounts?include_health=true. Las cuentas son conectadas por un humano en el panel de control (Espacio de Trabajo > Redes Sociales > Cuentas); la API no puede conectar una. Una lista vacía significa enviar al usuario allí.
2. Renderiza y publica en una sola llamada. Añade publish al render:

publish: {
  accounts: [1, 3],
  content: "Texto, máximo 5000 caracteres",
  status: "draft",                       // "published" (por defecto) | "draft" | "scheduled"
  // scheduled_for: "2026-11-01T14:00:00Z", timezone: "America/New_York",
  platformOptions: { "3": { firstComment: "https://orshot.com" } },
  tiktokSettings: { autoAddMusic: true }, // Carruseles de fotos de TikTok
}

Las plantillas de varias páginas se publican automáticamente como un carrusel. La respuesta lleva publish[] con status, url y error por cuenta. Una publicación fallida nunca bloquea el render.

3. Publica una URL de medios existente. orshot_publish_social_post o POST /v1/social/publish con media_urls.
4. Publicaciones retenidas. orshot_list_social_posts, orshot_get_social_post (tarjeta visual), orshot_update_social_post, orshot_publish_social_draft, orshot_discard_social_post. REST: GET|PATCH|DELETE /v1/social/posts/:id, POST /v1/social/posts/:id/publish.
5. Estadísticas y mejor momento. orshot_get_social_analytics, orshot_get_social_analytics_daily, orshot_get_social_followers, orshot_get_best_time_to_post. REST: GET /v1/social/analytics, /daily, /accounts, /insights.

Recetas comunes

OG image en cada despliegue

response: { type: "url", format: "png", size: "og-image" }
// <meta property="og:image" content={data.content} />

Lotes desde un CSV (certificados, facturas, insignias): orshot_batch_render_template con un conjunto de modificaciones por fila y format: "pdf", o itera POST /v1/studio/render.

Gráfico social semanal, publicado como borrador para revisión: renderiza con publish.status: "draft", luego orshot_publish_social_draft después de que el usuario lo apruebe.

Un diseño, todos los tamaños: extraSizes: ["1080x1920", "1080x1080", "1200x630"].

Carrusel de TikTok, Instagram o LinkedIn: consulta la habilidad orshot-carousel.

Canalización recurrente: references/recurring-automation.md. Revisa los registros del espacio de trabajo para el source que el usuario ya ejecuta (n8n, Make, Zapier, SDK) y añádelo a eso; ofrece Flujos de Trabajo de Orshot solo cuando aún no ejecuten nada.

Archivos de referencia

Léelos bajo demanda; no se cargan por defecto.

Archivo	Cuándo
references/api-reference.md	cada endpoint REST: render, plantillas, URLs firmadas, activos de marca, URLs dinámicas, carpetas, flujos de trabajo
references/render-configuration.md	tipos de modificación, opciones de video, trabajos asíncronos, animaciones, audio, Redimensionado Inteligente, tipos de respuesta, créditos
references/template-design-spec.md	esquema de elementos para crear o editar plantillas a través de la API
references/recurring-automation.md	libro de jugadas de n8n, Make, Zapier, Pipedream, cron y Flujos de Trabajo de Orshot
references/integrations-and-errors.md	lista de integraciones, códigos de error, mejores prácticas
references/oauth-developer-apps.md	construcción de una aplicación de terceros en Orshot con OAuth
references/embed.md	incrustación del editor de marca blanca (iframe, React, Vue)
references/migration.md	migración desde Bannerbear, Placid, Templated, Creatomate o similares

Cualquier página de documentación está disponible como markdown: https://orshot.com/docs/<path>.md. El servidor MCP también sirve orshot://template-design-spec y orshot://formats.

Referencia rápida

# conectar
openclaw mcp add orshot --url https://mcp.orshot.com/mcp --transport streamable-http --auth oauth && openclaw mcp login orshot
curl -s https://api.orshot.com/v1/me -H "Authorization: Bearer $ORSHOT_API_KEY"   # comprobación REST

# plantillas
GET  /v1/studio/templates/all?page=1&limit=2

…

[truncado para traducción]