Compile

The compile endpoint parses a .ws script and returns a RenderGraph JSON — the intermediate representation that drives video rendering. Use this to inspect what a video will contain before committing to a render job.

Compile from Source

POST/api/compile

Compile source

Parses .ws source text and returns the compiled RenderGraph with diagnostics.

Request body:

json

{
  "source": "Film \"Hello World\"\n  mood: confident\n\nScene \"Intro\"\n  show \"Hello, Workshop!\"\n    size: hero\n    enter: rise",
  "theme": "corporate-blue"
}

Field	Type	Required	Description
`source`	string	yes	The `.ws` source text
`theme`	string	no	Name of a registered ThemePack to apply

Response (200):

json

{
  "renderGraph": {
    "version": "rendergraph.v1",
    "meta": {
      "title": "Hello World",
      "durationSeconds": 5,
      "aspect": "16:9",
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "theme": "default",
      "mood": "confident"
    },
    "timeline": [],
    "assets": {},
    "globals": { "fps": 30, "mood": "confident", "tempo": "measured" }
  },
  "diagnostics": []
}

Error (422): Compilation failed with diagnostics:

json

{
  "error": "Compilation failed",
  "diagnostics": [
    { "level": "error", "message": "Unknown mood: nonexistent", "line": 2, "column": 9 }
  ]
}

Compile from File Upload

POST/api/compile/file

Compile file

Upload a .ws file directly as multipart form-data with a file field. Maximum 50 MB. Response is the same as compile from source.

Examples

Minimal script:

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"
  }'

With ThemePack:

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 \"Demo\"\n  mood: confident\n\nScene \"Hello\"\n  show \"Hello World\"\n    size: hero",
    "theme": "corporate-blue"
  }'

Next Steps

Render — queue a video render from compiled output
Validate — check a RenderGraph for structural correctness
Your First Video — step-by-step walkthrough