ottoport 1.3.2 → 1.4.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.3.2",
+  "version": "1.4.0",
   "author": {
     "name": "LITBOX LLC",
     "email": "support@ottoport.ai"

package/README.md

@@ -19,10 +19,12 @@ ottoport models [--modality chat|image|video|tts|music] [--json]
 
 ottoport chat  "<prompt>" [--model claude-sonnet-5] [--system "..."] [--no-stream]
                           [--temperature 0.7] [--max-tokens 512]
-ottoport image "<prompt>" [--model gpt-image-2] [--size 1024x1024] [--n 1]
-                          [--image <url>] [--out file.png]
-ottoport video "<prompt>" [--model kling-3.0] [--duration 5]
-                          [--aspect-ratio 16:9] [--image <url>] [--out clip.mp4]
+ottoport image "<prompt>" [--model gpt-image-2] [--size 1024x1024 | --resolution 2k]
+                          [--aspect-ratio 16:9] [--n 1] [--seed 7]
+                          [--image <url>] [--ref <url>[,<url>…]] [--out file.png]
+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]
 ottoport speech "<text>"  [--model gpt-4o-mini-tts] [--voice alloy] [--out speech.mp3]
 ottoport music "<prompt>" [--model suno-v5] [--duration 15] [--out song.mp3]
 
@@ -76,6 +78,21 @@ forwarded from the environment rather than written into any config file.
 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.
 
+### Modes and resolution
+
+Video takes four modes — text-to-video, image-to-video (`image_url`),
+first-and-last-frame (`image_url` + `last_frame_url`), and reference-to-video
+(`reference_image_urls`). Images take one reference (`image_url`) or several
+(`reference_image_urls`). Both take a `resolution`: `480p`…`4k` for video,
+`1k`/`2k`/`4k` for images, and a tier above a model's base rate costs more.
+
+Which modes and tiers a model accepts differs per model, so
+`ottoport_list_models` — and `ottoport models` in the CLI — prints each one's
+menu beside its price. For one model in full, including every parameter it
+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.
+
 ## Configuration
 
 - `OTTOPORT_API_KEY` — your `op-…` key. Export it from your shell profile: the
@@ -90,6 +107,8 @@ it needs Node 20+ on the PATH of whatever starts that host.
   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.
+- `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.
 
 Docs: <https://ottoport.ai/docs> · Support: support@ottoport.ai

package/cli/ottoport.mjs

@@ -5,7 +5,7 @@
 //
 //   ottoport models [--modality chat|image|video]
 //   ottoport chat   "prompt" [--model claude-sonnet-5] [--system "..."] [--no-stream]
-//   ottoport image  "prompt" [--model gpt-image-2] [--size 1024x1024] [--out img.png]
+//   ottoport image  "prompt" [--model gpt-image-2] [--resolution 2k] [--ref a.png,b.png] [--out img.png]
 //   ottoport video  "prompt" [--model kling-3.0] [--duration 5] [--out clip.mp4]
 //   ottoport speech "text" [--model gpt-4o-mini-tts] [--voice alloy] [--out speech.mp3]
 //   ottoport music  "prompt" [--model suno-v5] [--duration 15] [--out song.mp3]
@@ -31,7 +31,11 @@ function parseArgs(argv) {
       if (key.startsWith("no-")) {
         flags[key.slice(3)] = false;
       } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
-        flags[key] = argv[++i];
+        const value = argv[++i];
+        // Repeats accumulate rather than overwrite, so `--ref a --ref b` keeps
+        // both. Everything downstream reads the last value of a scalar flag,
+        // which an array's last element still is.
+        flags[key] = key in flags ? [].concat(flags[key], value) : value;
       } else {
         flags[key] = true;
       }
@@ -42,9 +46,14 @@ function parseArgs(argv) {
   return { positional, flags };
 }
 
+/** The effective value of a flag that may have been repeated. */
+function last(value) {
+  return Array.isArray(value) ? value[value.length - 1] : value;
+}
+
 function config(flags) {
-  const baseUrl = (flags.url || process.env.OTTOPORT_BASE_URL || process.env.NEXT_PUBLIC_APP_URL || BASE).replace(/\/+$/, "");
-  const apiKey = flags.key || process.env.OTTOPORT_API_KEY || process.env.OTTOPORT_KEY_SECRET;
+  const baseUrl = (last(flags.url) || process.env.OTTOPORT_BASE_URL || process.env.NEXT_PUBLIC_APP_URL || BASE).replace(/\/+$/, "");
+  const apiKey = last(flags.key) || process.env.OTTOPORT_API_KEY || process.env.OTTOPORT_KEY_SECRET;
   return { baseUrl, apiKey };
 }
 
@@ -69,21 +78,73 @@ async function readError(res) {
 }
 
 // ── commands ─────────────────────────────────────────────────────────
+/**
+ * One model in full — every parameter it reads, with its own limits filled
+ * in. `ottoport models` answers "which model"; this answers "and what may I
+ * send it", which the catalog view can only hint at.
+ */
+async function cmdModel(id, flags) {
+  const { baseUrl, apiKey } = config(flags);
+  const res = await fetch(`${baseUrl}/api/v1/models/${encodeURIComponent(id)}`, { headers: headers(apiKey, false) });
+  if (!res.ok) die(await readError(res));
+  const m = await res.json();
+  if (flags.json) return console.log(JSON.stringify(m, null, 2));
+  console.log(`${m.id} — ${m.display_name} [${m.modality}, ${m.owned_by}]`);
+  if (m.description) console.log(m.description);
+  if (m.credits_display) console.log(`rate:       ${m.credits_display}`);
+  console.log(`endpoint:   ${m.endpoint}`);
+  const caps = m.capabilities;
+  if (caps?.modes) {
+    const refs = caps.maxReferenceImages ? ` (up to ${caps.maxReferenceImages} reference images)` : "";
+    console.log(`modes:      ${caps.modes.join(", ")}${refs}`);
+  }
+  if (typeof caps?.maxInputImages === "number") {
+    console.log(`inputs:     ${caps.maxInputImages > 0 ? `up to ${caps.maxInputImages} reference images` : "text only"}`);
+  }
+  if (caps?.resolutions?.length) {
+    // The multiplier rides beside the tier: on video it is what it costs.
+    const tiers = caps.resolution_multipliers
+      ? caps.resolutions.map((r) => (caps.resolution_multipliers[r] > 1 ? `${r} ×${caps.resolution_multipliers[r]}` : r))
+      : caps.resolutions;
+    console.log(`resolution: ${tiers.join(", ")}${caps.base_resolution ? ` (base ${caps.base_resolution})` : ""}`);
+  }
+  console.log("parameters:");
+  for (const p of m.parameters ?? []) {
+    console.log(`  ${String(p.name).padEnd(21)}${p.type}${p.required ? ", required" : ""} — ${p.note}`);
+  }
+}
+
 async function cmdModels(flags) {
   const { baseUrl, apiKey } = config(flags);
-  const qs = flags.modality ? `?modality=${encodeURIComponent(flags.modality)}` : "";
+  const qs = last(flags.modality) ? `?modality=${encodeURIComponent(last(flags.modality))}` : "";
   const res = await fetch(`${baseUrl}/api/v1/models${qs}`, { headers: headers(apiKey, false) });
   if (!res.ok) die(await readError(res));
   const { data } = await res.json();
   if (flags.json) return console.log(JSON.stringify(data, null, 2));
   const pad = (s, n) => String(s).padEnd(n);
-  console.log(pad("ID", 20) + pad("MODALITY", 10) + pad("PROVIDER", 12) + "PRICING");
+  console.log(pad("ID", 20) + pad("MODALITY", 10) + pad("PROVIDER", 12) + "RATE");
   for (const m of data) {
-    const price = Object.entries(m.pricing ?? {}).map(([k, v]) => `${k}=$${v}`).join(" ");
-    console.log(pad(m.id, 20) + pad(m.modality, 10) + pad(m.owned_by, 12) + price);
+    // The gateway formats the rate; this prints it. Anything else puts a unit
+    // in the client, where changing it means everyone reinstalling.
+    console.log(pad(m.id, 20) + pad(m.modality, 10) + pad(m.owned_by, 12) + (m.credits_display ?? ""));
+    // What the model accepts, on its own line: which modes, how many
+    // reference images, which resolutions. Picking a model for a
+    // first-and-last-frame shot is otherwise trial and error.
+    const accepts = capabilityLine(m.capabilities);
+    if (accepts) console.log(pad("", 42) + accepts);
   }
 }
 
+function capabilityLine(caps) {
+  if (!caps) return "";
+  if (caps.modality === "video") {
+    const refs = caps.maxReferenceImages ? `, up to ${caps.maxReferenceImages} refs` : "";
+    return `accepts: ${caps.modes.join(", ")}${refs} · ${caps.resolutions.join("/")}`;
+  }
+  const inputs = caps.maxInputImages ? `up to ${caps.maxInputImages} input images` : "text only";
+  return `accepts: ${inputs} · ${caps.resolutions.join("/")}`;
+}
+
 async function cmdChat(prompt, flags) {
   if (!prompt) die("chat requires a prompt: ottoport chat \"hello\"");
   const { baseUrl, apiKey } = config(flags);
@@ -93,11 +154,11 @@ async function cmdChat(prompt, flags) {
 
   const stream = flags.stream !== false;
   const body = {
-    model: flags.model || "claude-sonnet-5",
+    model: last(flags.model) || "claude-sonnet-5",
     messages,
     stream,
-    ...(flags.temperature ? { temperature: Number(flags.temperature) } : {}),
-    ...(flags["max-tokens"] ? { max_tokens: Number(flags["max-tokens"]) } : {}),
+    ...(flags.temperature ? { temperature: Number(last(flags.temperature)) } : {}),
+    ...(last(flags["max-tokens"]) ? { max_tokens: Number(last(flags["max-tokens"])) } : {}),
   };
 
   const res = await fetch(`${baseUrl}/api/v1/chat/completions`, {
@@ -147,15 +208,35 @@ async function download(url, out) {
   console.error(`saved → ${out} (${buf.length} bytes)`);
 }
 
+/**
+ * `--ref` given once or several times.
+ *
+ * The flag parser keeps the last value for a repeated flag and a comma list is
+ * 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;
+  const list = (Array.isArray(raw) ? raw : [raw])
+    .filter(Boolean)
+    .flatMap((value) => String(value).split(",").map((one) => one.trim()))
+    .filter(Boolean);
+  return list.length ? list : undefined;
+}
+
 async function cmdImage(prompt, flags) {
   if (!prompt) die("image requires a prompt: ottoport image \"a red fox\"");
   const { baseUrl, apiKey } = config(flags);
   const body = {
-    model: flags.model || "gpt-image-2",
+    model: last(flags.model) || "gpt-image-2",
     prompt,
-    ...(flags.size ? { size: flags.size } : {}),
-    ...(flags.n ? { n: Number(flags.n) } : {}),
-    ...(flags.image ? { image_url: flags.image } : {}),
+    ...(last(flags.size) ? { size: last(flags.size) } : {}),
+    ...(last(flags.resolution) ? { resolution: last(flags.resolution) } : {}),
+    ...(last(flags["aspect-ratio"]) ? { aspect_ratio: flags["aspect-ratio"] } : {}),
+    ...(last(flags.n) ? { n: Number(last(flags.n)) } : {}),
+    ...(last(flags.seed) ? { seed: Number(last(flags.seed)) } : {}),
+    ...(last(flags.image) ? { image_url: flags.image } : {}),
+    ...(references(flags) ? { reference_image_urls: references(flags) } : {}),
   };
   const res = await fetch(`${baseUrl}/api/v1/images/generations`, {
     method: "POST",
@@ -166,18 +247,22 @@ async function cmdImage(prompt, flags) {
   const json = await res.json();
   const urls = (json.data ?? []).map((d) => d.url).filter(Boolean);
   urls.forEach((u) => console.log(u));
-  if (flags.out && urls[0]) await download(urls[0], flags.out);
+  if (last(flags.out) && urls[0]) await download(urls[0], last(flags.out));
 }
 
 async function cmdVideo(prompt, flags) {
   if (!prompt) die("video requires a prompt: ottoport video \"a drone shot\"");
   const { baseUrl, apiKey } = config(flags);
   const body = {
-    model: flags.model || "kling-3.0",
+    model: last(flags.model) || "kling-3.0",
     prompt,
-    ...(flags.duration ? { duration: Number(flags.duration) } : {}),
-    ...(flags["aspect-ratio"] ? { aspect_ratio: flags["aspect-ratio"] } : {}),
-    ...(flags.image ? { image_url: flags.image } : {}),
+    ...(last(flags.duration) ? { duration: Number(last(flags.duration)) } : {}),
+    ...(last(flags.resolution) ? { resolution: last(flags.resolution) } : {}),
+    ...(last(flags["aspect-ratio"]) ? { aspect_ratio: flags["aspect-ratio"] } : {}),
+    ...(last(flags.seed) ? { seed: Number(last(flags.seed)) } : {}),
+    ...(last(flags.image) ? { image_url: flags.image } : {}),
+    ...(last(flags["last-frame"]) ? { last_frame_url: flags["last-frame"] } : {}),
+    ...(references(flags) ? { reference_image_urls: references(flags) } : {}),
   };
   console.error("submitting video job (this can take a minute)…");
   const res = await fetch(`${baseUrl}/api/v1/videos/generations`, {
@@ -201,7 +286,7 @@ async function cmdVideo(prompt, flags) {
   const url = job.data?.[0]?.url;
   if (url) {
     console.log(url);
-    if (flags.out) await download(url, flags.out);
+    if (flags.out) await download(url, last(flags.out));
   } else {
     console.log(JSON.stringify(job, null, 2));
   }
@@ -211,11 +296,11 @@ async function cmdAudio(kind, prompt, flags) {
   if (!prompt) die(`${kind} requires a prompt: ottoport ${kind} "hello"`);
   const { baseUrl, apiKey } = config(flags);
   const body = {
-    model: flags.model || (kind === "speech" ? "gpt-4o-mini-tts" : "suno-v5"),
+    model: last(flags.model) || (kind === "speech" ? "gpt-4o-mini-tts" : "suno-v5"),
     prompt,
-    ...(flags.voice ? { voice: flags.voice } : {}),
-    ...(flags.duration ? { duration: Number(flags.duration) } : {}),
-    ...(flags.format ? { format: flags.format } : {}),
+    ...(last(flags.voice) ? { voice: last(flags.voice) } : {}),
+    ...(last(flags.duration) ? { duration: Number(last(flags.duration)) } : {}),
+    ...(last(flags.format) ? { format: last(flags.format) } : {}),
   };
   const path = kind === "speech" ? "audio/speech" : "audio/music";
   const res = await fetch(`${baseUrl}/api/v1/${path}`, {
@@ -231,10 +316,10 @@ async function cmdAudio(kind, prompt, flags) {
   if (flags.out) {
     if (item.b64_json) {
       const bytes = Buffer.from(item.b64_json, "base64");
-      await writeFile(flags.out, bytes);
-      console.error(`saved → ${flags.out} (${bytes.length} bytes)`);
+      await writeFile(last(flags.out), bytes);
+      console.error(`saved → ${last(flags.out)} (${bytes.length} bytes)`);
     } else if (item.url) {
-      await download(item.url, flags.out);
+      await download(item.url, last(flags.out));
     }
   }
 }
@@ -243,12 +328,16 @@ const HELP = `OttoPort — one command for every model.
 
 Usage:
   ottoport models [--modality chat|image|video|tts|music] [--json]
+  ottoport models <model-id> [--json]     what that one model accepts
   ottoport chat  "<prompt>" [--model claude-sonnet-5] [--system "..."] [--no-stream]
                             [--temperature 0.7] [--max-tokens 512]
-  ottoport image "<prompt>" [--model gpt-image-2] [--size 1024x1024] [--n 1]
-                            [--image <url>] [--out file.png]
-  ottoport video "<prompt>" [--model kling-3.0] [--duration 5]
-                            [--aspect-ratio 16:9] [--image <url>] [--out clip.mp4]
+  ottoport image "<prompt>" [--model gpt-image-2] [--size 1024x1024 | --resolution 2k]
+                            [--aspect-ratio 16:9] [--n 1] [--seed 7]
+                            [--image <url>] [--ref <url>[,<url>…]] [--out file.png]
+  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>…]]
+                            [--no-wait] [--out clip.mp4]
   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
@@ -262,10 +351,13 @@ Global flags:
 
 Examples:
   export OTTOPORT_API_KEY=op-... OTTOPORT_BASE_URL=https://ottoport.dev
-  ottoport models --modality image
+  ottoport models --modality image      # prints what each one accepts
+  ottoport models veo-3.1               # its modes, tiers, and every parameter
   ottoport chat "explain MCP in one line" --model claude-haiku-4.5
   ottoport image "isometric city at dusk" --model gpt-image-2 --out city.png
-  ottoport video "cinematic product reveal" --model seedance-2.0-fast
+  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 image "her, on a beach" --ref face.png,style.png
   ottoport speech "Welcome to OttoPort" --voice alloy --out welcome.mp3
   ottoport music "lo-fi focus beat" --duration 20 --out focus.mp3
   ottoport mcp
@@ -278,7 +370,8 @@ async function main() {
   const prompt = rest.join(" ");
   try {
     switch (command) {
-      case "models": return await cmdModels(flags);
+      // `models <id>` is the detail view; bare `models` is the catalog.
+      case "models": return rest[0] ? await cmdModel(rest[0], flags) : await cmdModels(flags);
       case "chat": return await cmdChat(prompt, flags);
       case "image": return await cmdImage(prompt, flags);
       case "video": return await cmdVideo(prompt, flags);

package/commands/image.md

@@ -1,6 +1,6 @@
 ---
 description: Generate an image through the OttoPort gateway
-argument-hint: "<prompt> [--model <id>] [--size 1024x1024]"
+argument-hint: "<prompt> [--model <id>] [--resolution 2k] [--ref <url>…]"
 allowed-tools: mcp__ottoport__ottoport_generate_image, mcp__ottoport__ottoport_list_models, Bash(curl:*)
 ---
 
@@ -9,6 +9,14 @@ Generate an image with the `ottoport_generate_image` MCP tool.
 Request: $ARGUMENTS
 
 - Pass `model` only if the user named one; the tool defaults to `gpt-image-2`.
-- An edit of an existing image goes through `image_url`, not the prompt.
+- An edit of an existing image goes through `image_url`, not the prompt. Several
+  references at once — a character plus the scene, a product plus a style — go
+  through `reference_image_urls`.
+- Detail is `resolution` (`1k`/`2k`/`4k`), optionally with `aspect_ratio`; pass
+  `size` instead when the user named exact pixels. A higher tier costs more, so
+  send one only when the request asks for it.
+- Models differ in how many references and which resolutions they take. If a
+  request needs more than one reference, or 4k, check `ottoport_list_models`
+  first — it prints each model's menu — rather than spending a failed call.
 - The tool returns URLs, and provider URLs expire. Print the URL, and if the
   user asked for a file, download it to the path they named with `curl -sSL`.

package/commands/models.md

@@ -1,14 +1,22 @@
 ---
-description: List the OttoPort model catalog with live pricing, optionally filtered by modality
-argument-hint: "[chat|image|video|tts|music]"
+description: The OttoPort model catalog — what each model is for, its rate, and what one model accepts
+argument-hint: "[chat|image|video|tts|music | <model-id>]"
 allowed-tools: mcp__ottoport__ottoport_list_models
 ---
 
-List the OttoPort catalog using the `ottoport_list_models` MCP tool.
+Answer with the `ottoport_list_models` MCP tool.
 
-Modality filter (may be empty — then list everything): `$1`
+Argument (may be empty — then list everything): `$1`
 
-Present the result as a table: model id, what it is good at, and price. Group by
-modality when no filter was given, and keep it to the models worth choosing
-between rather than every row. Never invent a model id that the tool did not
-return.
+- A modality (`chat`, `image`, `video`, `tts`, `music`) → pass it as `modality`
+  and present a table: model id, what it is good at, and its rate.
+- A model id (`veo-3.1`, `nano-banana-pro`, …) → pass it as `model`. The tool
+  then returns that one model in full: its input modes, the resolutions it
+  offers with their price multipliers, and every request parameter it reads.
+  Present it as-is — the parameter list is the answer to "what can I send it".
+- Nothing → list everything, grouped by modality, and keep it to the models
+  worth choosing between rather than every row.
+
+Rates are in credits — the unit the account's balance is kept in — so quote
+them as the tool returns them and never convert to a currency. Never invent a
+model id, a mode, or a resolution the tool did not return.

package/commands/video.md

@@ -1,6 +1,6 @@
 ---
 description: Generate a video through the OttoPort gateway
-argument-hint: "<prompt> [--model <id>] [--duration 5]"
+argument-hint: "<prompt> [--model <id>] [--duration 5] [--resolution 1080p]"
 allowed-tools: mcp__ottoport__ottoport_generate_video, mcp__ottoport__ottoport_list_models, Bash(curl:*)
 ---
 
@@ -8,8 +8,20 @@ Generate a video with the `ottoport_generate_video` MCP tool.
 
 Request: $ARGUMENTS
 
-- Pass `model`, `duration`, `aspect_ratio` and `image_url` only when the request
+- Pass `model`, `duration`, `resolution` and `aspect_ratio` only when the request
   supplies them; the tool defaults to `kling-3.0`.
+- Pick the mode from what the user gave you:
+  - nothing but a prompt → text-to-video;
+  - one still → `image_url`, the first frame;
+  - a start and an end → `image_url` **and** `last_frame_url`;
+  - a character, product or style to carry through the shot →
+    `reference_image_urls`.
+- Not every model takes every mode or every resolution. When the request needs
+  a closing frame, references, or a tier above 1080p, read
+  `ottoport_list_models` first — each model prints its own menu — instead of
+  discovering it from a failed call.
+- `resolution` is billed: a 1080p or 4k clip costs more per second than the
+  model's base tier. Send one only when the request asks for it.
 - Video generation takes a minute or more and the call blocks until the job is
   terminal. Say so before you start, and do not retry a call that is merely slow
   — a retry is a second billable generation.

package/mcp/server.mjs

@@ -13,8 +13,18 @@
 //   claude mcp add ottoport -- node /abs/path/to/mcp/server.mjs
 
 import { createInterface } from "node:readline";
+import { readFileSync } from "node:fs";
 
 const PROTOCOL_VERSION = "2024-11-05";
+// Read from the package rather than repeated here: a version that says 0.1.0
+// while the package ships 1.3.x sends whoever is debugging to the wrong code.
+const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+})();
 const BASE = (process.env.OTTOPORT_BASE_URL || process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3014").replace(/\/+$/, "");
 const KEY = process.env.OTTOPORT_API_KEY || process.env.OTTOPORT_KEY_SECRET;
 
@@ -34,15 +44,82 @@ async function gwError(res) {
 }
 
 // ── tool implementations ─────────────────────────────────────────────
-async function listModels({ modality } = {}) {
+/**
+ * What a model takes, in one clause.
+ *
+ * Without this the catalog answers "which model" and leaves "and what may I
+ * send it" to trial and error — which on a paid endpoint is a failed billable
+ * call, or worse, a field the provider silently ignores while charging in
+ * full. Rendered only when the gateway published it; an older deployment
+ * reads exactly as it did before.
+ */
+function accepts(capabilities) {
+  if (!capabilities) return "";
+  const parts = [];
+  if (Array.isArray(capabilities.modes) && capabilities.modes.length) {
+    parts.push(capabilities.modes.join("/"));
+  }
+  if (typeof capabilities.maxInputImages === "number") {
+    parts.push(capabilities.maxInputImages > 0 ? `up to ${capabilities.maxInputImages} reference images` : "text only");
+  }
+  if (typeof capabilities.maxReferenceImages === "number") {
+    parts.push(`up to ${capabilities.maxReferenceImages} references`);
+  }
+  if (Array.isArray(capabilities.resolutions) && capabilities.resolutions.length) {
+    parts.push(capabilities.resolutions.join("/"));
+  }
+  return parts.length ? ` · accepts ${parts.join(", ")}` : "";
+}
+
+/** One model in full: what it accepts, what it costs, and its request body. */
+async function describeModel(id) {
+  const res = await fetch(`${BASE}/api/v1/models/${encodeURIComponent(id)}`, { headers: headers(false) });
+  if (!res.ok) throw new Error(await gwError(res));
+  const m = await res.json();
+  const caps = m.capabilities;
+  const lines = [
+    `${m.id} — ${m.display_name} [${m.modality}, ${m.owned_by}]`,
+    ...(m.description ? [m.description] : []),
+    ...(m.credits_display ? [`Rate: ${m.credits_display}`] : []),
+    `Endpoint: ${m.endpoint}`,
+  ];
+  if (caps?.modes) {
+    const refs = caps.maxReferenceImages ? ` (up to ${caps.maxReferenceImages} reference images)` : "";
+    lines.push(`Modes: ${caps.modes.join(", ")}${refs}`);
+  }
+  if (typeof caps?.maxInputImages === "number") {
+    lines.push(`Input images: ${caps.maxInputImages > 0 ? `up to ${caps.maxInputImages}` : "none — text-to-image only"}`);
+  }
+  if (caps?.resolutions?.length) {
+    // A tier's multiplier prints beside it: on video, a resolution is a price.
+    const tiers = caps.resolution_multipliers
+      ? caps.resolutions.map((r) => (caps.resolution_multipliers[r] > 1 ? `${r} ×${caps.resolution_multipliers[r]}` : r))
+      : caps.resolutions;
+    lines.push(`Resolutions: ${tiers.join(", ")}${caps.base_resolution ? ` (base ${caps.base_resolution})` : ""}`);
+  }
+  lines.push("Parameters:");
+  for (const p of m.parameters ?? []) {
+    lines.push(`  ${p.name} (${p.type}${p.required ? ", required" : ""}) — ${p.note}`);
+  }
+  return lines.join("\n");
+}
+
+async function listModels({ modality, model } = {}) {
+  // A named model is answered in full — its modes, its resolutions, and the
+  // exact body it takes — rather than as one line in a catalog of sixty.
+  if (model) return describeModel(model);
   const qs = modality ? `?modality=${encodeURIComponent(modality)}` : "";
   const res = await fetch(`${BASE}/api/v1/models${qs}`, { headers: headers(false) });
   if (!res.ok) throw new Error(await gwError(res));
   const { data } = await res.json();
+  // Lead with what the model is for: an agent picking one needs the capability,
+  // and the rate is the tiebreaker. The gateway formats the rate itself, so no
+  // unit is spelled out here.
   return data
     .map((m) => {
-      const price = Object.entries(m.pricing ?? {}).map(([k, v]) => `${k}=$${v}`).join(" ");
-      return `${m.id} — ${m.display_name} [${m.modality}, ${m.owned_by}]${price ? " · " + price : ""}`;
+      const rate = m.credits_display ? ` · ${m.credits_display}` : "";
+      const what = m.description ? ` — ${m.description}` : "";
+      return `${m.id} [${m.modality}, ${m.owned_by}]${what}${rate}${accepts(m.capabilities)}`;
     })
     .join("\n");
 }
@@ -68,18 +145,18 @@ async function chat({ prompt, model, system, temperature, max_tokens }) {
   return json?.choices?.[0]?.message?.content ?? "";
 }
 
-async function generateImage({ prompt, model, size, n, image_url }) {
+async function generateImage({ prompt, model, ...rest }) {
   if (!prompt) throw new Error("`prompt` is required");
   const res = await fetch(`${BASE}/api/v1/images/generations`, {
     method: "POST",
     headers: { ...headers(), "idempotency-key": crypto.randomUUID() },
-    body: JSON.stringify({
-      model: model || "gpt-image-2",
-      prompt,
-      ...(size ? { size } : {}),
-      ...(n ? { n } : {}),
-      ...(image_url ? { image_url } : {}),
-    }),
+    // Everything else goes through untouched. Naming the fields here made this
+    // file a second copy of the gateway's request shape, and a copy that drops
+    // what it has not heard of: `reference_image_urls` and `resolution` were
+    // 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, ...rest }),
   });
   if (!res.ok) throw new Error(await gwError(res));
   const json = await res.json();
@@ -87,18 +164,13 @@ async function generateImage({ prompt, model, size, n, image_url }) {
   return urls.length ? urls.join("\n") : "(no image returned)";
 }
 
-async function generateVideo({ prompt, model, duration, aspect_ratio, image_url }) {
+async function generateVideo({ prompt, model, ...rest }) {
   if (!prompt) throw new Error("`prompt` is required");
   const res = await fetch(`${BASE}/api/v1/videos/generations`, {
     method: "POST",
     headers: { ...headers(), "idempotency-key": crypto.randomUUID() },
-    body: JSON.stringify({
-      model: model || "kling-3.0",
-      prompt,
-      ...(duration ? { duration } : {}),
-      ...(aspect_ratio ? { aspect_ratio } : {}),
-      ...(image_url ? { image_url } : {}),
-    }),
+    // Passed through; see `generateImage` for why this layer names nothing.
+    body: JSON.stringify({ model: model || "kling-3.0", prompt, ...rest }),
   });
   if (!res.ok) throw new Error(await gwError(res));
   let job = await res.json();
@@ -143,11 +215,12 @@ async function generateAudio(kind, { prompt, model, voice, duration, format }) {
 const TOOLS = [
   {
     name: "ottoport_list_models",
-    description: "List the models OttoPort exposes, with modality, provider, and pricing. Optionally filter by modality.",
+    description: "The OttoPort catalog: modality, provider, price, and what each model accepts — input modes, reference-image count, resolutions. Read it before naming a model or a mode. Filter with `modality`, or pass `model` for ONE model in full: its resolutions with their price multipliers and every request parameter it reads.",
     inputSchema: {
       type: "object",
       properties: {
         modality: { type: "string", enum: ["chat", "image", "video", "tts", "music"], 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." },
       },
     },
     handler: listModels,
@@ -170,15 +243,24 @@ const TOOLS = [
   },
   {
     name: "ottoport_generate_image",
-    description: "Generate an image from a text prompt through an OttoPort image model (GPT Image, Nano Banana, …). Returns image URL(s).",
+    description: "Generate an image through an OttoPort image model (GPT Image, Nano Banana, …). Text-to-image, editing from one reference, or several references at once. Which a model accepts is in its capabilities — call ottoport_list_models. Returns image URL(s).",
     inputSchema: {
       type: "object",
       properties: {
         prompt: { type: "string" },
         model: { type: "string", description: "Model id, e.g. gpt-image-2, nano-banana-2, nano-banana-pro. Default gpt-image-2." },
-        size: { type: "string", description: 'e.g. "1024x1024" or "16:9".' },
+        size: { type: "string", description: 'Exact pixels, e.g. "1024x1024". Wins over `resolution`.' },
+        // No `enum`: the vocabulary is "1k"/"2k"/"4k", but which of them a given
+        // model actually offers differs per model, and an enum here reads as a
+        // promise that every value works everywhere. It does not — and since
+        // resolution is a price multiplier, the wrong guess is a refused call
+        // at best. The model's own menu is in `ottoport_list_models`.
+        resolution: { type: "string", description: 'Output detail — "1k", "2k" or "4k", but only the tiers this model lists in ottoport_list_models. Priced accordingly. Pair with `aspect_ratio` when you know the shape but not the pixel vocabulary; an explicit `size` wins.' },
+        aspect_ratio: { type: "string", description: 'e.g. "16:9". Read only when `size` is absent.' },
         n: { type: "number" },
-        image_url: { type: "string", description: "Source image URL for image-to-image / edits." },
+        seed: { type: "number" },
+        image_url: { type: "string", description: "One reference image, for editing and image-to-image." },
+        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." },
       },
       required: ["prompt"],
     },
@@ -186,15 +268,21 @@ const TOOLS = [
   },
   {
     name: "ottoport_generate_video",
-    description: "Generate a video from a text prompt (or an image) through an OttoPort video model (Veo, Kling, Seedance, …). Blocks on the queue and returns a video URL.",
+    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.",
     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." },
-        duration: { type: "number", description: "Seconds." },
+        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.
+        resolution: { type: "string", description: 'Output detail — "480p", "720p", "1080p", "2k" or "4k", but only the tiers this model lists in ottoport_list_models. Priced accordingly, so it is worth reading before spending.' },
         aspect_ratio: { type: "string", description: 'e.g. "16:9".' },
-        image_url: { type: "string", description: "Source image URL for image-to-video." },
+        seed: { type: "number" },
+        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." },
       },
       required: ["prompt"],
     },
@@ -255,7 +343,7 @@ async function handle(msg) {
       return reply(id, {
         protocolVersion: PROTOCOL_VERSION,
         capabilities: { tools: {} },
-        serverInfo: { name: "ottoport", version: "0.1.0" },
+        serverInfo: { name: "ottoport", version: VERSION },
       });
 
     case "notifications/initialized":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ottoport",
-  "version": "1.3.2",
+  "version": "1.4.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",
   "license": "MIT",

package/skills/ottoport/SKILL.md

@@ -14,10 +14,10 @@ and do not call the HTTP API, when a tool covers the job:
 
 | Tool | For |
 | --- | --- |
-| `ottoport_list_models` | The catalog, with modality, provider, and price. Filter with `modality`. |
+| `ottoport_list_models` | The catalog: what each model is for, and its rate in credits. 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`, `n`, `image_url` (edits / image-to-image). |
-| `ottoport_generate_video` | `prompt`, plus optional `model`, `duration`, `aspect_ratio`, `image_url`. |
+| `ottoport_generate_image` | `prompt`, plus optional `model`, `size` or `resolution`, `aspect_ratio`, `n`, `seed`, `image_url` (one reference), `reference_image_urls` (several). |
+| `ottoport_generate_video` | `prompt`, plus optional `model`, `duration`, `resolution`, `aspect_ratio`, `seed`, `image_url` (first frame), `last_frame_url`, `reference_image_urls`. |
 | `ottoport_generate_speech` | `prompt` (the text), plus optional `model`, `voice`, `format`. |
 | `ottoport_generate_music` | `prompt`, plus optional `model`, `duration`, `format`. |
 
@@ -25,6 +25,36 @@ If those tools are not present, the server is not registered in this client —
 say so rather than reaching for a shell. `ottoport install <host>` registers it
 (codex, claude, hermes, cursor, windsurf, claude-desktop).
 
+## Modes
+
+Video takes four, and which ones a model accepts is per-model — `ottoport_list_models`
+prints each one's menu beside its price:
+
+| Mode | Send |
+| --- | --- |
+| 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 |
+
+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.
+
+`resolution` is separate from all of it, and **it is priced** — a higher tier
+costs more. The vocabulary is `"480p"`/`"720p"`/`"1080p"`/`"2k"`/`"4k"` for
+video and `"1k"`/`"2k"`/`"4k"` for images, but **no model offers all of it**:
+`kling-3.0` has no 480p and no 4k, `gemini-omni-flash` has only 720p,
+`gpt-image-1.5` only 1k. Same for how many references a model takes —
+`nano-banana-lite` accepts 3, `gpt-image-2` accepts 16.
+
+So read the model's own menu before naming a mode, a resolution or a second
+reference image: `ottoport_list_models` with `model` set to the one you are
+about to call answers with exactly that — its modes, what each resolution tier
+costs, and the parameter list, for that model alone. A value the model does not
+list is refused with its actual menu in the message, which costs a round trip
+rather than a generation — but the round trip is avoidable and the lookup is
+one call. Give `size` instead when you know the exact pixels; it wins.
+
 ## Choosing a model
 
 Pass `model` only when the request calls for a specific one; every tool has a
@@ -39,7 +69,9 @@ sensible default.
 | music | `suno-v5` | `lyria-2` |
 
 Never invent a model id. Call `ottoport_list_models` when unsure — the catalog
-changes, and a wrong id is a failed billable call.
+changes, and a wrong id is a failed billable call. Rates come back in credits,
+the unit the account balance is kept in; quote them as given rather than
+converting to a currency.
 
 ## What comes back