Automotion docs
API

Scripts

Generate structured video scripts with AI — scenes of narration (`voiceText`) and image prompts, plus a title and description — grounded by your brief, tone, audience, structure, visual style and optional source material. Pair with [Renders](/docs/api/renders): map the scenes into a movie document (voice elements from `voiceText`, generated images from `imagePrompt`) and render it.

Generate structured video scripts with AI — scenes of narration (voiceText) and image prompts, plus a title and description — grounded by your brief, tone, audience, structure, visual style and optional source material. Pair with Renders: map the scenes into a movie document (voice elements from voiceText, generated images from imagePrompt) and render it.

Generation is synchronous — the response carries the finished script, typically after tens of seconds — and costs max(2, ceil(scenes/4)) credits, charged only on success: a generation that fails validation after every repair attempt answers LLM_FAILED and charges nothing. The model is re-prompted until the draft satisfies every constraint you set (exact scene count, words per scene, required image prompts), so what you receive is guaranteed to match the request's shape. Note that title and description are model-authored text — review them before publishing anywhere.

All endpoints live under https://api.useautomotion.com/v1, require Authorization: Bearer <api key>, and answer with the standard envelopes.

POST /scripts

Generate a video script. Synchronously generate a structured video script (scenes of voiceText + imagePrompt, plus title/description) from a brief and grounding parameters — tone, audience, structure, visual style, source material to transform, and scene/word bounds. Costs max(2, ceil(scenes/4)) credits, charged only on success; the model is re-prompted until the draft satisfies every constraint. Expect a response time of tens of seconds.

Parameters

NameInTypeRequiredDescription
Idempotency-Keyheaderstring (non-empty, ≤ 255 chars)noOptional client-chosen key making the create retry-safe (§9): replaying the same key with the same body returns the ORIGINAL render with 200; a different body is rejected with IDEMPOTENCY_KEY_REUSED.

Request body

The brief and grounding parameters.

FieldTypeDefaultDescription
brief *string (non-empty, ≤ 2000 chars)—What the video is about — the creative brief the script is grounded in.
sourceMaterialstring (non-empty, ≤ 30000 chars)—Existing material (transcript, article, notes) to transform. The script covers the same substance in entirely original wording — sentences are never copied.
sceneCountinteger (1–50)—Exact number of scenes to produce. When omitted, the model chooses 10–14.
targetDurationSecnumber (5–3600)—Approximate total narration length in seconds — pacing guidance, not enforced.
languagestring (non-empty, ≤ 50 chars)—Output language (e.g. "English", "Deutsch"). English when omitted.
tonestring (non-empty, ≤ 200 chars)—Narration tone, e.g. "calm, authoritative" or "playful and fast".
audiencestring (non-empty, ≤ 200 chars)—Who the video is for; the script's vocabulary and examples target them.
structurestring (non-empty, ≤ 2000 chars)—Free-text structural instructions the scenes must follow, e.g. "hook, then 5 numbered points each reinforced by a practical line, then a strong close and a CTA".
visualStylestring (non-empty, ≤ 500 chars)—Visual style applied to every imagePrompt (subject, palette, lighting, mood) so the scenes render as one coherent set.
wordsPerSceneobject—Per-scene narration length bounds — enforced: drafts outside them are repaired.
includeImagePromptsbooleantrueEmit an imagePrompt for every scene (default true).
includeTitlebooleantrueEmit a video title (default true).
includeDescriptionbooleantrueEmit a video description (default true).

Example

curl -X POST https://api.useautomotion.com/v1/scripts \
  -H "Authorization: Bearer $AUTOMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Five stoic habits that build discipline",
    "sceneCount": 12,
    "tone": "calm, assertive",
    "structure": "hook, five numbered points each reinforced, strong close, CTA",
    "visualStyle": "weathered marble statues, golden torchlight, deep blacks, 9:16",
    "wordsPerScene": {
      "min": 9,
      "max": 16
    }
  }'

Responses

  • 201 — The generated script. Returns ScriptResource.
  • 200 — Idempotent replay: the same Idempotency-Key with the same body returns the original script. Returns ScriptResource.

ScriptResource

FieldTypeDefaultDescription
id *string (non-empty)—Script id.
title *string (non-empty) | null—Video title. Null when not requested.
description *string (non-empty) | null—Video description. Null when not requested.
scenes *object[]—The scenes, in playback order with 1-based indexes.
meta *object—Generation metadata.
createdAt *string (date-time)—Creation time (ISO-8601).

Errors

VALIDATION_ERROR · INSUFFICIENT_CREDITS · IDEMPOTENCY_KEY_REUSED · LLM_FAILED — plus the pipeline-wide UNAUTHORIZED · RATE_LIMITED · INTERNAL.

GET /scripts/{id}

Get a script. Fetch a previously generated script by id.

Parameters

NameInTypeRequiredDescription
idpathstring (non-empty)yesThe script id.

Example

curl https://api.useautomotion.com/v1/scripts/$SCRIPT_ID \
  -H "Authorization: Bearer $AUTOMOTION_API_KEY"

Responses

  • 200 — The script. Returns ScriptResource.

ScriptResource

FieldTypeDefaultDescription
id *string (non-empty)—Script id.
title *string (non-empty) | null—Video title. Null when not requested.
description *string (non-empty) | null—Video description. Null when not requested.
scenes *object[]—The scenes, in playback order with 1-based indexes.
meta *object—Generation metadata.
createdAt *string (date-time)—Creation time (ISO-8601).

Errors

NOT_FOUND — plus the pipeline-wide UNAUTHORIZED · RATE_LIMITED · INTERNAL.

Previous

Templates

Next

Assets

On this page