ottoport 1.5.2 → 1.6.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ottoport",
   "description": "One API for every model. Call chat, image, video, speech and music models through the OttoPort gateway — as MCP tools, slash commands, or the bundled CLI.",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "author": {
     "name": "LITBOX LLC",
     "email": "support@ottoport.ai"

package/README.md

@@ -26,6 +26,8 @@ ottoport image --model qwen-image-layered --image <url> [--layers 4]
 ottoport video "<prompt>" [--model kling-3.0] [--duration 5] [--resolution 1080p]
                           [--aspect-ratio 16:9] [--image <url>] [--last-frame <url>]
                           [--ref <url>[,<url>…]] [--out clip.mp4]
+                          [--webhook-url https://…] [--no-wait]
+ottoport webhook status|retry <job-id>   # delivery attempts / redeliver now
 ottoport speech "<text>"  [--model gpt-4o-mini-tts] [--voice alloy] [--out speech.mp3]
 ottoport music "<prompt>" [--model suno-v5] [--duration 15] [--out song.mp3]
 
@@ -75,7 +77,8 @@ forwarded from the environment rather than written into any config file.
 ## MCP tools
 
 `ottoport_list_models`, `ottoport_chat`, `ottoport_generate_image`,
-`ottoport_generate_video`, `ottoport_generate_speech`, `ottoport_generate_music`.
+`ottoport_generate_video`, `ottoport_video_webhook`, `ottoport_generate_speech`,
+`ottoport_generate_music`.
 The server speaks stdio JSON-RPC and is launched by the host as a subprocess, so
 it needs Node 20+ on the PATH of whatever starts that host.
 
@@ -99,6 +102,17 @@ reads, pass `model` to that tool or run `ottoport models <model-id>`. Asking
 for something a model does not offer is refused with its actual list, before a
 generation is spent.
 
+### Webhooks
+
+Pass `webhook_url` (MCP) or `--webhook-url` (CLI) with a video to have OttoPort
+POST the finished job to that HTTPS endpoint as `video.completed` or
+`video.failed`. Deliveries are signed:
+`x-ottoport-signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>`.
+Failed deliveries are retried after 1, 5, 30 and 120 minutes, 5 attempts in
+all (redirects are not followed); `ottoport webhook retry <job-id>` or `ottoport_video_webhook` sends
+one again at any time. Verification examples are at
+https://ottoport.ai/docs#webhooks.
+
 ## Configuration
 
 - `OTTOPORT_API_KEY` — your `op-…` key. Export it from your shell profile: the
@@ -108,13 +122,17 @@ generation is spent.
   only for local development or a self-hosted gateway.
 - `OTTOPORT_BASE_URL` configures the MCP server only; it does not silently
   redirect CLI traffic.
+- `OTTOPORT_WEBHOOK_SECRET` — the secret video webhooks are signed with, used
+  when a webhook URL is given without an explicit secret. Keep it in the
+  environment rather than on the command line.
 
 ## Notes
 
 - Image, video, and audio calls return **URLs**, and provider URLs expire.
   Download anything worth keeping.
 - Video generation takes a minute or more and the call blocks until the job is
-  terminal. A retry is a second billable generation, not a resumption.
+  terminal, unless a webhook is given or `--no-wait` is passed. A retry is a
+  second billable generation, not a resumption.
 - `resolution` is a price multiplier, not a formatting hint. Leave it unset to
   bill at the model's base tier.
 - Requests are billed against the prepaid balance on your OttoPort account.

package/cli/ottoport.mjs

@@ -257,11 +257,13 @@ async function cmdImage(prompt, flags) {
 }
 
 async function cmdVideo(prompt, flags) {
-  if (!prompt) die("video requires a prompt: ottoport video \"a drone shot\"");
+  // A depth model needs only --video; the gateway refuses a prompt there.
+  if (!prompt && !last(flags.video)) die("video requires a prompt: ottoport video \"a drone shot\" (or --video <url> on a depth model)");
   const { baseUrl, apiKey } = config(flags);
   const body = {
     model: last(flags.model) || "kling-3.0",
-    prompt,
+    ...(prompt ? { prompt } : {}),
+    ...(last(flags.video) ? { video_url: last(flags.video) } : {}),
     ...(last(flags.duration) ? { duration: Number(last(flags.duration)) } : {}),
     ...(last(flags.resolution) ? { resolution: last(flags.resolution) } : {}),
     ...(last(flags["aspect-ratio"]) ? { aspect_ratio: flags["aspect-ratio"] } : {}),
@@ -269,6 +271,7 @@ async function cmdVideo(prompt, flags) {
     ...(last(flags.image) ? { image_url: flags.image } : {}),
     ...(last(flags["last-frame"]) ? { last_frame_url: flags["last-frame"] } : {}),
     ...(references(flags) ? { reference_image_urls: references(flags) } : {}),
+    ...webhook(flags),
   };
   console.error("submitting video job (this can take a minute)…");
   const res = await fetch(`${baseUrl}/api/v1/videos/generations`, {
@@ -279,7 +282,8 @@ async function cmdVideo(prompt, flags) {
   if (!res.ok) die(await readError(res));
   let job = await res.json();
   if (job.status === "failed") die(job.error || "video generation failed", 2);
-  if (!flags["no-wait"]) {
+  if (body.webhook_url) process.stderr.write(`webhook: ${body.webhook_url} will be notified when the job finishes\n`);
+  if (flags.wait !== false) {
     process.stderr.write(`job ${job.id} accepted; waiting for completion…\n`);
     while (job.status === "queued" || job.status === "processing") {
       await new Promise((resolve) => setTimeout(resolve, 3_000));
@@ -298,6 +302,42 @@ async function cmdVideo(prompt, flags) {
   }
 }
 
+/**
+ * `--webhook-url` registers the job's webhook. The secret comes from
+ * `--webhook-secret` or OTTOPORT_WEBHOOK_SECRET; flags are visible in shell
+ * history and `ps`, so the environment is the better home for it.
+ */
+function webhook(flags) {
+  const url = last(flags["webhook-url"]);
+  if (!url) return {};
+  const secret = last(flags["webhook-secret"]) || process.env.OTTOPORT_WEBHOOK_SECRET;
+  if (!secret) die("--webhook-url needs a signing secret: set OTTOPORT_WEBHOOK_SECRET or pass --webhook-secret");
+  return { webhook_url: url, webhook_secret: secret };
+}
+
+function describeDelivery(d) {
+  const response = d.response_status ? `HTTP ${d.response_status}` : d.attempts ? "no response" : "not sent";
+  return `${d.event}  ${d.status}  ${d.attempts}/${d.max_attempts} attempts  ${response}${d.response_body ? `  ${d.response_body.slice(0, 120)}` : ""}`;
+}
+
+async function cmdWebhook(action, jobId, flags) {
+  if (!["status", "retry"].includes(action) || !jobId) die("usage: ottoport webhook status|retry <job-id> [--json]");
+  const { baseUrl, apiKey } = config(flags);
+  const path = `${baseUrl}/api/v1/videos/generations/${encodeURIComponent(jobId)}`;
+  const res = action === "retry"
+    ? await fetch(`${path}/webhook`, { method: "POST", headers: headers(apiKey, false) })
+    : await fetch(path, { headers: headers(apiKey, false) });
+  if (!res.ok) die(await readError(res));
+  const body = await res.json();
+  if (flags.json) return void console.log(JSON.stringify(body, null, 2));
+  const deliveries = action === "retry" ? body.deliveries : body.webhook?.deliveries;
+  if (action === "status" && !body.webhook) return void console.log(`job ${jobId} (${body.status}) was submitted without a webhook`);
+  if (action === "status") console.log(`job ${jobId} (${body.status}) → ${body.webhook.url}`);
+  if (!deliveries?.length) return void console.log("no deliveries yet — one is sent when the job finishes");
+  for (const d of deliveries) console.log(describeDelivery(d));
+  if (action === "retry" && deliveries[0].status !== "delivered") process.exitCode = 2;
+}
+
 async function cmdAudio(kind, prompt, flags) {
   if (!prompt) die(`${kind} requires a prompt: ottoport ${kind} "hello"`);
   const { baseUrl, apiKey } = config(flags);
@@ -345,7 +385,12 @@ Usage:
   ottoport video "<prompt>" [--model kling-3.0] [--duration 5] [--resolution 1080p]
                             [--aspect-ratio 16:9] [--seed 7] [--image <url>]
                             [--last-frame <url>] [--ref <url>[,<url>…]]
+                            [--webhook-url https://…] [--webhook-secret <s>]
                             [--no-wait] [--out clip.mp4]
+  ottoport video --model video-depth-anything --video <url> [--out depth.mp4]
+                            turn a video (≤60s) into a grayscale depth video
+  ottoport webhook status <job-id> [--json]   delivery attempts and responses
+  ottoport webhook retry  <job-id> [--json]   redeliver a finished job's webhook now
   ottoport speech "<text>" [--model gpt-4o-mini-tts] [--voice alloy] [--format mp3] [--out speech.mp3]
   ottoport music  "<prompt>" [--model suno-v5] [--duration 15] [--format mp3] [--out song.mp3]
   ottoport mcp
@@ -356,6 +401,7 @@ Usage:
 Global flags:
   --url <base>   override https://ottoport.ai (local/self-hosted development)
   --key <key>    OttoPort API key       (env OTTOPORT_API_KEY)
+  --webhook-secret <s>  signs webhook deliveries (env OTTOPORT_WEBHOOK_SECRET)
 
 Examples:
   export OTTOPORT_API_KEY=op-...
@@ -365,6 +411,8 @@ Examples:
   ottoport image "isometric city at dusk" --model gpt-image-2 --out city.png
   ottoport video "cinematic product reveal" --model seedance-2.0-fast --resolution 1080p
   ottoport video "the logo unfolds" --image start.png --last-frame end.png
+  ottoport video "drone over fjords" --webhook-url https://example.com/hooks/ottoport --no-wait
+  ottoport webhook retry 7c1e9a52-…
   ottoport image "her, on a beach" --ref face.png,style.png
   ottoport image --model seedream-5.0-layers --image https://…/poster.png
   ottoport speech "Welcome to OttoPort" --voice alloy --out welcome.mp3
@@ -384,6 +432,7 @@ async function main() {
       case "chat": return await cmdChat(prompt, flags);
       case "image": return await cmdImage(prompt, flags);
       case "video": return await cmdVideo(prompt, flags);
+      case "webhook": return await cmdWebhook(rest[0], rest[1], flags);
       case "speech": return await cmdAudio("speech", prompt, flags);
       case "music": return await cmdAudio("music", prompt, flags);
       case "mcp": return await import(new URL("../mcp/server.mjs", import.meta.url));

package/mcp/server.mjs

@@ -177,17 +177,25 @@ async function generateImage({ prompt, model, ...rest }) {
   return lines.length ? lines.join("\n") : "(no image returned)";
 }
 
-async function generateVideo({ prompt, model, ...rest }) {
-  if (!prompt) throw new Error("`prompt` is required");
+async function generateVideo({ prompt, model, webhook_url, webhook_secret, ...rest }) {
+  // A depth model takes only `video_url`; the gateway says which models need a prompt.
+  if (!prompt && !rest.video_url) throw new Error("`prompt` is required");
+  // The secret is best left in the server's environment, so an agent never has
+  // to carry it through a conversation.
+  const secret = webhook_secret || process.env.OTTOPORT_WEBHOOK_SECRET;
+  if (webhook_url && !secret) throw new Error("`webhook_url` needs a signing secret: set OTTOPORT_WEBHOOK_SECRET for the MCP server or pass `webhook_secret`");
   const res = await fetch(`${BASE}/api/v1/videos/generations`, {
     method: "POST",
     headers: { ...headers(), "idempotency-key": crypto.randomUUID() },
     // Passed through; see `generateImage` for why this layer names nothing.
-    body: JSON.stringify({ model: model || "kling-3.0", prompt, ...rest }),
+    body: JSON.stringify({ model: model || "kling-3.0", ...(prompt ? { prompt } : {}), ...rest, ...(webhook_url ? { webhook_url, webhook_secret: secret } : {}) }),
   });
   if (!res.ok) throw new Error(await gwError(res));
   let job = await res.json();
   if (job.status === "failed") throw new Error(job.error || "video generation failed");
+  // With a webhook the caller has said where the result should go; holding the
+  // tool call open for minutes as well would only block the agent.
+  if (webhook_url) return `Video job ${job.id} is ${job.status}. ${webhook_url} will receive video.completed or video.failed when it finishes; check deliveries with ottoport_video_webhook.`;
   // The public video endpoint is deliberately asynchronous. MCP tools should
   // still fulfil their promise of returning usable output, so wait for the
   // job rather than returning a queued-job JSON blob to the agent.
@@ -204,6 +212,18 @@ async function generateVideo({ prompt, model, ...rest }) {
   return url || JSON.stringify(job);
 }
 
+async function videoWebhook({ job_id, action = "status" }) {
+  if (!job_id) throw new Error("`job_id` is required");
+  const path = `${BASE}/api/v1/videos/generations/${encodeURIComponent(job_id)}`;
+  const res = action === "retry"
+    ? await fetch(`${path}/webhook`, { method: "POST", headers: headers(false) })
+    : await fetch(path, { headers: headers(false) });
+  if (!res.ok) throw new Error(await gwError(res));
+  const body = await res.json();
+  if (action === "retry") return JSON.stringify(body.deliveries ?? [], null, 2);
+  return JSON.stringify({ id: body.id, status: body.status, webhook: body.webhook ?? null }, null, 2);
+}
+
 async function generateAudio(kind, { prompt, model, voice, duration, format }) {
   if (!prompt) throw new Error("`prompt` is required");
   const res = await fetch(`${BASE}/api/v1/audio/${kind === "tts" ? "speech" : "music"}`, {
@@ -275,18 +295,21 @@ const TOOLS = [
         image_url: { type: "string", description: "One reference image, for editing and image-to-image — or, on a layer-decomposition model, the image to split." },
         reference_image_urls: { type: "array", items: { type: "string" }, description: "Several references — a character sheet, a product plus a scene — up to the model's maxInputImages. Call ottoport_list_models to see it." },
         num_layers: { type: "number", description: "Layer models that let you choose (qwen-image-layered, 2–10): how many RGBA layers to split into. Each bills separately. seedream-5.0-layers decides for itself and refuses this." },
+        horizontal_angle: { type: "number", description: "Camera models only (qwen-image-angles): orbit in degrees, 0–360. Needs image_url; prompt optional." },
+        vertical_angle: { type: "number", description: "Camera models only: elevation in degrees, -30 (below) to 90 (overhead)." },
+        zoom: { type: "number", description: "Camera models only: 0 (wide) to 10 (close)." },
       },
     },
     handler: generateImage,
   },
   {
     name: "ottoport_generate_video",
-    description: "Generate a video through an OttoPort video model (Veo, Kling, Seedance, …). Four modes: text-to-video, image-to-video (`image_url`), first-and-last-frame (plus `last_frame_url`), and reference-to-video (`reference_image_urls`). Which a model accepts is in its capabilities — call ottoport_list_models. Blocks on the queue and returns a video URL.",
+    description: "Generate a video through an OttoPort video model (Veo, Kling, Seedance, …). Modes: text-to-video, image-to-video (`image_url`), first-and-last-frame (plus `last_frame_url`), reference-to-video (`reference_image_urls`), and on some models video edit/extend (`video_url`). video-depth-anything instead turns `video_url` into a grayscale depth video and takes no prompt. Which a model accepts is in its capabilities — call ottoport_list_models. Blocks on the queue and returns a video URL, unless `webhook_url` is given.",
     inputSchema: {
       type: "object",
       properties: {
-        prompt: { type: "string" },
-        model: { type: "string", description: "Model id, e.g. veo-3.1, kling-3.0, seedance-2.0-fast. Default kling-3.0." },
+        prompt: { type: "string", description: "Required, except on video-depth-anything, which takes none." },
+        model: { type: "string", description: "Model id, e.g. veo-3.1, kling-3.0, seedance-2.0-fast, video-depth-anything. Default kling-3.0." },
         duration: { type: "number", description: "Seconds. The main lever on what this costs." },
         // Per-model, not universal — see the note on the image tool. kling-3.0
         // has no 480p and no 4k; gemini-omni-flash has only 720p.
@@ -296,11 +319,29 @@ const TOOLS = [
         image_url: { type: "string", description: "First frame, for image-to-video." },
         last_frame_url: { type: "string", description: "Final frame. With `image_url`, this is first-and-last-frame generation." },
         reference_image_urls: { type: "array", items: { type: "string" }, description: "Subjects the shot carries through — a character, a product, a style — without being a frame of it." },
+        keyframes: { type: "array", items: { type: "object", properties: { image_url: { type: "string" }, time: { type: "number", description: "Seconds from the start; omit to spread evenly." } }, required: ["image_url"] }, description: "Images pinned in time, for keyframes-to-video." },
+        video_url: { type: "string", description: "A video to edit or extend, on models listing video-edit / video-extend — or the only input to video-depth-anything. Edits and depth bill per second of this video (at most 60s)." },
+        video_task: { type: "string", enum: ["edit", "extend"], description: "edit (default) restyles video_url; extend continues it for `duration` more seconds." },
+        webhook_url: { type: "string", description: "Public HTTPS endpoint to POST the finished job to (events video.completed / video.failed, signed with HMAC-SHA256). With it the tool returns the job id at once instead of waiting." },
+        webhook_secret: { type: "string", description: "Signing secret for webhook_url. Omit to use the server's OTTOPORT_WEBHOOK_SECRET." },
       },
-      required: ["prompt"],
+      required: [],
     },
     handler: generateVideo,
   },
+  {
+    name: "ottoport_video_webhook",
+    description: "Inspect or redeliver a video job's webhook. `status` returns the job and every delivery attempt with the endpoint's response; `retry` sends a finished job's webhook again now (resetting its 5 automatic attempts) and returns the result.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: { type: "string", description: "The video job id returned by ottoport_generate_video." },
+        action: { type: "string", enum: ["status", "retry"], description: "Default status." },
+      },
+      required: ["job_id"],
+    },
+    handler: videoWebhook,
+  },
   {
     name: "ottoport_generate_speech",
     description: "Convert text to speech through an OttoPort TTS model. Returns an audio URL or data URL.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ottoport",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Claude Code plugin, CLI and MCP server for OttoPort — one OpenAI-compatible API for every LLM, image, video, and speech model.",
   "homepage": "https://ottoport.ai",
   "repository": {

package/skills/ottoport/SKILL.md

@@ -17,7 +17,8 @@ and do not call the HTTP API, when a tool covers the job:
 | `ottoport_list_models` | The catalog: what each model is for, and its rate in credits and USD. Filter with `modality`, or pass `model` for ONE model in full — its modes, its resolution tiers with prices, and every parameter it reads. |
 | `ottoport_chat` | `prompt`, plus optional `model`, `system`, `temperature`, `max_tokens`. |
 | `ottoport_generate_image` | `prompt`, plus optional `model`, `size` or `resolution`, `aspect_ratio`, `n`, `seed`, `image_url` (one reference), `reference_image_urls` (several). Layer decomposition too: `model` `qwen-image-layered` or `seedream-5.0-layers` with `image_url` alone (prompt optional, `num_layers` on Qwen) returns one URL per RGBA layer. |
-| `ottoport_generate_video` | `prompt`, plus optional `model`, `duration`, `resolution`, `aspect_ratio`, `seed`, `image_url` (first frame), `last_frame_url`, `reference_image_urls`. |
+| `ottoport_generate_video` | `prompt`, plus optional `model`, `duration`, `resolution`, `aspect_ratio`, `seed`, `image_url` (first frame), `last_frame_url`, `reference_image_urls`, `webhook_url` (returns the job id at once and POSTs the result there; the secret comes from `webhook_secret` or the server's `OTTOPORT_WEBHOOK_SECRET`). |
+| `ottoport_video_webhook` | `job_id`, plus `action` `status` (every delivery attempt and the endpoint's response) or `retry` (redeliver a finished job's webhook now). |
 | `ottoport_generate_speech` | `prompt` (the text), plus optional `model`, `voice`, `format`. |
 | `ottoport_generate_music` | `prompt`, plus optional `model`, `duration`, `format`. |