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.

34 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

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/create-job

Create a spend-gated video generation job

Backward-compatible alias for /api/v1/video/create. This endpoint may start paid generation only after successful authentication, request validation, deterministic preflight, provider capability validation, and credit/BYOK authorization. LTX lip-sync preflight failures return 422 with no_credits_spent=true and no provider dispatch.

Parameters

NameInDescription
Idempotency-Key header optional Recommended for paid generation retries; reused keys are deduplicated per user and body hash.

Responses

StatusMeaning
202 Job accepted after credit/BYOK authorization and dispatch recorded
402 Insufficient credits; provider was not dispatched
422 Preflight or validation failed; no credits spent for pre-dispatch failures
425 Idempotent request still processing
POST /api/v1/video/start

Create and start a long-video job

Responses

StatusMeaning
202 Job started
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