Short dramas

POST /v1/dramas creates a drama from a brief or a script and starts episode 1. Each episode is a workflow run (geekidea/drama-episode): GEEKIDEA writes the story, designs the looks, draws reference images, plans the storyboard, renders keyframes and clips, and cuts the final video. Progress, confirmation, redo and cancellation use the /v1/workflow_runs endpoints.

Create a drama

curl https://api.geekidea.ai/v1/dramas \
  -H "Authorization: Bearer $GEEKIDEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: drama-42" \
  -d '{
    "prompt": "A girl wakes up the day before her college entrance exam and decides to change her family'\''s fate",
    "style": "urban comeback, fast pace, warm tones",
    "aspect_ratio": "9:16",
    "episodes": 3,
    "episode_seconds": 60,
    "text_model": "openai/gpt-5.4",
    "image_model": "openai/gpt-image-2",
    "video_model": "bytedance/seedance-1.5-pro",
    "budget_usd": 20
  }'

{
  "id": "drama_0192f1c3a7b87c3e9a4f5b6c7d8e9f01",
  "object": "drama",
  "status": "producing",
  "source": "ai",
  "title": null,
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "language": "en-US",
  "planned_episodes": 3,
  "episode_seconds": 60,
  "models": { "text": "openai/gpt-5.4", "image": "openai/gpt-image-2", "video": "bytedance/seedance-1.5-pro", "image_quality": null },
  "web_research": false,
  "auto_confirm": false,
  "auto_continue": false,
  "episodes": [
    { "id": "episode_0192f1c3a7b87c3e9a4f5b6c7d8e9f02", "episode_no": 1, "status": "producing", "run_id": "run_0192f1c3a7b87c3e9a4f5b6c7d8e9f03", "progress": 0, "final_video": null, "cover": null, "duration_ms": null }
  ],
  "end_user": null,
  "metadata": null,
  "created_at": 1791425100
}

Follow the episode with GET /v1/workflow_runs/{run_id}, its event stream or webhooks.

Field	Description
`prompt`	One-sentence brief (genre, characters, style…). Give `prompt`, `script` or both
`script`	Script text to adapt
`style`	Visual style, such as “cinematic realism” or “anime”
`aspect_ratio`	`9:16` (default) or `16:9`. The video model must support it
`resolution`	`480p`, `720p` (default) or `1080p`
`language`	Dialogue language, `zh-CN` or `en-US`. Detected from the prompt or script when omitted
`episodes`	Planned number of episodes, 1–100, default 1
`episode_seconds`	Episode length in seconds, 30–300, default 60
`text_model`	Required. Text model for understand, story and storyboard
`image_model`	Required. Image model for reference images, keyframes and the poster
`video_model`	Required. Video model for the clips
`image_quality`	Image quality, when the image model supports it
`web_research`	Research the web while understanding the brief, when the text model supports it
`auto_confirm`	Continue after each step without waiting for confirmation
`auto_continue`	Start the next episode automatically when one is completed
`budget_usd`	Budget for episode 1 in USD, see Budget
`end_user`	Your end-user identifier, up to 128 characters
`metadata`	Up to 16 string key–value pairs

POST /v1/dramas/quote takes the same body and saves nothing. It returns estimated_cost_usd, the amount held when the drama is created (split into model_cost_usd and fee_usd), the steps in that first segment, episode_cost_usd for the whole of episode 1, and within_budget when you sent budget_usd. Before the outline and storyboard exist the number of characters and clips is unknown, so the estimate is based on defaults and the episode length and errs high. Creating returns 402 when your balance is below estimated_cost_usd.

Steps

Each episode runs these steps in order:

Step	Makes	Stops for confirmation	Episode 1	Later episodes
`understand`	The brief card (`brief`): theme, audience, title, world, style	Yes	Runs	Skipped
`story`	Episode 1: the series outline (`outline`) and the episode plot (`plot`). Later: the episode plot	Yes	Runs	Runs
`asset_check`	Which characters, scenes and props to reuse, add or restyle (`asset_check`)	No	Skipped	Runs
`look`	Looks of characters, scenes and props (`look`)	Yes	Runs	Runs
`assets`	Reference images: a portrait and a turnaround sheet per character, one image per scene and prop. Later episodes draw only new or restyled ones	Yes	Runs	Runs
`storyboard`	Scenes, shots and the clips to render (`storyboard`)	Yes	Runs	Runs
`keyframes`	A start frame for each clip	No	Runs	Runs
`clips`	A video for each clip	Yes	Runs	Runs
`final`	The final video and cover; episode 1 also gets a poster	No	Runs	Runs

With auto_confirm: true no step stops. Skipped steps are not charged. When the run stops in waiting_input, review the episode, edit artifacts if you like, then call POST /v1/workflow_runs/{id}/confirm. Redo a step with POST /v1/workflow_runs/{id}/steps/{stepKey}/redo and cancel with POST /v1/workflow_runs/{id}/cancel.

Dramas and episodes

Endpoint	Description
`GET /v1/dramas`	Dramas in the project, newest first. Filter with `end_user`, page with `after` (the last drama ID) and `limit` (1–100, default 20)
`GET /v1/dramas/{id}`	The drama’s settings and a summary of each episode
`POST /v1/dramas/{id}/episodes`	Start the next episode. Optional body: `budget_usd` for this episode
`GET /v1/dramas/{id}/episodes/{no}`	The episode’s workflow run, the current version of each artifact, its media and the final video

The next episode can start only when the previous one is completed and the planned count is not reached; otherwise it returns 409 workflow_invalid_state. With auto_continue: true this happens automatically. Episode status is producing, waiting_input, completed, failed or cancelled. Drama status is draft, producing, completed or archived.

Artifacts

Text outputs are versioned artifacts. kind is one of brief, outline, plot, asset_check, look and storyboard. brief and outline are shared by the whole drama.

Endpoint	Description
`GET /v1/dramas/{id}/episodes/{no}/artifacts/{kind}`	The current version
`PUT /v1/dramas/{id}/episodes/{no}/artifacts/{kind}`	Replace the content as a new version
`GET /v1/dramas/{id}/episodes/{no}/artifacts/{kind}/versions`	Every version, newest first
`POST /v1/dramas/{id}/episodes/{no}/artifacts/{kind}/versions/{version}/restore`	Make an earlier version current

curl -X PUT https://api.geekidea.ai/v1/dramas/drama_0192f1c3a7b87c3e9a4f5b6c7d8e9f01/episodes/1/artifacts/storyboard \
  -H "Authorization: Bearer $GEEKIDEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload": { … }, "feedback": "Shorter opening scene"}'

payload is the whole new content, in the same structure as the payload you read. Updating or restoring resets the steps that depend on the artifact and puts the run back in waiting_input; confirm to continue with the new content. Invalid content returns 400 invalid_parameter, a running run returns 409 workflow_invalid_state, and brief and outline can only be changed on episode 1. An artifact version has kind, step, version, current, schema_version, source (generated or edited), feedback, payload and created_at.

Elements

GET /v1/dramas/{id}/elements returns the drama’s characters, scenes and props. Each has a code, kind (character, scene or prop), name, description and looks; each look has from_episode_no, label, description, image and, for characters, turnaround.

Media

Every image and video of an episode is a media slot (dmedia_…) with versions. category is character, turnaround, scene, prop, keyframe, clip, final, cover or poster.

Endpoint	Description
`GET /v1/dramas/{id}/media/{mediaId}`	The slot with its `current` and `latest` versions
`POST /v1/dramas/{id}/media/{mediaId}/regenerate`	Regenerate one item. Optional body: `prompt` (replaces the previous prompt), `feedback` (appended to it)
`GET /v1/dramas/{id}/media/{mediaId}/versions`	Every version, newest first
`POST /v1/dramas/{id}/media/{mediaId}/versions/{version}/adopt`	Make an earlier succeeded version current
`POST /v1/dramas/{id}/media/{mediaId}/upload`	Replace with an image uploaded through `POST /v1/files`. Body: `file_id`

Regenerate works on character, turnaround, scene, prop, keyframe, clip and poster. It opens its own charge (kind media) for that one item’s model cost and feature fee (one image, or the clip’s seconds; the poster has no feature fee), and does not reset any step.
Upload works on character, turnaround, scene, prop, keyframe and poster, and is free.
When a new version becomes current, media made from it are marked stale: true. Regenerate them if you want; the final video is not re-cut automatically.
Regenerate, adopt and upload return 409 workflow_invalid_state while the run is running. Regenerate also returns 409 while the item is already regenerating.

A media version has version, status (generating, succeeded or failed), source (generated, regenerated, uploaded or composed), file, generation_id, prompt, feedback, error_code and created_at. File urls are signed and expire; query again for fresh links.

Pricing

Each episode costs the model calls its steps make, at the same price as calling the models directly, plus a feature fee per step. See Billing for the current feature fees.

Get started

Generate

Workflows

Async and webhooks

Account

Create a drama

Steps

Dramas and episodes

Artifacts

Elements

Media

Pricing

​Create a drama

​Steps

​Dramas and episodes

​Artifacts

​Elements

​Media

​Pricing

Create a drama

Steps

Dramas and episodes

Artifacts

Elements

Media

Pricing