AI Authoring

AI authoring turns a brief into .ws source. The important part is not that a model writes text. The important part is that the result is passed through Workshop's compiler gate before it enters the production workflow.

POST/api/author

Generate `.ws` from intent

Creates a .ws script from a natural-language prompt, optionally using mood, aspect, brand URLs, templates, and compiler validation.

bash
curl -X POST "$WORKSHOP_URL/api/author" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $WORKSHOP_API_KEY" \
  -d '{
    "prompt": "Create a 20-second product launch teaser for a finance analytics tool. Make it precise, confident, and suitable for executives.",
    "mood": "precision",
    "aspect": "16:9",
    "validate": true,
    "includeRenderGraph": false
  }'
json
{
  "source": "Film "Launch Teaser"
  mood: precision
...",
  "diagnostics": [],
  "metadata": {
    "sceneCount": 3,
    "estimatedDuration": 18.5,
    "mood": "precision"
  }
}

Request Fields

Field Type Purpose
prompt string Natural-language production brief
mood string Preferred mood or mood composition
aspect string 16:9, 9:16, 1:1, or supported aspect
validate boolean Run compiler validation before returning
includeRenderGraph boolean Include compiled graph for inspection

Brand-Aware Authoring

When URL brand extraction is enabled, the author route can inspect URLs in the prompt and use discovered colors as brand hints. This is best-effort. If the URL cannot be fetched, authoring continues without blocking the request.

Agent Guidance

Agents should use this endpoint as a draft generator, then call compile or render explicitly. A strong agent loop is:

  1. Generate .ws from prompt.
  2. Compile with diagnostics.
  3. Repair any compiler errors.
  4. Present the source and RenderGraph summary for human review.
  5. Render only after the artifact is approved for publication.

Next Steps

  • What to Build - agentic production workflows
  • Compile - validation gate
  • MCP - expose authoring and compile tools to agents