Quickstart

This guide takes you from zero to a rendered MP4 in under five minutes. All you need is an API key and a terminal.

Prerequisites

Workshop is a hosted API. There is nothing to install. You need two things:

  • API key — provided when you are onboarded
  • Org ID — your organization identifier, provided alongside your API key

Contact us at hello@ws.video to get onboarded.

Workshop is in public beta. All tiers currently allow 10 requests per minute. This limit will be revisited after we exit beta.

## Step 1: Check Connectivity

Verify the API is reachable. The health endpoint is public and does not require authentication.

bash
curl https://api.ws.video/health
json
{
  "status": "ok",
  "version": "1.0.0"
}

Step 2: Compile a Script

Send a .ws script to the compile endpoint. This parses your script and returns a RenderGraph — the compiled video specification.

bash
curl -X POST https://api.ws.video/api/compile \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{
    "source": "Film \"Hello World\"\n  mood: confident\n\nScene \"Intro\"\n  show \"Hello, Workshop!\"\n    size: hero\n    enter: rise"
  }'

The response contains a renderGraph object (the compiled video specification) and a diagnostics array (any warnings).

If your script has errors, you will get a 422 response with diagnostics explaining what went wrong and where.

Step 3: Render to Video

Send the same source to the render endpoint. Workshop compiles it, validates the output, and queues a render job.

bash
curl -X POST https://api.ws.video/api/render \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{
    "source": "Film \"Hello World\"\n  mood: confident\n\nScene \"Intro\"\n  show \"Hello, Workshop!\"\n    size: hero\n    enter: rise"
  }'
json
{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "message": "Render queued. Poll GET /render/a1b2c3d4... for status."
}

Step 4: Poll for Completion

Rendering is asynchronous. Poll the job status until it completes.

bash
curl https://api.ws.video/api/render/YOUR_JOB_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID"

The status field will be one of: queued, rendering, complete, or failed.

Step 5: Download the Video

Once the status is complete, download the MP4.

bash
curl -o my-video.mp4 https://api.ws.video/api/video/YOUR_JOB_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-org-id: YOUR_ORG_ID"

Open my-video.mp4. You have a professional motion graphics video generated from five lines of text.

What Just Happened

Your .ws script went through Workshop's compiler pipeline:

  1. Lexer — tokenized the source text
  2. Parser — built an abstract syntax tree
  3. Normalizer — resolved defaults and expanded shorthand
  4. Mood Engine — applied the confident mood profile (palette, typography, timing, easing, entrances)
  5. Timing Calculator — computed hold durations from syllable counts and reading speed
  6. Layout Solver — positioned elements within the frame
  7. Physics Solver — calculated spring dynamics for entrance animations
  8. Compiler — emitted a RenderGraph (the video specification)
  9. Renderer — turned the RenderGraph into an MP4

Every step is deterministic. Run the same script again and you get byte-identical output.

Next Steps