ottoport 1.8.0 → 1.10.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.8.0",
+  "version": "1.10.0",
   "author": {
     "name": "LITBOX LLC",
     "email": "support@ottoport.ai"

package/cli/ottoport.mjs

@@ -253,8 +253,8 @@ async function download(url, out) {
  * what a shell user reaches for anyway, so both spellings are accepted:
  * `--ref a.png --ref b.png` and `--ref a.png,b.png`.
  */
-function references(flags) {
-  const raw = flags.ref ?? flags.reference;
+function references(flags, name = "ref") {
+  const raw = name === "ref" ? flags.ref ?? flags.reference : flags[name];
   const list = (Array.isArray(raw) ? raw : [raw])
     .filter(Boolean)
     .flatMap((value) => String(value).split(",").map((one) => one.trim()))
@@ -308,6 +308,8 @@ 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) } : {}),
+    ...(references(flags, "ref-video") ? { reference_video_urls: references(flags, "ref-video") } : {}),
+    ...(references(flags, "ref-audio") ? { reference_audio_urls: references(flags, "ref-audio") } : {}),
     ...webhook(flags),
   };
   console.error("submitting video job (this can take a minute)…");
@@ -410,7 +412,7 @@ async function cmdAudio(kind, prompt, flags) {
 const HELP = `OttoPort — one command for every model.
 
 Usage:
-  ottoport models [--modality chat|image|video|tts|music] [--json]
+  ottoport models [--modality chat|image|video|tts|stt|music|embedding] [--json]
   ottoport models <model-id> [--json]     what that one model accepts
   ottoport chat  "<prompt>" [--model claude-sonnet-5] [--system "..."] [--no-stream]
                             [--video <url|file>[,<url|file>…]]   ask about a video
@@ -423,6 +425,7 @@ 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>…]]
+                            [--ref-video <url>[,<url>…]] [--ref-audio <url>[,<url>…]]
                             [--webhook-url https://…] [--webhook-secret <s>]
                             [--no-wait] [--out clip.mp4]
   ottoport video --model video-depth-anything --video <url> [--out depth.mp4]

package/mcp/server.mjs

@@ -151,6 +151,34 @@ async function chat({ prompt, model, system, temperature, max_tokens }) {
   return json?.choices?.[0]?.message?.content ?? "";
 }
 
+/**
+ * Poll a job until it finishes, or until `timeoutMs` runs out.
+ *
+ * `statusPath` is the job's status route with `{id}` for the id — the same
+ * template the gateway's quote reports as `job_path` — and it is always read
+ * from BASE: every request this server makes goes to OTTOPORT_BASE_URL, which
+ * is what lets a reseller put its own gateway in front without a code change.
+ *
+ * Returns the finished job, or the last one seen with `timedOut` set so the
+ * caller can say where to pick it up. A failed job throws.
+ */
+async function waitForJob(statusPath, job, { timeoutMs, label }) {
+  const path = statusPath.replace("{id}", encodeURIComponent(job.id));
+  const deadline = Date.now() + timeoutMs;
+  while (job.status === "queued" || job.status === "processing") {
+    if (Date.now() >= deadline) return { job, timedOut: true, path };
+    await new Promise((resolve) => setTimeout(resolve, 3_000));
+    const status = await fetch(`${BASE}${path}`, { headers: headers(false) });
+    if (!status.ok) throw new Error(await gwError(status));
+    job = await status.json();
+  }
+  if (job.status === "failed") throw new Error(job.error || `${label} generation failed`);
+  return { job, timedOut: false, path };
+}
+
+const IMAGE_JOB_PATH = "/api/v1/images/generations/{id}";
+const VIDEO_JOB_PATH = "/api/v1/videos/generations/{id}";
+
 async function generateImage({ prompt, model, ...rest }) {
   // A layer-decomposition model splits `image_url` and takes the prompt as an
   // optional caption; every other image model needs the prompt. The gateway
@@ -165,10 +193,21 @@ async function generateImage({ prompt, model, ...rest }) {
     // live on the gateway and unreachable from any MCP client, silently. The
     // gateway validates against the model's capabilities and says what it
     // does not accept; this layer has no business having an opinion.
-    body: JSON.stringify({ model: model || "gpt-image-2", ...(prompt ? { prompt } : {}), ...rest }),
+    //
+    // Queued as a job and polled: a 4K or layered image can take longer than
+    // a proxy in front of the gateway holds a request open, and the hold is
+    // then settled on what actually came back.
+    body: JSON.stringify({ model: model || "gpt-image-2", ...(prompt ? { prompt } : {}), ...rest, async: true }),
   });
   if (!res.ok) throw new Error(await gwError(res));
-  const json = await res.json();
+  let json = await res.json();
+  // A 202 is a job. A 200 with `data` is the image itself — the dev key, or a
+  // gateway that predates image jobs — and is read exactly as before.
+  if (res.status === 202) {
+    const { job, timedOut, path } = await waitForJob(IMAGE_JOB_PATH, json, { timeoutMs: 5 * 60_000, label: "image" });
+    if (timedOut) return `Image job ${job.id} is still processing. Poll ${path} for its result.`;
+    json = job;
+  }
   // A layer stack prints one line per layer with what the model called it, so
   // the agent can pick "headline" out of eight URLs without opening them.
   const lines = (json.data ?? []).filter((d) => d.url).map((d) =>
@@ -179,7 +218,8 @@ async function generateImage({ prompt, model, ...rest }) {
 
 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");
+  // A draft completion takes everything from its draft, the prompt included.
+  if (!prompt && !rest.video_url && !rest.draft_id) 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;
@@ -191,30 +231,25 @@ async function generateVideo({ prompt, model, webhook_url, webhook_secret, ...re
     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");
+  const submitted = await res.json();
+  if (submitted.status === "failed") throw new Error(submitted.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.`;
+  if (webhook_url) return `Video job ${submitted.id} is ${submitted.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.
-  const deadline = Date.now() + 10 * 60_000;
-  while (job.status === "queued" || job.status === "processing") {
-    if (Date.now() >= deadline) return `Video job ${job.id} is still processing. Poll /api/v1/videos/generations/${job.id} for its result.`;
-    await new Promise((resolve) => setTimeout(resolve, 3_000));
-    const status = await fetch(`${BASE}/api/v1/videos/generations/${encodeURIComponent(job.id)}`, { headers: headers(false) });
-    if (!status.ok) throw new Error(await gwError(status));
-    job = await status.json();
-  }
-  if (job.status === "failed") throw new Error(job.error || "video generation failed");
+  const { job, timedOut, path } = await waitForJob(VIDEO_JOB_PATH, submitted, { timeoutMs: 10 * 60_000, label: "video" });
+  if (timedOut) return `Video job ${job.id} is still processing. Poll ${path} for its result.`;
   const url = job.data?.[0]?.url;
+  // The draft's job id is what completes it, so it is worth saying.
+  if (url && rest.draft) return `${url}\nDraft ${job.id} — complete it at 1080p with draft_id "${job.id}" within seven days.`;
   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 path = `${BASE}${VIDEO_JOB_PATH.replace("{id}", encodeURIComponent(job_id))}`;
   const res = action === "retry"
     ? await fetch(`${path}/webhook`, { method: "POST", headers: headers(false) })
     : await fetch(path, { headers: headers(false) });
@@ -252,7 +287,7 @@ const TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        modality: { type: "string", enum: ["chat", "image", "video", "tts", "music"], description: "Filter to one modality." },
+        modality: { type: "string", enum: ["chat", "image", "video", "tts", "stt", "music", "embedding"], description: "Filter to one modality." },
         model: { type: "string", description: "A model id, e.g. veo-3.1. Returns that one model's full parameter list instead of the catalog." },
       },
     },
@@ -305,7 +340,7 @@ const TOOLS = [
   },
   {
     name: "ottoport_generate_video",
-    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.",
+    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`, plus `reference_video_urls` / `reference_audio_urls` on models whose capabilities list `referenceMedia`), and on some models video edit/extend (`video_url`). Seedance 2.5 also drafts: `draft: true` renders a cheap 480p preview, and `draft_id` set to that job's id renders the same shot at 1080p. 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: {
@@ -320,9 +355,13 @@ 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." },
+        reference_video_urls: { type: "array", items: { type: "string" }, description: "Reference videos — motion, a performance, a scene — on models listing `referenceMedia` (Seedance 2.x, MiniMax H3, Wan 3.0). Billed per second of reference video where the upstream charges for it. To change one clip rather than draw on it, send it as `video_url` on a model listing video-edit." },
+        reference_audio_urls: { type: "array", items: { type: "string" }, description: "Reference audio — a voice, a beat — beside reference images or videos, on the same models. Not billed." },
         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." },
+        draft: { type: "boolean", description: "Seedance 2.5 only: render a 480p preview at about a quarter of the 1080p price, to check the shot before paying for it. Text, image and reference-image requests; no `resolution`." },
+        draft_id: { type: "string", description: "Seedance 2.5 only: the job id of a finished draft, to render that same shot at 1080p. Send `model` and this alone — prompt, inputs and duration come from the draft. Within seven days of the draft." },
         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." },
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ottoport",
-  "version": "1.8.0",
+  "version": "1.10.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,7 @@ 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`, `quality` (GPT Image only), `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`, `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_generate_video` | `prompt`, plus optional `model`, `duration`, `resolution`, `aspect_ratio`, `seed`, `image_url` (first frame), `last_frame_url`, `reference_image_urls`, `reference_video_urls` / `reference_audio_urls` (models listing `referenceMedia`), `video_url` (edit / extend), `draft` / `draft_id` (Seedance 2.5: a 480p preview, then the same shot at 1080p from the preview's job id), `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`. |
@@ -36,7 +36,7 @@ prints each one's menu beside its price:
 | text-to-video | `prompt` alone |
 | image-to-video | `image_url` — the first frame |
 | first-and-last-frame | `image_url` **and** `last_frame_url` |
-| reference-to-video | `reference_image_urls` — a character, a product, a style the shot carries through without either being a frame of it |
+| reference-to-video | `reference_image_urls` — a character, a product, a style the shot carries through without either being a frame of it; plus `reference_video_urls` and `reference_audio_urls` (motion, a performance, a voice) on models whose capabilities list `referenceMedia` — Seedance 2.x, MiniMax H3, Wan 3.0 |
 
 Images are the same idea with one axis: `image_url` for a single edit, or
 `reference_image_urls` for several at once, up to that model's limit.