Workflows

Estimate and run a Workflow Starter

Price exact starter inputs, preserve the returned versions, and create one idempotent workflow run.

On this page

Estimate the exact inputs, starter_version, and optional account_id you intend to run. Estimation creates no media. A run is accepted only when its estimate and starter versions are still current and every paid step has a known cost.

Creation is the paid action. Send the estimate response's versions with the same inputs and a stable Idempotency-Key. Playground use is optional; direct API integrations follow the same contract.

After creation, use the returned links.self URL as described in Monitor, cancel, and retry.

Estimate the exact inputs

Estimate the exact intended inputs and current starter version. This request creates no media.

curl https://api.entirefeed.com/v1/workflow-starters/text-to-video-basic/estimate \
  -X POST \
  -H "Authorization: Bearer $ENTIREFEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "video_idea": "A slow product reveal with soft daylight and a clean studio background"
  },
  "starter_version": "st_0123456789abcdef01234567"
}'

200 Request-specific estimate

{
  "object": "workflow_starter_estimate",
  "starter_slug": "text-to-video-basic",
  "starter_version": "st_0123456789abcdef01234567",
  "estimated_cost": {
    "amount_usd": "1.53"
  },
  "estimated_micro_usd": 1530000,
  "line_items": [
    {
      "label": "Video generation",
      "amount_usd": "1.53",
      "confidence": "exact",
      "reason": "Calculated from the current starter inputs."
    }
  ],
  "unknown_costs": [],
  "estimate_version": "estimate_v1"
}

Continue only when unknown_costs is empty.Use the endpoint response as current pricing for the exact request; example amounts are illustrative.

Create one intended run

Creation is the paid action.The estimate is reserved while the run is active and reconciled against final usage.

curl https://api.entirefeed.com/v1/workflow-starters/text-to-video-basic/runs \
  -X POST \
  -H "Authorization: Bearer $ENTIREFEED_API_KEY" \
  -H "Idempotency-Key: launch-video-042" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "video_idea": "A slow product reveal with soft daylight and a clean studio background"
  },
  "starter_version": "st_0123456789abcdef01234567",
  "estimate_version": "estimate_v1",
  "metadata": {
    "customer_job_id": "launch-video-042"
  }
}'

201 Queued workflow run

{
  "id": "wrun_0123456789abcdef0123456789abcdef",
  "object": "workflow_run",
  "status": "queued",
  "starter_slug": "text-to-video-basic",
  "starter_version": "st_0123456789abcdef01234567",
  "created_at": "2026-07-14T08:30:00Z",
  "estimated_cost": {
    "amount_usd": "1.53"
  },
  "metadata": {
    "customer_job_id": "launch-video-042"
  },
  "links": {
    "self": "https://api.entirefeed.com/v1/workflow-runs/wrun_0123456789abcdef0123456789abcdef"
  }
}

Replay uncertain requests safely

Same intent

Repeat the same body and key after a timeout to recover the original run.

New intent

Changed inputs or metadata require a new estimate and key.

Handle preflight failures

409 workflow_estimate_requiredEstimate the workflow starter before running it. Estimate before creating the run.

409 workflow_estimate_staleWorkflow estimate is stale. Estimate again before running. Estimate the same intended inputs again.

409 starter_version_staleWorkflow starter version is stale. Read the starter, revalidate, and estimate again.

409 idempotency_conflictIdempotency-Key was reused with a different request body. Use the original body or a new intent key.

422 unknown_workflow_costWorkflow contains paid steps whose cost cannot be estimated. Stop; the run cannot reserve a known amount.

422 Cost cannot be determined

{
  "error": {
    "type": "unknown_workflow_cost",
    "code": "unknown_workflow_cost",
    "message": "Workflow contains paid steps whose cost cannot be estimated.",
    "request_id": "req_0123456789abcdef"
  }
}