Greenlight AI

Introduction

Greenlight is a REST API that gates AI-video assets before they’re generated. Base URL https://api.greenlight.ai. All requests are JSON. Current version: v1.

Authentication

Bearer token. Send Authorization: Bearer gl_live_.... Keys are created in the dashboard; gl_test_ keys don’t count against quota.

Endpoints

POST/v1/check/script

Evaluate an idea, script, or series plan.

Returns a Verdict (score, verdict, notes, per-dimension: hook, clarity, trend_fit, audience_resonance, brand_safety).

Request body
{
  "text": "...",
  "format": "short-form|series|ad",
  "audience": "gen-z, indonesia",
  "brand_safety": true
}
Response
{
  "id": "vd_7a1e...",
  "verdict": "pass",
  "score": 8.4,
  "dimensions": {
    "hook": 8.1,
    "clarity": 8.6,
    "trend_fit": 7.9,
    "audience_resonance": 8.5,
    "brand_safety": 9.2
  },
  "notes": ["Hook lands in the first line.", "Ending is soft — sharpen the CTA."]
}
POST/v1/check/prompt

Lint a generation prompt (model-aware).

Returns Verdict + failure_risks[] + rewritten_prompt.

Request body
{
  "prompt": "...",
  "model": "veo-3.1",
  "shot_type": "wide|close|..."
}
Response
{
  "id": "vd_3d90...",
  "verdict": "revise",
  "score": 6.1,
  "failure_risks": ["subject_overload", "ambiguous_negation"],
  "rewritten_prompt": "wide shot, neon-lit alley, ONE running figure, heavy rain, cinematic"
}
POST/v1/evaluate/frame

Score one storyboard frame vs its prompt.

Returns Verdict + failure_modes[] + autofix.

Request body
{
  "image": "<url|base64>",
  "prompt": "...",
  "model": "veo-3.1",
  "consistency_ref": "<url?>"
}
Response
{
  "id": "vd_9f2c...",
  "verdict": "pass | revise | block",
  "score": 8.2,
  "threshold": 7.0,
  "passed": true,
  "confidence": 0.86,
  "failure_modes": [
    { "code": "human_anatomy", "severity": "low", "detail": "left hand: 6 fingers", "frame_region": [0.61, 0.44, 0.72, 0.58] }
  ],
  "dimensions": { "aesthetic": 8.5, "prompt_adherence": 7.9, "consistency": 8.0, "hook": 7.4 },
  "notes": [
    "Hook reads by 1.2s — strong.",
    "Caption contrast low for mobile; darken background 10%."
  ],
  "autofix": {
    "applied": false,
    "rewritten_prompt": "wide shot, neon-lit alley, ONE running figure, both hands visible, heavy rain, cinematic",
    "expected_score": 8.9
  },
  "model": "veo-3.1",
  "created_at": "2026-07-29T10:00:00Z"
}
POST/v1/gate/storyboard

Batch-gate a full storyboard with optional continuity check.

Returns { passed, frames, continuity, summary }.

Request body
{
  "frames": [{ "image": "...", "prompt": "..." }],
  "model": "...",
  "threshold": 7.0,
  "audience": "...",
  "check_continuity": true
}
Response
{
  "passed": true,
  "frames": [ /* FrameVerdict[] */ ],
  "continuity": { "score": 8.7, "issues": [] },
  "summary": { "pass_rate": 0.94, "avg_score": 8.2 }
}

Verdict schema

Verdict
{
  "id": "vd_9f2c...",
  "verdict": "pass | revise | block",
  "score": 8.2,
  "threshold": 7.0,
  "passed": true,
  "confidence": 0.86,
  "failure_modes": [
    { "code": "human_anatomy", "severity": "low", "detail": "left hand: 6 fingers", "frame_region": [0.61, 0.44, 0.72, 0.58] }
  ],
  "dimensions": { "aesthetic": 8.5, "prompt_adherence": 7.9, "consistency": 8.0, "hook": 7.4 },
  "notes": [
    "Hook reads by 1.2s — strong.",
    "Caption contrast low for mobile; darken background 10%."
  ],
  "autofix": {
    "applied": false,
    "rewritten_prompt": "wide shot, neon-lit alley, ONE running figure, both hands visible, heavy rain, cinematic",
    "expected_score": 8.9
  },
  "model": "veo-3.1",
  "created_at": "2026-07-29T10:00:00Z"
}

Failure-mode codes:

attribute_bindingcountingtext_renderingspatial_relationphysicshuman_anatomyhuman_actionnegationstyle_blendabstract_conceptbrand_safety

Errors

StatusTypeMeaning
400invalid_requestMalformed or missing required fields.
401invalid_api_keyMissing or invalid bearer token.
402quota_exceededMonthly check quota used; add overage or upgrade.
422unprocessableBad image — unreadable, corrupt, or unsupported format.
429rate_limitedToo many requests; back off and retry.
5xxserver_errorSomething failed on our end. Retry with backoff.

JSON error shape:

json
{
  "error": {
    "type": "quota_exceeded",
    "message": "Monthly check quota exceeded. Upgrade or wait for reset."
  }
}

SDKs

Official: Python (pip install greenlight), JavaScript/TypeScript (npm i @greenlight/sdk). Both wrap the REST API 1:1.

Coming soon — use cURL for now.