Create, Studio, and the media library

Create with the interface

Create supports image, video, and speech models, prompt refinement, and one to four variations. The displayed credit estimate covers all selected variations. Inspiration thumbnails only select a look; “Try this prompt” fills the prompt without generating. “View API request” exposes the configured JSON request. Each variation is a separate job, so one failure does not discard other results.

Studio includes templates, typed connections, notes, groups, duplicate, undo/redo, arrangement, saved run history, and JSON/ZIP import and export. Text, image, video, and audio inputs can be overridden by an API request. Talking portrait and motion transfer nodes connect voiceovers and video references to images.

The media library combines completed generations with uploaded and saved references. Search, favorite, rename, and organize saved media into folders. Video previews can save the current frame as a new image reference when the media host allows cross-origin capture.

Create your first saved graph

Download the example request JSON and save it as studio-image-workflow.json. It defines a textInput node named prompt, a Nano Banana Pro generation node, and an output node named result. Saving the graph does not run it or charge generation credits.

curl -X POST https://vydra.ai/api/v1/studio/workflows \
  -H "Authorization: Bearer $VYDRA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @studio-image-workflow.json

HTTP 201 returns {"data":{"id":"WORKFLOW_ID","name":"API image example"}}. Use that ID below. The example’s default image costs 75 credits. Unlike the canonical job response, Studio and library responses wrap resource objects in data.

A graph contains nodes and edges, with up to 100 nodes and 300 edges. Nodes need id, type, position, and data; edges connect compatible named handles. Read a saved graph with GET /studio/workflows/{id} to discover its input IDs. Input overrides target node IDs, not display labels or model parameter names. Text, image, video, and audio inputs take strings; media inputs use accessible HTTPS URLs. Graph structure is checked when saved, and execution validity is checked when a run starts.

Run a saved workflow

Use a Bearer API key or a signed-in session. Studio and library reads require jobs:read; writes require jobs:write. Keys with jobs:* or * also work. All resources belong to the authenticated organization.

curl https://vydra.ai/api/v1/studio/workflows \
  -H "Authorization: Bearer $VYDRA_API_KEY"

curl https://vydra.ai/api/v1/studio/workflows/WORKFLOW_ID/run \
  -H "Authorization: Bearer $VYDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: campaign-2026-09-05-01" \
  -d '{"inputs":{"prompt":"A cinematic product photograph"}}'

curl https://vydra.ai/api/v1/studio/runs/RUN_ID \
  -H "Authorization: Bearer $VYDRA_API_KEY"

Creation returns {"data":{"runId":"…","creditsEstimated":75,"status":"running"}} with HTTP 202. Poll the run to receive its status, per-node results and job IDs, outputs, and net credits used. Reuse the same idempotency key for a retry of the same workflow and inputs. A replay returns HTTP 200 with data.runId and data.creditsEstimated; poll that ID for current status. Keys are organization-scoped and at most 200 characters. Editing the saved graph does not change a previous run or make an old key start it again. Reusing it with different inputs returns 409. A fresh key starts a new billable run.

Read results and stop a run

Poll GET /studio/runs/{id} every 5 seconds while data.status is running. Terminal statuses are completed, failed, and cancelled. Read per-node jobId, status, output, and error from data.nodeResults. In the example graph, the final image URL is data.nodeResults.result.output.imageUrl. data.creditsUsed reports net charged credits after recorded refunds; do not treat an estimate as a reservation.

curl -X PATCH https://vydra.ai/api/v1/studio/runs/RUN_ID \
  -H "Authorization: Bearer $VYDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"cancel"}'

HTTP 202 acknowledges the cancellation request, not immediate completion. Keep polling until terminal. A missing or no-longer-running run returns 404. Deleting a workflow with an active run returns 409. Invalid graph/input requests return 400, missing scope returns 403, and run submission rate limits return 429.

Endpoints

Paths above are relative to /api/v1. Generated job assets remain available through /assets; deleting a saved library entry does not delete a completed job.

Portable workflows and HeliosGen

JSON exports preserve reference URLs. ZIP exports include input media: 4 MB per asset, 40 MB per bundle. Larger media can be used through HTTPS URLs. Import supports Vydra v1 files and compatible HeliosGen v1 manifests: prompts, image/video inputs, comments, groups, and matching generation models. It converts terminal nodes to explicit outputs.

HeliosGen models without a matching provider adapter, assistant chat histories, and unsupported frame/reference handles are rejected with an explanation. Imported workflows never silently substitute a model. Provider credentials and local desktop paths are not transferred.

Speech and prompt refinement

Submit generate_speech through POST /jobs with {"prompt":"Your script","voice_id":"21m00Tcm4TlvDq8ikWAM"}. Speech costs one credit per started 100 characters. Submit improve_prompt with a prompt to receive refined text for one credit. Both accept up to 10,000 characters and require the corresponding provider to be configured.

The MCP source includes saved workflow discovery, execution, and status tools, plus creator catalog and media library tools. Build and publish the updated package before using those additions from a package registry.