Imagera Motion Pro API

Higher-fidelity transfer of a reference video’s motion onto a still character image.

imagera-motion-transfer-proVideo editingvideo100–200 credits

Calling the API

Install the client

Nothing to install. The API is plain HTTPS and JSON, so the HTTP client already in your project is the client — fetch, requests, curl. There is no SDK.

Setup your API key

Keys are shown once. Keep yours in an environment variable — never in source control, never in client-side code.

Create an API key

bashEnvironment

# Put the key in your environment, never in source control.
export IMAGERA_API_KEY="ima_sk_YOUR_KEY"

Submit a request

Name the model in the path, send its parameters as the JSON body. The call returns a request_id immediately; generation continues in the background.

javascriptPOST /v1/queue/imagera-motion-transfer-pro

const response = await fetch(
  "https://api.imagera.ai/v1/queue/imagera-motion-transfer-pro",
  {
    method: "POST",
    headers: {
      "Authorization": `Key ${process.env.IMAGERA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "ref_image": "https://example.com/input.jpg",
      "video": "https://example.com/input.mp4"
    }),
  },
);

// 202 Accepted — the job is queued, not finished.
const job = await response.json();
console.log(job.request_id, job.status);

Authentication

API key

Every request carries your key in the Authorization header. Use the Key scheme.

httpRequest header

Authorization: Key ima_sk_YOUR_KEY

Bearer is accepted as well, so an HTTP client that only speaks that scheme works unchanged — it is the same key, not a different credential. Scheme matching is case-insensitive.

Keys are revocable per integration and stop working within about a minute. Rotate by creating the new key, deploying it, then revoking the old one.

Pricing

100–200 credits per request. The exact cost depends on speed.

Credit cost by speed
Speed	Credits
`standard`	100
`ultra-fast`	200

A failed generation is refunded automatically. API calls draw on the same credit balance as the studios.

Webhooks

Webhooks are the intended way to learn that a generation finished: you submit, we call your server when it is done, and you never hold a connection open or run a polling loop.

Register an endpoint

Endpoints are registered against your account, not passed per request, so a leaked request body cannot redirect your callbacks. Each gets its own signing secret, shown once.

• HTTPS only — plaintext http:// is refused.
• Must resolve to public internet space. Private, loopback, link-local and cloud metadata addresses are refused.
• Ports 443 and 8443.
• Redirects are followed up to 3 hops, and every hop is re-validated.
• No credentials in the URL.

jsonPOST your endpoint — Imagera-Webhook-Event-Type: generation.completed

{
  "event_id": "evt_7c1f9a3e5b2d4086a1c3e5f7b9d0",
  "event_type": "generation.completed",
  "api_version": "2026-07-31",
  "created_at": "2026-07-31T08:42:17.000Z",
  "request_id": "req_8f3c1a9e2b7d",
  "status": "OK",
  "data": {
    "request_id": "req_8f3c1a9e2b7d",
    "gateway_request_id": "req_8f3c1a9e2b7d",
    "status": "COMPLETED",
    "model": "imagera-motion-transfer-pro",
    "credits_used": 100,
    "timings": {
      "inference_seconds": 4.2
    },
    "videos": [
      {
        "url": "https://example.com/output.mp4",
        "file_name": "output.mp4",
        "content_type": "video/mp4"
      }
    ],
    "output_count": 1
  },
  "error": null
}

Verify the signature

Verify every delivery before you trust it. The body hash is inside the signed string, so a valid signature proves both the sender and the exact bytes.

Use the raw request bytes. Re-serialising parsed JSON changes key order and whitespace and will never reproduce the hash. This is the most common integration failure.

javascriptVerify a delivery

const crypto = require("node:crypto");

function verifyImageraWebhook(rawBody, headers, secrets, toleranceSeconds = 300) {
  const eventId   = headers["imagera-webhook-id"];
  const timestamp = headers["imagera-webhook-timestamp"];
  const header    = headers["imagera-webhook-signature"];
  if (!eventId || !timestamp || !header) return false;

  // Replay bound. Without it a captured request is valid forever.
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > toleranceSeconds) return false;

  const bodyHash     = crypto.createHash("sha256").update(rawBody).digest("hex");
  const signedString = `v1\n${eventId}\n${timestamp}\n${bodyHash}`;

  // The header may carry SEVERAL signatures during a secret rotation.
  const candidates = header.split(/\s+/)
    .filter((p) => p.startsWith("v1="))
    .map((p) => Buffer.from(p.slice(3), "hex"));

  return [].concat(secrets).some((secret) => {
    const expected = crypto.createHmac("sha256", secret).update(signedString).digest();
    return candidates.some(
      (c) => c.length === expected.length && crypto.timingSafeEqual(c, expected),
    );
  });
}

// Express — note express.raw(), NOT express.json().
app.post("/imagera", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyImageraWebhook(req.body, req.headers, [process.env.IMAGERA_WEBHOOK_SECRET])) {
    return res.status(401).send("bad signature");
  }
  const event = JSON.parse(req.body.toString("utf8"));
  // Dedupe on event.event_id, then acknowledge fast.
  res.status(200).send("ok");
});

Retries and delivery

Delivery is at-least-once, so the same event can arrive twice. Record the event_id values you have processed and ignore repeats — it is stable across every attempt.

Return 2xx as soon as the event is durably queued and do the work afterwards; a handler slower than 10s is retried unnecessarily. Failed attempts back off 1s → 2s → 4s → 8s → 16s, up to 6 attempts. A 4xx other than 408, 425 or 429 is permanent and is not retried.

Reject any delivery whose Imagera-Webhook-Timestamp is more than 300 seconds from your clock — that is the replay bound.

Queue

Every generation is queued. These endpoints are how you reconcile state — after a missed webhook, on restart, or to cancel. Poll sparingly; prefer the webhook.

Submit a request

POST /v1/queue/imagera-motion-transfer-pro returns 202 Accepted. Follow the URLs it gives you rather than rebuilding them.

json202 Accepted

{
  "request_id": "req_8f3c1a9e2b7d",
  "status": "IN_QUEUE",
  "model": "imagera-motion-transfer-pro",
  "status_url": "https://api.imagera.ai/v1/queue/requests/req_8f3c1a9e2b7d/status",
  "response_url": "https://api.imagera.ai/v1/queue/requests/req_8f3c1a9e2b7d",
  "cancel_url": "https://api.imagera.ai/v1/queue/requests/req_8f3c1a9e2b7d/cancel"
}

Fetch request status

Status is one of IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELLED. The last three are terminal — stop asking once you see one.

javascript/v1/queue/requests/{id}/status

// Prefer the status_url the submit response gave you.
const res = await fetch(job.status_url, {
  headers: { "Authorization": `Key ${process.env.IMAGERA_API_KEY}` },
});
const { status } = await res.json();

Get the result

Once the status is COMPLETED, fetch the result from response_url. Errors come back as application/problem+json documents with a machine-readable code, so you can branch on the code rather than on message text.

javascript/v1/queue/requests/{id}

const res = await fetch(job.response_url, {
  headers: { "Authorization": `Key ${process.env.IMAGERA_API_KEY}` },
});
const result = await res.json();

Files

Anywhere the schema names a URI you can pass either an inline data URI or a public URL. There is no upload endpoint to call first, and generated outputs come back as URLs you can feed straight into a follow-up request.

Data URI (base64)

Simplest for small inputs. Base64 inflates the payload by about a third, so prefer a URL for anything large.

javascriptInline upload

import { readFile } from "node:fs/promises";

const bytes = await readFile("./input.jpg");
const dataUri = `data:image/jpeg;base64,${bytes.toString("base64")}`;

// Pass it anywhere the schema expects a URI.
body: JSON.stringify({ ref_image: dataUri })

Hosted files (URL)

Any publicly reachable HTTPS URL. It must be readable without authentication — a signed URL works, a private bucket does not.

javascriptHosted input

body: JSON.stringify({"ref_image":"https://example.com/input.jpg"})

Uploading files

Pass a data URI for small files, or host the file yourself and pass its URL. Nothing else is required.

Schema

Input

ref_imagestring (uri)required

Character image to animate

videostring (uri)required

Reference motion video (3-30s)

promptstringoptional

Optional scene description

Max length: 2500

image_urlstring (uri)optional

processing_speedstringoptional

Delivery tier. "ultra-fast" routes to the accelerated path and is priced separately (see the `speed` column of this model's price table).

Options: standard, ultra-fast

Default "standard"

Minimal example

jsonRequired only

{
  "ref_image": "https://example.com/input.jpg",
  "video": "https://example.com/input.mp4"
}

Full example

jsonAll parameters

{
  "image_url": "https://example.com/input.jpg",
  "processing_speed": "standard",
  "prompt": "a lighthouse at dusk, long exposure",
  "ref_image": "https://example.com/input.jpg",
  "video": "https://example.com/input.mp4"
}

Output

Returns video as URLs, not inline bytes. On the result response they arrive at the top level under videos, alongside request_id, status, model, credits_used and timings.

A webhook delivery wraps that same object one level down, in the event's data field, and adds output_count — so event.data.videos on a callback is result.videos when you fetch it yourself. Only the webhook has a data field.

The output payload is not published as a formal schema, so it is not documented field-by-field here rather than being guessed at. Submit one request and inspect the response to see its exact shape.