Doodaro API reference

# .env (never commit this file)
DOODARO_API_KEY=ddr_live_...

Authorization: Bearer ddr_live_...

{"error": {"code": "not_found", "message": "Project not found."}}

-H "Idempotency-Key: generate-7f3c1c9e-2026-09-15"

{
  "id": "uuid",
  "title": "How planes fly",
  "revision": 7,
  "format": "portrait",
  "size": {"width": 1080, "height": 1920, "fps": 24},
  "engineVersion": "doodle-0.3.0",
  "style": {"id": "doodaro:<versionId>", "title": "Color Chalkboard"},
  "voice": {"id": "uuid", "name": "Damon"},
  "language": "en",
  "durationSeconds": 84,
  "readiness": {
    "scriptReady": true,
    "images": {"ready": 7, "total": 7},
    "voices": {"ready": 7, "total": 7},
    "canRender": true,
    "blockers": []
  },
  "scenes": [
    {
      "id": "uuid", "index": 0, "title": "The Everyday Miracle",
      "narration": "Every day, around a hundred thousand flights take off...",
      "visualDirection": "Vertical documentary composition at a busy airport...",
      "durationSeconds": 13.2,
      "image": {"status": "ready", "url": "/api/v1/media/<assetId>"},
      "voice": {"status": "ready", "url": "/api/v1/media/<assetId>", "durationSeconds": 11.8, "override": null}
    }
  ],
  "latestRender": {"id": "uuid", "status": "complete", "progress": 100, "videoUrl": "https://media.doodaro.com/..."},
  "dashboardUrl": "https://app.doodaro.com/?project=<id>#storyboard",
  "createdAt": "...", "updatedAt": "..."
}

// doodaro-flow.mjs
// Node.js 18 or newer (built-in fetch). Run on a server, not in a browser.
//   DOODARO_API_KEY=ddr_live_... node doodaro-flow.mjs
import { writeFile } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';

const BASE = 'https://app.doodaro.com/api/v1';
const KEY = process.env.DOODARO_API_KEY;
if (!KEY) throw new Error('Set DOODARO_API_KEY first.');

const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
const TERMINAL = new Set(['complete', 'failed', 'cancelled', 'uncertain']);

// One helper for every call: auth header, JSON body, error object, 429 retry.
async function api(method, path, body, { idempotencyKey } = {}) {
  for (let attempt = 0; ; attempt++) {
    const headers = { Authorization: `Bearer ${KEY}` };
    if (body !== undefined) headers['Content-Type'] = 'application/json';
    if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;

    const res = await fetch(BASE + path, {
      method,
      headers,
      body: body === undefined ? undefined : JSON.stringify(body),
    });

    if (res.status === 429 && attempt < 5) {
      const seconds = Number(res.headers.get('Retry-After')) || 5;
      await sleep(seconds * 1000);
      continue;
    }

    const data = await res.json().catch(() => ({}));
    if (!res.ok) {
      const error = new Error(`${res.status} ${data.error?.code}: ${data.error?.message}`);
      error.status = res.status;
      error.code = data.error?.code;
      throw error;
    }
    return data;
  }
}

async function waitForJob(jobId) {
  for (;;) {
    const job = await api('GET', `/jobs/${jobId}`);
    console.log(`${job.type} job ${job.id}: ${job.status} ${job.progress ?? 0}%`);
    if (TERMINAL.has(job.status)) return job;
    await sleep(4000); // poll every 3 to 5 seconds
  }
}

// 1. Pick a style and a voice. Never invent ids.
const { styles } = await api('GET', '/styles?query=chalkboard');
const { voices } = await api('GET', '/voices?language=en');
const style = styles[0];
const voice = voices[0];

// 2. Create a project with your own scenes.
let project = await api('POST', '/projects', {
  title: 'How planes fly',
  format: 'portrait',
  styleId: style.id,
  voice: { id: voice.id, name: voice.name },
  language: 'en',
  scenes: [
    {
      title: 'Hook',
      narration: 'Every day, around a hundred thousand flights take off. Here is how a wing holds them up.',
      visualDirection: 'A busy airport at dawn, planes lined up on the runway.',
    },
    {
      title: 'Lift',
      narration: 'A wing pushes air down. The air pushes the wing up. That push is called lift.',
      visualDirection: 'A wing cross-section with arrows showing air flowing down and lift pointing up.',
    },
  ],
});
console.log('Project:', project.id, project.dashboardUrl);

// 3. Generate pictures and narration. The Idempotency-Key makes a retry safe.
const run = randomUUID();
const { jobs } = await api('POST', `/projects/${project.id}/generate`, {}, { idempotencyKey: `generate-${run}` });
const finished = await Promise.all(jobs.map(job => waitForJob(job.id)));
if (finished.some(job => job.status !== 'complete')) throw new Error('Generation did not complete.');

// 4. Read the project. get_project syncs finished assets first.
project = await api('GET', `/projects/${project.id}`);
if (!project.readiness.canRender) {
  throw new Error(`Not ready to render: ${JSON.stringify(project.readiness.blockers)}`);
}

// 5. Render the video and wait for it.
const { render } = await api('POST', `/projects/${project.id}/renders`, {}, { idempotencyKey: `render-${run}` });
const done = await waitForJob(render.id);
if (done.status !== 'complete') throw new Error(`Render ${done.status}: ${JSON.stringify(done.error)}`);

// 6. Download the MP4. videoUrl is a public link, so no key is sent.
const video = await fetch(done.result.videoUrl);
await writeFile('how-planes-fly.mp4', Buffer.from(await video.arrayBuffer()));
console.log('Saved how-planes-fly.mp4. Open in the dashboard:', project.dashboardUrl);

# doodaro_flow.py
# Python 3.9 or newer. pip install requests
#   DOODARO_API_KEY=ddr_live_... python doodaro_flow.py
import json
import os
import time
import uuid

import requests

BASE = "https://app.doodaro.com/api/v1"
KEY = os.environ["DOODARO_API_KEY"]
TERMINAL = {"complete", "failed", "cancelled", "uncertain"}

session = requests.Session()
session.headers["Authorization"] = f"Bearer {KEY}"


class DoodaroError(Exception):
    def __init__(self, status, code, message):
        super().__init__(f"{status} {code}: {message}")
        self.status, self.code = status, code


def api(method, path, body=None, idempotency_key=None):
    """One helper for every call: auth header, JSON body, error object, 429 retry."""
    headers = {}
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    for attempt in range(6):
        res = session.request(method, BASE + path, json=body, headers=headers, timeout=60)
        if res.status_code == 429 and attempt < 5:
            time.sleep(int(res.headers.get("Retry-After", "5")))
            continue
        try:
            data = res.json()
        except ValueError:
            data = {}
        if not res.ok:
            err = data.get("error", {})
            raise DoodaroError(res.status_code, err.get("code"), err.get("message"))
        return data


def wait_for_job(job_id):
    while True:
        job = api("GET", f"/jobs/{job_id}")
        print(f"{job['type']} job {job['id']}: {job['status']} {job.get('progress') or 0}%")
        if job["status"] in TERMINAL:
            return job
        time.sleep(4)  # poll every 3 to 5 seconds


# 1. Pick a style and a voice. Never invent ids.
style = api("GET", "/styles?query=chalkboard")["styles"][0]
voice = api("GET", "/voices?language=en")["voices"][0]

# 2. Create a project with your own scenes.
project = api("POST", "/projects", {
    "title": "How planes fly",
    "format": "portrait",
    "styleId": style["id"],
    "voice": {"id": voice["id"], "name": voice["name"]},
    "language": "en",
    "scenes": [
        {
            "title": "Hook",
            "narration": "Every day, around a hundred thousand flights take off. Here is how a wing holds them up.",
            "visualDirection": "A busy airport at dawn, planes lined up on the runway.",
        },
        {
            "title": "Lift",
            "narration": "A wing pushes air down. The air pushes the wing up. That push is called lift.",
            "visualDirection": "A wing cross-section with arrows showing air flowing down and lift pointing up.",
        },
    ],
})
print("Project:", project["id"], project["dashboardUrl"])

# 3. Generate pictures and narration. The Idempotency-Key makes a retry safe.
run = uuid.uuid4().hex
jobs = api("POST", f"/projects/{project['id']}/generate", {}, idempotency_key=f"generate-{run}")["jobs"]
finished = [wait_for_job(job["id"]) for job in jobs]
if any(job["status"] != "complete" for job in finished):
    raise SystemExit("Generation did not complete.")

# 4. Read the project. get_project syncs finished assets first.
project = api("GET", f"/projects/{project['id']}")
if not project["readiness"]["canRender"]:
    raise SystemExit("Not ready to render: " + json.dumps(project["readiness"]["blockers"]))

# 5. Render the video and wait for it.
render = api("POST", f"/projects/{project['id']}/renders", {}, idempotency_key=f"render-{run}")["render"]
done = wait_for_job(render["id"])
if done["status"] != "complete":
    raise SystemExit(f"Render {done['status']}: {json.dumps(done.get('error'))}")

# 6. Download the MP4. videoUrl is a public link, so no key is sent.
with requests.get(done["result"]["videoUrl"], stream=True, timeout=300) as video:
    video.raise_for_status()
    with open("how-planes-fly.mp4", "wb") as f:
        for chunk in video.iter_content(chunk_size=1 << 20):
            f.write(chunk)
print("Saved how-planes-fly.mp4. Open in the dashboard:", project["dashboardUrl"])