Video generation

POST /v1/generation/clips renders a clip of the person or character in your image, moving the way your prompt describes, and speaking your audio if you send some. It runs on the Atmee V2 renderer, and you get a downloadable mp4 back in the same request, or after a retry when the renderer is starting cold.

Use it for UGC-style ads, product explainers, social posts, spokesperson intros, and character shots for games and stories. Clips work best when a person or character is the subject of the shot; a scene without one, such as a place or a product on its own, can work too, but results vary. For the images that animate badly, see Avatar 101: Negative examples.

Before you startCopy Anchor Link

• Atmee V2 access on a plan with clips. Without V2 access the call answers v2_access_required; there is no Atmee V1 clip.
• A key with generation:write and avatars:write. See what every generation call has in common.
• A server. Call the API from your backend only; the key never goes to a browser.
• Permission. If the image shows a real person other than you, get that person's permission first.

Make a clipCopy Anchor Link

curl -X POST https://api.atmanity.us/v1/generation/clips \
  -H "X-Api-Key: $ATMEE_API_KEY" \
  -H "Idempotency-Key: 6f1c2a9e-3b7d-4c11-9a52-0d8e4f7b2c61" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/host.png",
    "prompt": "she holds up the bottle and smiles, the camera slowly pushing in",
    "audio": "https://example.com/line.mp3",
    "durationSeconds": 12
  }'

{
  "clip": {
    "upload": "upload:3b2f6e1a-9c4d-4f8e-a1b2-7c6d5e4f3a2b",
    "url": "https://…/clip.mp4",
    "expiresAt": "2026-11-05T09:12:44Z",
    "durationSeconds": 12,
    "width": 512,
    "height": 512,
    "unavailable": false
  },
  "replayed": false
}

Request fieldsCopy Anchor Link

SizesCopy Anchor Link

Set the clip's size with resolution. Leave it out for a square clip.

Not every account can use every size yet. To see which ones yours can:

1. Call GET /v1/account with your key.
2. Look at pricing.generation.clipResolutions: it lists the sizes you can ask for. If it isn't there at all, every size is open to you.

Asking for a size that isn't on that list fails with 400 invalid_input, and the error message names the sizes you can use instead.

Longer videosCopy Anchor Link

A clip is at most 15 seconds. For a longer video, make several clips and join them:

1. Split the script or audio into parts of 15 seconds or less, at a pause between sentences so the joins don't land mid-word.
2. Make one clip per part, with the same image and size for each so the person looks the same throughout, and a new Idempotency-Key for each.
3. Join the mp4s in order. Every clip is 25 fps at the size you asked for, so they join without re-encoding:

# parts.txt lists the clips in order, one per line: file 'part1.mp4'
ffmpeg -f concat -safe 0 -i parts.txt -c copy video.mp4

Each part is billed as its own clip, so a 60-second video made of four 15-second clips costs 4 credits.

CostCopy Anchor Link

1 credit per clip, whatever its length, with or without sound, on Growth and up. To check what a call cost, read microcreditsCharged in its answer: it counts in hundredths of a credit, so 100 is 1 credit, and a replay shows 0.

You pay only for a clip you get: flagged, failed and refused calls cost nothing, and so does a replay. Your balance and the key's spend cap are checked before the render starts.

ErrorsCopy Anchor Link

Clips answer the errors every generation call shares, plus:

Node exampleCopy Anchor Link

Make a clip, retry while it renders, and save the mp4. Node 18 or later.

import { randomUUID } from "node:crypto";
import { writeFile } from "node:fs/promises";

const BASE = "https://api.atmanity.us";

export async function makeClip(input) {
  const key = randomUUID(); // one key for this clip, reused on every retry
  for (;;) {
    const res = await fetch(`${BASE}/v1/generation/clips`, {
      method: "POST",
      headers: {
        "X-Api-Key": process.env.ATMEE_API_KEY,
        "Idempotency-Key": key,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(input),
    });
    // A wrong key answers 401 as plain text or no body, so never assume JSON.
    const text = await res.text();
    let body = {};
    try {
      body = text ? JSON.parse(text) : {};
    } catch {
      body = { message: text };
    }
    if (res.ok) return body.clip;
    const code =
      typeof body.error === "string" ? body.error : `http_${res.status}`;
    const retry = ["request_in_progress", "rate_limited"].includes(code);
    if (!retry) throw new Error(`${res.status} ${code}: ${body.message ?? ""}`);
    const wait = Number(res.headers.get("Retry-After") ?? 10);
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
}

const clip = await makeClip({
  image: "https://example.com/host.png",
  prompt: "he waves at the camera and laughs",
  durationSeconds: 8,
});
const mp4 = await fetch(clip.url);
await writeFile("clip.mp4", Buffer.from(await mp4.arrayBuffer()));