AI Authoring

Workshop's author endpoint converts a plain-English prompt into a valid .ws script. The LLM generates the creative content; the compiler validates the output before it reaches you. Every script returned is 100% syntactically correct.

Basic Authoring

bash
curl -X POST https://api.ws.video/api/author \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{
    "prompt": "Create a polished 20-second launch teaser for a workflow platform with three scenes and a strong CTA.",
    "mood": "confident",
    "aspect": "16:9",
    "validate": true,
    "includeRenderGraph": false
  }'

The response includes:

  • source — the generated .ws script
  • diagnostics — any compiler warnings
  • metadata — scene count, estimated duration, mood applied

You can take the returned source and send it directly to /api/render.

The Validation Gate

When validate: true (the default), the generated script passes through Workshop's full compiler pipeline before being returned. If the LLM produces invalid syntax, the compiler catches it and feeds the error back to the LLM for automatic correction.

This self-healing loop means the author endpoint returns syntactically valid .ws every time. You do not need to parse or validate the output yourself.

Including the RenderGraph

Set includeRenderGraph: true to get both the .ws source and the compiled RenderGraph in a single call:

bash
curl -X POST https://api.ws.video/api/author \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{
    "prompt": "Write a short internal metrics update with 3 scenes and one numerical proof point.",
    "mood": "confident + elegant",
    "validate": true,
    "includeRenderGraph": true
  }'

This saves a round trip if you plan to render immediately.

Brand-Aware Authoring

Mention a URL in your prompt and Workshop's brand resolver will extract colors from the website and inject them as context for the LLM:

bash
curl -X POST https://api.ws.video/api/author \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{
    "prompt": "Create a 30-second product video for our brand. Use https://stripe.com as color inspiration and keep the style premium.",
    "mood": "elegant"
  }'

The brand resolver runs an intelligent heuristic extraction engine against the referenced URL, discovering primary, accent, and background brand colors automatically. These are ranked, deduplicated, and injected into the LLM's context to generate brand-accurate scripts. The extraction is best-effort and non-fatal — if the URL is unreachable, authoring continues without brand hints.

When to Author vs. Write Directly

Use AI authoring when you have a content idea but not a specific visual plan. The LLM makes creative decisions about scene structure, element sizing, entrances, and pacing.

Write .ws directly when you know exactly what you want — specific text, specific layout, specific timing. Direct authoring gives you full control over every parameter.

Use both when you want a starting point: author from a prompt, then edit the returned .ws source to refine specific details.

Next Steps