API Reference & Specification

POST /ask AUTH: X-API-KEY Send a video with custom prompt instructions; get back exact result.

MULTIPART/FORM-DATA PARAMETERS

prompt · string — Required. The prompt instruction defining your exact transcript, summary, or JSON schema.

file · file — Optional. Video (mp4, webm, mov), image (png, jpg), or PDF document. Up to 8 auxiliary files per ask.

provider · string — "aistudio" (default), "wrapper", or "gemini". All three share the same queue, caps and error codes; only the transport differs. Omit it and the operator's default is used.

model · string — Pin target model. Default: gemini-3.8-flash.

timeoutMs · number — Allowed execution budget in milliseconds (default: 180000, max: 600000).

progressId · string — Optional client tracking token to poll live steps via GET /progress/:id.

temporary · boolean — Default true. Forces isolated throwaway session with zero server retention.

RESPONSE (200 OK)

{
  "ok": true,
  "reply": "00:00.120 Speaker 1: Complete data privacy...\n00:04.300 Speaker 2: Instant JSON output.",
  "provider": "aistudio",
  "callId": "call-a4f91b-…"
}

GET /progress/:id AUTH: X-API-KEY / SESSION Poll real-time timeline steps for an in-flight prompt request.

RESPONSE (200 OK)

{
  "ok": true,
  "steps": [
    { "name": "browser:starting", "ms": 14 },
    { "name": "composer:typing", "ms": 120 },
    { "name": "generation:running", "ms": 10420 },
    { "name": "request:completed", "ms": 12480 }
  ]
}

POST /jobs AUTH: X-API-KEY Initialize a partitioned long-form video dubbing or transcription job.

JSON PARAMETERS

durationMs · number — Total video duration in milliseconds.

chunkMs · number — Target slice duration (e.g. 180000 for 3 min chunks).

overlapMs · number — Boundary overlap (e.g. 15000 for 15s continuity).

GET /health PUBLIC System liveness check, browser daemon status, and queue telemetry.

{
  "ok": true,
  "status": "ready",
  "defaultProvider": "aistudio",
  "chrome": "running",
  "browsers": [ 9223, 9222 ],
  "idle": false
}

ERR ERROR SPECIFICATION & RECOVERY STANDARD Deterministic machine-readable failure codes and retry strategies.

ERROR CODE	HTTP	RETRYABLE	DESCRIPTION
QUEUE_FULL	429	true	Server busy; concurrent pipeline processing queue depth limit reached.
QUOTA_EXCEEDED	429	false	Account or invitation token request limit cap has been exhausted.
CLIENT_GONE	499	false	Caller closed HTTP socket connection before prompt execution completed.
CHUNK_OFFSET_OUT_OF_RANGE	400	false	Multipart job chunk timing offset falls outside valid duration boundaries.