Character automation API

Create, refine, save and reuse a character, then generate finished videos without opening the Vydra UI. Use a Bearer API key with jobs:read and jobs:write. Vydra returns media files for your own publishing tools.

Create a character and a video

const base = "https://www.vydra.ai/api/v1";
const headers = { Authorization: `Bearer ${process.env.VYDRA_API_KEY}`, "Content-Type": "application/json" };
async function api(path, method = "GET", body, extra = {}) {
  const res = await fetch(base + path, { method, headers: { ...headers, ...extra },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
  const data = await res.json();
  if (!res.ok) throw new Error(JSON.stringify(data));
  return data.data;
}
async function run(body, retryKey) {
  // Persist retryKey before submitting. Reuse it after a network error.
  const started = await api("/characters/runs", "POST", body, { "Idempotency-Key": retryKey });
  for (;;) {
    const result = await api("/characters/runs/" + started.runId);
    if (result.status === "completed") return result;
    if (["failed", "cancelled"].includes(result.status)) throw new Error(JSON.stringify(result.error));
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}
const image = await run({ action: "create", description: "A full-body cheerful clay robot in a blue jacket" }, "my-character-001");
const character = await api("/characters", "POST", { name: "Blue Robot", imageUrl: image.outputs.find(o => o.type === "image").url });
const sheet = await run({ action: "sheet", reference: { characterId: character.id } }, "my-sheet-001");
await api("/characters/" + character.id, "PATCH", { referenceSheetUrl: sheet.outputs.find(o => o.type === "image").url });
const video = await run({ action: "video", reference: { characterId: character.id }, prompt: "The robot waves and dances happily", duration: 5 }, "my-video-001");
const finishedVideoUrl = video.outputs.find(o => o.type === "video").url;
// Download finishedVideoUrl, then hand the file to your publishing tool.

Available actions

• design: send a messages array with user/assistant role and content. Each request costs 1 credit. GPT suggests character ideas and asks clarifying questions; completed outputs contain JSON text, with structured concepts in design. Choose a concept and pass its description to create to generate a GPT Image 2.5 preview. Refine ideas with more messages or refine images with edit.
• create: description → a full-body GPT Image 2.5 reference.
• edit: reference and description → a revised reference preserving the other details.
• sheet: reference and optional description → front, back and face reference sheet.
• video: reference, prompt, optional duration (4–15 seconds, default 5), aspectRatio (9:16, 16:9 or 1:1) → Seedance 2.5 video at 720p.
• recast: sourceVideoUrl, reference, optional additionalReferences (up to three), subjectDescriptions and resolution (720p or 1080p). Wan 3.0 Prime Edit powers new swaps. Upload a 4–15 second video and choose up to four characters. References match people from left to right by default; optional descriptions identify specific people. Motion and original audio are preserved through the existing delivery pipeline.
• template: templateId and ordered references → the same saved recipe and provider routing as the UI.

A reference is either {"characterId":"UUID","useReferenceSheet":false} or {"imageUrl":"workspace-owned URL"}. Reference sheets are opt-in and must exist. Creating an image, editing it or generating a sheet does not overwrite a saved character: explicitly POST /characters to save, or PATCH /characters/{id} to replace its image or sheet. Replacing imageUrl clears an older sheet unless a replacement sheet is supplied.

Run a template

GET /api/v1/character-templates returns published templates, reference counts and role labels in exact order. Each reference can identify a different saved character. Object roles accept an uploaded image. Background overrides apply only to templates that accept them; referenceIndex starts at zero. Car Jump accepts a car image as the second reference, or carDescription with only the character reference.

{
  "action": "template",
  "templateId": "instagram-kitchen-tactical-dance",
  "references": [
    {
      "characterId": "FIRST_CHARACTER_UUID"
    },
    {
      "characterId": "SECOND_CHARACTER_UUID"
    }
  ]
}

Kitchen Dance keeps the saved source, role order, audio and configured Kling → Seedance → WAN fallback. A template marked templateImageRequired needs its templateImagePath downloaded from the Vydra website and uploaded to your workspace as templateImageUrl. GT3 Swap needs sourceVideoUrl from your workspace and an empty references array.

Uploads, saved characters and finished output

POST /api/v1/character-swap/prepare with either sourceUrl (a public Instagram reel/post) or videoUrl (a workspace upload). Optionally supply segment: {start, end} in seconds to choose a 4–30 second section. It returns data.videoUrl, durationSec, a thumbnail and audio metadata. Use that normalized MP4 as sourceVideoUrl for a recast run. Longer sources require an explicit section; blocked Instagram posts return INSTAGRAM_UPLOAD_REQUIRED and can be uploaded instead.

Use the upload API to get a signed upload URL, PUT the file, then use the returned public URL. Character references must be owned PNG, JPEG or WebP files in the same workspace. Source videos must be owned MP4 files. GET /characters lists saved characters; GET, PATCH and DELETE /characters/{id} manage one character. To rename or change its description, PATCH name or description. To make it the default, PATCH isDefault: true.

GET /characters/runs/{id} returns status, creditsUsed, error and outputs. Outputs remain empty until the whole run completes; then each entry contains type and url (or text). Download completed files promptly and store them in your own media system. Do not treat an intermediate frame as a finished video. Cancel future steps with PATCH /studio/runs/{id} and {"action":"cancel"}; submitted jobs settle with normal charges and refunds.

These routes use the existing Studio database and worker. Deploy the application and its existing character/Studio migrations before using them in production. See OpenAPI for complete input schemas and Studio for arbitrary workflows and saved workflows.