Workflows

A workflow is a product that takes several steps to finish, such as one episode of a short drama or a video clone. Each step calls models (text, image, video, speech) or processes media on GEEKIDEA’s side. You start a workflow from its own endpoint, for example POST /v1/dramas, and get back a run (run_…). Progress, confirmation, redo and cancellation go through the shared /v1/workflow_runs endpoints.

Catalog

GET /v1/workflows lists the workflows you can call. GET /v1/workflows/{author}/{slug} returns one of them. Both work without an API key; anonymous calls list public workflows only. The same catalog is on geekidea.ai/workflows.

curl https://api.geekidea.ai/v1/workflows/geekidea/drama-episode \
  -H "Authorization: Bearer $GEEKIDEA_API_KEY"

{
  "id": "geekidea/drama-episode",
  "object": "workflow",
  "name": "Short drama episode",
  "description": "Makes one episode of a short drama from a brief or a script: …",
  "version": 1,
  "start_path": "/v1/dramas",
  "steps": [
    { "key": "understand", "type": "ai", "depends_on": [], "confirm": true, "fee_units": ["step"] },
    { "key": "story", "type": "ai", "depends_on": ["understand"], "confirm": true, "fee_units": ["step"] },
    …
  ],
  "fee_price_version": 1,
  "fees": [
    { "step": "understand", "spec": null, "unit": "step", "unit_price_usd": 0.04 },
    …
  ],
  "currency": "USD"
}

Field	Description
`id`	Workflow ID: `geekidea/drama-episode` or `geekidea/video-clone`
`start_path`	The endpoint that starts it
`steps`	Each step’s `key`, `type` (`ai` calls models, `local` processes media, `input` waits for you), `depends_on`, whether it stops for `confirm`, and the `fee_units` it charges by
`fees`, `fee_price_version`	The current feature fee prices, see Billing

POST /v1/workflows/{author}/{slug}/quote takes the same body as the start endpoint and runs nothing. It returns estimated_cost_usd (the amount held for the first segment), its model_cost_usd and fee_usd, total_cost_usd for all steps, and each step with next_segment showing whether it is in the first segment. Model cost is an estimate; you pay for the calls actually made.

Runs

GET /v1/workflow_runs/{id} returns the run with its steps and costs.

{
  "id": "run_0192f1c3a7b87c3e9a4f5b6c7d8e9f01",
  "object": "workflow.run",
  "workflow": "geekidea/drama-episode",
  "status": "waiting_input",
  "progress": 22,
  "auto_continue": false,
  "budget_usd": 20,
  "model_cost_usd": 0.0612,
  "fee_usd": 0.08,
  "cost_usd": 0.1412,
  "held_usd": null,
  "error_code": null,
  "steps": [
    { "key": "understand", "status": "succeeded", "attempt": 1, "error_code": null, "started_at": 1791425100, "finished_at": 1791425130, "confirmed_at": 1791425200 },
    { "key": "story", "status": "waiting_input", "attempt": 1, "error_code": null, "started_at": 1791425201, "finished_at": 1791425260, "confirmed_at": null },
    { "key": "asset_check", "status": "skipped", "attempt": 1, "error_code": null, "started_at": null, "finished_at": 1791425100, "confirmed_at": null },
    …
  ],
  "created_at": 1791425100,
  "finished_at": null
}

Field	Description
`status`	`pending`, `running`, `waiting_input`, `succeeded`, `failed` or `cancelled`
`progress`	0–100
`auto_continue`	Whether steps continue without stopping for confirmation
`budget_usd`	Budget of the run in USD; `null` when unlimited
`model_cost_usd`, `fee_usd`, `cost_usd`	Settled model cost, feature fee and total. Only finished segments are included
`held_usd`	Amount held for the segment in progress; `null` when nothing is running
`error_code`	Why the run failed
`steps`	Every step, in order

Step status is one of:

Status	Meaning
`pending`	Not started yet
`running`	Running now
`waiting_input`	Finished and waiting for your confirmation, or paused because the segment ran out of money (`error_code` says why)
`succeeded`	Done (and confirmed, if it needed confirmation)
`failed`	Failed after automatic retries; `error_code` says why
`skipped`	Does not apply to this run, for example `asset_check` in episode 1 of a drama. Skipped steps are not charged
`cancelled`	The run was cancelled before the step finished

A failed step is retried automatically when the error allows it; attempt counts the tries. Retries don’t charge the feature fee again.

Stream progress

GET /v1/workflow_runs/{id}/events streams the run as Server-Sent Events. Each time the status, progress, cost or a step changes, you get a workflow.run event with the whole run object. When the run ends you get data: [DONE] and the stream closes.

curl -N https://api.geekidea.ai/v1/workflow_runs/run_0192f1c3a7b87c3e9a4f5b6c7d8e9f01/events \
  -H "Authorization: Bearer $GEEKIDEA_API_KEY"

id: 3f9a1c0b7d2e4a65
event: workflow.run
data: {"id":"run_0192f1c3a7b87c3e9a4f5b6c7d8e9f01","object":"workflow.run","status":"running","progress":11,…}

: ping

data: [DONE]

A : ping comment is sent every 15 seconds while nothing changes.
A connection lasts at most 30 minutes. Reconnect with the Last-Event-ID header set to the last id you received; if nothing has changed since, nothing is sent again. Changes in between are not replayed: you get the latest state.
A run in waiting_input keeps the stream open until it ends or the connection times out.

Confirmation points

Some steps stop for confirmation when they finish: the step becomes waiting_input, and so does the run. You can then read and edit what the step produced (for example a drama’s storyboard or a clone’s plan) before anything more is spent. Which steps stop is shown by confirm in the catalog and in each guide.

GET /v1/workflow_runs/{id}/quote returns what confirming will hold: estimated_cost_usd for the steps up to the next confirmation point (or to the end), and total_cost_usd for all remaining steps.
POST /v1/workflow_runs/{id}/confirm accepts the waiting steps, holds the next segment and continues.

curl -X POST https://api.geekidea.ai/v1/workflow_runs/run_0192f1c3a7b87c3e9a4f5b6c7d8e9f01/confirm \
  -H "Authorization: Bearer $GEEKIDEA_API_KEY" \
  -H "Idempotency-Key: drama-42-confirm-story"

Confirm returns the run. It returns 409 workflow_invalid_state when the run is not waiting_input, and 402 when your balance, the API key’s limit or budget_usd can’t cover the next segment. To skip confirmations, turn on auto-confirm when you start the workflow (auto_confirm: true on dramas and video clones). The run’s auto_continue is then true: steps that would stop for confirmation succeed right away, and the whole run is held as one segment.

Budget

Set budget_usd when you start a workflow to cap what the run may cost. Before each segment starts (start, confirm, redo), GEEKIDEA checks that the settled cost plus the segment’s estimate stays within the budget; if not, the request fails with 402 workflow_budget_exceeded and nothing starts. A segment is held at an estimate. If the actual spending reaches the held amount, or your balance or key limit runs out, the step that needed more stops as waiting_input with error_code workflow_charge_exhausted (or workflow_budget_exceeded, insufficient_quota, api_key_limit_reached). The run pauses in waiting_input and a workflow.budget_exceeded webhook is sent. Confirming queues that step again under a new hold.

Redo a step

POST /v1/workflow_runs/{id}/steps/{stepKey}/redo resets the step and every step that depends on it, holds the cost of running them again, and starts.

curl -X POST https://api.geekidea.ai/v1/workflow_runs/run_0192f1c3a7b87c3e9a4f5b6c7d8e9f01/steps/storyboard/redo \
  -H "Authorization: Bearer $GEEKIDEA_API_KEY" \
  -H "Idempotency-Key: drama-42-redo-storyboard-1"

Allowed when the run is waiting_input, succeeded or failed. A run that is running or cancelled, or a skipped step, returns 409 workflow_invalid_state. An unknown step returns 404 workflow_step_not_found.
Redo is charged like new work: model calls and feature fees of the earlier attempt are not refunded.

Editing a product’s output (for example PUT on a drama artifact or a clone plan) also resets the steps that depend on it and puts the run back in waiting_input; confirm to continue with your edit.

Cancel

POST /v1/workflow_runs/{id}/cancel cancels the run. Unfinished steps become cancelled, and model calls in flight are cancelled too. Costs already incurred (finished calls and succeeded steps) are charged; the rest of the hold is released. Cancelling a run that has already ended returns it unchanged.

Charges

A workflow is billed per charge (wfc_…): one hold and one settlement for each segment of steps between confirmation points. Charges are opened by:

Kind	When
`start`	Starting the workflow, and each confirm
`redo`	Redoing a step
`media`	Regenerating a single image or clip from a product endpoint

When a charge opens, its estimated cost (model cost + feature fees of the segment) is held from your balance once. Model calls inside the segment don’t hold separately.
When the segment ends, the charge settles at the actual model cost plus the feature fees of the steps that succeeded, never more than the hold. The rest is released.
The feature fee prices are locked when the charge opens.

What you pay, in practice:

A step’s feature fee is charged once when it succeeds. Automatic retries are not charged twice, and failed model calls are not charged.
A redo opens a new charge and charges the steps again, feature fee included.
Cancelling keeps already-succeeded steps and finished calls charged.

GET /v1/generations/{id} accepts a run ID or a charge ID. For a run it returns the total over all its charges; for a charge, that segment. Both include line_items: every model call (type: "model", with its id, model, step and cost) and every feature fee (type: "workflow_fee", with step, unit, quantity, unit_price and amount). usage.cost_details splits the cost into models and workflow_fee. See Billing for prices.

Idempotency

Send Idempotency-Key when you start a workflow, start the next drama episode, create a clone revision, confirm or redo. Within a project, a key is accepted once: a retry with the same key returns the existing drama, clone or run, and nothing is held twice. Use a new key for each operation.

Webhooks

Webhook endpoints can subscribe to workflow events:

Event	When	`data`
`workflow.step.completed`	A step succeeded	Step event: `object` (`workflow.step`), `run_id`, `workflow`, `progress` and `step`
`workflow.waiting_input`	The run stopped for confirmation	The run object
`workflow.budget_exceeded`	The run paused because a step ran out of money	The run object
`workflow.completed`	The run succeeded	The run object
`workflow.failed`	The run failed	The run object
`workflow.cancelled`	The run was cancelled	The run object

The run object is the same as GET /v1/workflow_runs/{id}.

Get started

Generate

Async and webhooks

Account

Workflows

Catalog

Runs

Stream progress

Confirmation points

Budget

Redo a step

Cancel

Charges

Idempotency

Webhooks

​Catalog

​Runs

​Stream progress

​Confirmation points

​Budget

​Redo a step

​Cancel

​Charges

​Idempotency

​Webhooks

Catalog

Runs

Stream progress

Confirmation points

Budget

Redo a step

Cancel

Charges

Idempotency

Webhooks