v1.0.0 · read-only reference · foundation

Supervised mass generation, over HTTP

Request photos and video in bulk and let the platform hold them to a standard: every batch persists a job before dispatch, survives a disconnect, is scored against its requirements, and repairs only the frames that failed.

38 operations Base https://myeq-full-1015143369529.europe-west4.run.app Spec /api/v1/openapi

Product maturity

This contract exposes foundations and experimental operations. It does not claim the complete storyboard product is finished.

Maturity foundation Availability internal Complete no Manifest /api/v1/product/manifest

Authentication

Every endpoint requires a bearer token. This page is a reference only — it never asks for, stores, or sends a credential.

generate is not callable with just a storyboard id: it requires the execution manifest hash that plan just priced, so a copy-pasted example has to show both calls.

PLAN=$(curl -s -X POST https://myeq-full-1015143369529.europe-west4.run.app/api/v1/projects/{projectId}/film-intelligence/storyboard-images/plan \
  -H "Authorization: Bearer $MYEQ_API_KEY" \
  -H "Content-Type: application/json")
HASH=$(echo "$PLAN" | jq -r '.executionManifestArtifact.artifactHash')

curl -X POST https://myeq-full-1015143369529.europe-west4.run.app/api/v1/projects/{projectId}/film-intelligence/storyboard-images/generate \
  -H "Authorization: Bearer $MYEQ_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{ \"expectedExecutionManifestArtifactHash\": \"$HASH\" }"

Mass generation

POST /api/v1/image/storyboard-batch

Render a small photo batch inline (synchronous, unsupervised)

Renders frames and returns them in the response. There is no job id and no QA: use this only for batches small enough to finish inside one request. continuityMode="chain" (the default) renders one frame at a time, conditioning each frame on the previous frame's output, so its ceiling is much lower than the parallel modes. Requests above the ceiling are rejected with 413 BEFORE any credit is charged and carry the durable path in durable_alternative. For genuine mass generation, or for anything that must meet a quality standard, use the supervised path: storyboard-images/plan then storyboard-images/generate. Feature-flagged (STORYBOARD_PHOTO_BATCH_ENABLED).

Responses

StatusMeaning
200 status=completed when every frame rendered, status=partial when some failed. Failed frames are refunded.
402 Insufficient credits; nothing was dispatched
403 Insufficient scope or forbidden project
413 Batch cannot finish synchronously. no_credits_spent=true; durable_alternative names the supervised endpoints to use instead.
429 Rate limit exceeded; retry_after_seconds returned
503 Storyboard photo batch not enabled
POST /api/v1/projects/{projectId}/film-intelligence/storyboard-images/plan

Compile the authoritative work plan for a supervised image batch

Returns the single authority for what will be generated, what it will cost, and what is missing: every required frame, the reference plates it depends on, the resolved provider, the credit ceiling, and any blocker that would stop execution. Spends no credits. Call this before generate to see the full cost and the blocker list.

Parameters

NameInDescription
projectId path required

Responses

StatusMeaning
200 Work plan with per-frame requirements, credit ceiling and blockers
403 Forbidden project
404 Project or storyboard not found
409 Script revision conflict: the storyboard is stale against its source revision
POST /api/v1/projects/{projectId}/film-intelligence/storyboard-images/generate

Start a durable, supervised image batch

The supervised mass-generation entry point, and the one to build on. Persists a job before dispatching, so the batch survives client disconnects and process restarts. Execution is lease-exclusive: a duplicate delivery of the same task cannot make one job run twice. After rendering, every frame is scored against its requirements and failures enter a bounded repair loop with a per-requirement attempt limit, a per-shot credit ceiling and an escalation ladder that ends in human review rather than unbounded retries. Requires expectedExecutionManifestArtifactHash: call plan first and copy executionManifestArtifact.artifactHash from its response. Without it this returns 400 storyboard_image_execution_manifest_required — the hash pins execution to the exact plan that was priced, so a stale plan cannot be executed silently. Returns 202 with a job to poll (job.id, then GET film-intelligence/jobs/{jobId}) — unless every selected requirement was already satisfied by a prior call, in which case it returns 200 with accepted=false and no job: check accepted before assuming a job started.

Parameters

NameInDescription
projectId path required
Idempotency-Key header optional Recommended. Job identity is content-addressed, so a replayed request returns the existing job instead of starting a second one.

Responses

StatusMeaning
200 Idempotent no-op: every selected requirement was already satisfied by a prior call. accepted=false, no job, nothing charged.
202 Job persisted and enqueued. The polling handle is job.id (nested), not a top-level jobId.
402 Insufficient credits for the plan ceiling; nothing was dispatched
403 Forbidden project
404 Project or storyboard not found
409 Script revision conflict, or the storyboard already has an active job
422 Plan has blockers that must be resolved before generation
GET /api/v1/projects/{projectId}/film-intelligence/jobs/{jobId}

Poll a durable generation job

Authoritative job state. status is queued, running, completed, partially_completed or failed. completed means every required frame was rendered AND passed review; partially_completed reports which requirements still failed and whether the batch is resumable. Safe to poll from any client, including one that did not start the job.

Parameters

NameInDescription
projectId path required
jobId path required

Responses

StatusMeaning
200 Job state, per-requirement results and QA evidence
403 Forbidden project
404 Job not found
GET /api/v1/projects/{projectId}/film-intelligence/photo-sequences/{planId}

Read a photo sequence plan and its current lifecycle

The plan, its frames and where it currently stands. Spends nothing. Use it to price a repair before authorizing one, and to see the lifecycle without mutating anything.

Parameters

NameInDescription
projectId path required
planId path required

Responses

StatusMeaning
200 Plan, frames and lifecycle
403 Forbidden project
404 Plan not found
POST /api/v1/projects/{projectId}/film-intelligence/photo-sequences/{planId}/review

Record a human accept/repair decision per frame

This is the human authority step, NOT the automatic scorer. Automatic scoring runs inside the generation job, and its verdicts and evidence are read from film-intelligence/jobs/{jobId} — not here. This endpoint records what a person decided about each frame, so it requires a decisions array (frameIndex, accept|repair, a note, optional prompt additions) and an existing QA report for the plan. Calling it without decisions returns 400, and with no prior QA report returns 409.

Parameters

NameInDescription
projectId path required
planId path required

Responses

StatusMeaning
201 Decisions recorded; the plan lifecycle advances to reflect them
400 No decisions supplied, or a decision failed validation
403 Forbidden project
404 Plan not found
409 No QA report exists yet for this plan; generate and let scoring run first
POST /api/v1/projects/{projectId}/film-intelligence/photo-sequences/{planId}/repair

Repair only the frames that failed review

Regenerates the failing requirements and nothing else, so accepted frames are frozen rather than re-rolled. Bounded by attempts per requirement, requests per shot and a credit ceiling; each escalation tightens constraints before falling back to a frozen prompt, and exhausting the ladder returns human_review instead of spending more.

Parameters

NameInDescription
projectId path required
planId path required

Responses

StatusMeaning
202 Repair job accepted; poll for the new verdicts
402 Repair would exceed the authorized credit ceiling
403 Forbidden project
404 Plan not found
409 Repair budget or attempt ladder exhausted; human review required
GET /api/v1/production/capabilities

What this deployment can actually execute right now

Runtime capability truth, not documentation. Each capability reports configured plus the honest limitations that apply, so a client (or an agent) can check whether a workload is executable before spending anything. Unconfigured providers are reported as unavailable rather than failing at dispatch.

Responses

StatusMeaning
200 Capability list with configured flags and limitations

Audio

POST /api/v1/audio/tts

Convert text to a neural voice

Responses

StatusMeaning
200 Audio generated and URL returned
POST /api/v1/tts

Text-to-speech (legacy alias)

Responses

StatusMeaning
200 Audio generated and URL returned

Commerce

POST /api/v1/commerce/videos

Generate a personalized commerce video (abandoned cart / post-purchase)

Generate a short vertical LTX video for a shopper from a commercial event. trigger=abandoned_cart produces an objection-handling video; trigger=post_purchase produces a cross-sell video. Send dryRun=true to preview the resolved brief + payload without spending credits. LTX only.

Responses

StatusMeaning
200 Dry-run preview (brief + payload, nothing generated)
202 Generation started (job returned)
422 Invalid request
503 Commerce video API not enabled

Credits

GET /api/v1/credits/summary

Get current user credit summary (stripe + bonus + total)

Responses

StatusMeaning
200 Credit summary payload

Delivery

POST /api/v1/delivery

Deliver a finished video to agnostic destinations (webhook / email / Drive)

Delivers an already-rendered video; spends NO generation credits. Webhook is fully wired (SSRF-guarded + HMAC-signed via X-MYEQ-Signature); email and google_drive return an honest "unsupported" until their adapters land. Feature-flagged (UNIVERSAL_DELIVERY_ENABLED).

Responses

StatusMeaning
200 Per-destination delivery results
422 Invalid request
503 Delivery API not enabled

Image

POST /api/v1/image/generate

Generate a static AI image

Responses

StatusMeaning
200 Image generated

Music

POST /api/v1/music

Compose an original AI song

Responses

StatusMeaning
200 Music generated and URL returned
POST /api/v1/music/generate

Generate music via async orchestration pipeline

Responses

StatusMeaning
202 Music generation accepted
GET /api/v1/music/status/{jobId}

Check generated music status by job id

Parameters

NameInDescription
jobId path required

Responses

StatusMeaning
200 Music status payload

Other

POST /api/v1/video/create-job

Retired direct video entrypoint

Direct v1 creation is retired. Default/24 FPS returns 410 VIDEO_V1_DIRECT_CREATE_RETIRED. Requests for 30/60 return 422 VIDEO_FPS_SNAPSHOT_REQUIRED; retired/unsupported 25/48/50 return 422. No cadence clamp, credit charge or dispatch occurs. Use the committed snapshot preflight-scene and generate-scene routes.

Responses

StatusMeaning
410 Legacy creation retired; migrate to committed snapshots.
422 Explicit FPS migration or unsupported cadence; no credits spent.
POST /api/v1/video/start

Retired direct video entrypoint

Direct v1 creation is retired. Default/24 FPS returns 410 VIDEO_V1_DIRECT_CREATE_RETIRED. Requests for 30/60 return 422 VIDEO_FPS_SNAPSHOT_REQUIRED; retired/unsupported 25/48/50 return 422. No cadence clamp, credit charge or dispatch occurs. Use the committed snapshot preflight-scene and generate-scene routes.

Responses

StatusMeaning
410 Legacy creation retired; migrate to committed snapshots.
422 Explicit FPS migration or unsupported cadence; no credits spent.
POST /api/v1/production/snapshots/preflight-scene

Preflight one scene without generating or spending credits

Uses the same snapshot compiler and adapter readiness as generation. Authenticated CPU health may run. Creates no render job, project write or credit reservation. Success does not reserve worker availability or wallet balance.

Responses

StatusMeaning
200 Readiness decision: data.ready, issues, estimatedCredits, exact fps and noCreditsSpent=true. A blocked decision is not an admission.
400 Invalid snapshot or target scene.
401 Authentication required.
403 Project/workspace permission denied.
409 Confirmation required, active scene conflict or stale state.
422 Exact scene class or preflight rejected; no credits spent.
503 Required runtime readiness unavailable.
POST /api/v1/production/snapshots/generate-scene

Generate one committed scene at its exact admitted FPS

Shares Studio authorization, cost, source, worker readiness and dispatch authority. Requires confirm=true and Idempotency-Key. Unsupported or unavailable classes fail before credit reservation. Paid submission is never automatically retried.

Parameters

NameInDescription
Idempotency-Key header required

Responses

StatusMeaning
200 Engine result with pendingTake/variation and durable job metadata; no completion is implied by acceptance.
400 Invalid snapshot or target scene.
401 Authentication required.
403 Project/workspace permission denied.
409 Confirmation required, active scene conflict or stale state.
422 Exact scene class or preflight rejected; no credits spent.
503 Required runtime readiness unavailable.
POST /api/v1/video/create

Retired direct video entrypoint

Direct v1 creation is retired. Default/24 FPS returns 410 VIDEO_V1_DIRECT_CREATE_RETIRED. Requests for 30/60 return 422 VIDEO_FPS_SNAPSHOT_REQUIRED; retired/unsupported 25/48/50 return 422. No cadence clamp, credit charge or dispatch occurs. Use the committed snapshot preflight-scene and generate-scene routes.

Responses

StatusMeaning
410 Legacy creation retired; migrate to committed snapshots.
422 Explicit FPS migration or unsupported cadence; no credits spent.
POST /api/v1/video/preflight

Retired direct video entrypoint

Direct v1 creation is retired. Default/24 FPS returns 410 VIDEO_V1_DIRECT_CREATE_RETIRED. Requests for 30/60 return 422 VIDEO_FPS_SNAPSHOT_REQUIRED; retired/unsupported 25/48/50 return 422. No cadence clamp, credit charge or dispatch occurs. Use the committed snapshot preflight-scene and generate-scene routes.

Responses

StatusMeaning
410 Legacy creation retired; migrate to committed snapshots.
422 Explicit FPS migration or unsupported cadence; no credits spent.

Projects

GET /api/v1/projects

List user projects

Responses

StatusMeaning
200 Project list
POST /api/v1/projects

Create a project

Responses

StatusMeaning
200 Project created

Status

GET /api/v1/download/{jobId}

Resolve final downloadable URL for a project or orchestrator job

Parameters

NameInDescription
jobId path required

Responses

StatusMeaning
200 Final asset URL payload
GET /api/v1/jobs/{jobId}

Get async job status and progress

Parameters

NameInDescription
jobId path required

Responses

StatusMeaning
200 Current status

Storage

GET /api/v1/storage/preview

Proxy an allowlisted image preview URL

No open proxy: only HTTPS URLs from approved hosts are fetched; Wasabi objects are signed with a one-hour TTL.

Parameters

NameInDescription
url query required

Responses

StatusMeaning
200 Image stream
400 Missing or disallowed URL
413 Image too large
415 Remote resource is not an image
POST /api/v1/storage/upload-url

Get a signed URL for direct S3 upload

Issues a short-lived upload URL under the authenticated user prefix. Category limits: PHOTOS 20 MB, VIDEOS 500 MB, MUSIC/SFX/VOICES 100 MB.

Responses

StatusMeaning
200 Presigned URL returned, including maxBytes for the resolved category
400 Invalid category, contentType, or sizeBytes
401 Unauthorized
413 File exceeds category size limit
GET /api/v1/storage/assets

List assets available in Creative Hub library (videos, photos, music, voices)

Responses

StatusMeaning
200 Asset library grouped by type

User

GET /api/v1/user/settings/creative

Get user creative-agent personalization settings

Responses

StatusMeaning
200 Creative profile payload
PUT /api/v1/user/settings/creative

Update user creative-agent personalization settings

Responses

StatusMeaning
200 Creative profile saved

Video

POST /api/v1/video/orchestrate

Create an orchestrated multimodal video job

Responses

StatusMeaning
202 Job started
GET /api/v1/video/quality-check/{jobId}

Run AI quality director review for a video project

Parameters

NameInDescription
jobId path required

Responses

StatusMeaning
200 Quality coherence report payload
GET /api/v1/video/status/{jobId}

Check generated video status by job id

Parameters

NameInDescription
jobId path required

Responses

StatusMeaning
200 Video status payload

Workspaces

GET /api/v1/workspaces

List accessible workspaces

Responses

StatusMeaning
200 Workspace list
401 Unauthorized
POST /api/v1/workspaces

Create a team workspace

Responses

StatusMeaning
201 Workspace created
400 Invalid name
401 Unauthorized
DELETE /api/v1/workspaces

Delete/detach a non-protected workspace

Requires owner membership. Personal/default and last remaining workspaces are protected. Assets are not permanently deleted by this endpoint.

Parameters

NameInDescription
id query required

Responses

StatusMeaning
200 Workspace removed and nextWorkspaceId returned
403 Forbidden or protected workspace
409 Cannot delete last workspace