Batch automation

Batch manifests coordinate repeatable TTS, image and video jobs. They are JSON files with an explicit schema version. Validation is offline and never checks quota or submits work.

Manifest format

{
  "version": 1,
  "concurrency": 2,
  "onError": "continue",
  "tasks": [
    {
      "id": "narration",
      "command": "audio tts",
      "idempotencyKey": "launch-narration-v1",
      "input": {
        "voiceId": "VOICE_ID",
        "text": "Welcome to Kitta",
        "format": "mp3"
      },
      "output": "output/narration.mp3"
    },
    {
      "id": "cover",
      "command": "image generate",
      "idempotencyKey": "launch-cover-v1",
      "input": {
        "prompt": "A paper-cut city at sunrise",
        "resolution": "1k"
      },
      "output": "output/cover.png"
    }
  ]
}

Supported commands are audio tts, image generate, and video generate. input uses public API field names, not CLI flag aliases. Task IDs, idempotency keys and output paths must be unique. Concurrency is limited to 1–8 and a manifest can contain at most 1,000 tasks.

Validate and run

kitta batch validate tasks.json
kitta batch run tasks.json
kitta batch run tasks.json --concurrency 1

onError: continue lets independent items finish after a failure. onError: stop prevents new items from starting after the first failure; already-running items are allowed to finish.

Inspect and resume

kitta batch status RUN_ID
kitta batch resume RUN_ID
kitta batch resume RUN_ID --manifest moved/tasks.json

Resume skips completed items and reruns incomplete items with their original idempotency keys. It refuses a modified manifest. State contains command names, keys, statuses, remote task IDs and input fingerprints, but not prompts, text or media URLs. The original manifest remains the source of input.

A partial batch exits nonzero while still writing its summary to stdout. Progress and sanitized item errors are written to stderr. The CLI reports completed operations and returned quota data; it does not impose a hard spending cap because the current public APIs do not provide quote-and-reserve semantics.