ottoport 1.11.0 → 1.12.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.11.0",
+  "version": "1.12.0",
   "author": {
     "name": "LITBOX LLC",
     "email": "support@ottoport.ai"

package/README.md

@@ -78,7 +78,10 @@ forwarded from the environment rather than written into any config file.
 
 `ottoport_list_models`, `ottoport_chat`, `ottoport_generate_image`,
 `ottoport_generate_video`, `ottoport_video_webhook`, `ottoport_generate_speech`,
-`ottoport_generate_music`.
+`ottoport_generate_music`, and for keeping results, `ottoport_list_collections`,
+`ottoport_create_collection`, `ottoport_list_assets`, `ottoport_save_asset`,
+`ottoport_upload_file` and `ottoport_delete_asset`. Every generate tool takes
+`collection` (an id or name) to save what it makes; `OTTOPORT_COLLECTION` sets a default.
 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.
 

package/cli/ottoport.mjs

@@ -10,6 +10,7 @@
 //   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]
+//   ottoport collections [list | create "name"]
 //   ottoport mcp
 //   ottoport install <codex|claude|hermes|cursor|windsurf|claude-desktop>
 //
@@ -278,6 +279,7 @@ async function cmdImage(prompt, flags) {
     ...(last(flags.seed) ? { seed: Number(last(flags.seed)) } : {}),
     ...(last(flags.image) ? { image_url: flags.image } : {}),
     ...(references(flags) ? { reference_image_urls: references(flags) } : {}),
+    ...collection(flags),
   };
   const res = await fetch(`${baseUrl}/api/v1/images/generations`, {
     method: "POST",
@@ -289,7 +291,7 @@ async function cmdImage(prompt, flags) {
   const urls = (json.data ?? []).map((d) => d.url).filter(Boolean);
   // A layer stack names each line, so `headline` can be found among eight URLs.
   (json.data ?? []).filter((d) => d.url).forEach((d) =>
-    console.log(d.layer ? `layer ${d.layer.index}${d.layer.name ? ` (${d.layer.name})` : ""}: ${d.url}` : d.url));
+    console.log(outputLine(d, d.layer ? `layer ${d.layer.index}${d.layer.name ? ` (${d.layer.name})` : ""}: ` : "")));
   if (last(flags.out) && urls[0]) await download(urls[0], last(flags.out));
 }
 
@@ -311,6 +313,7 @@ async function cmdVideo(prompt, 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),
+    ...collection(flags),
   };
   console.error("submitting video job (this can take a minute)…");
   const res = await fetch(`${baseUrl}/api/v1/videos/generations`, {
@@ -334,7 +337,7 @@ async function cmdVideo(prompt, flags) {
   if (job.status === "failed") die(job.error || "video generation failed", 2);
   const url = job.data?.[0]?.url;
   if (url) {
-    console.log(url);
+    console.log(outputLine(job.data[0]));
     if (flags.out) await download(url, last(flags.out));
   } else {
     console.log(JSON.stringify(job, null, 2));
@@ -386,6 +389,7 @@ async function cmdAudio(kind, prompt, flags) {
     ...(last(flags.voice) ? { voice: last(flags.voice) } : {}),
     ...(last(flags.duration) ? { duration: Number(last(flags.duration)) } : {}),
     ...(last(flags.format) ? { format: last(flags.format) } : {}),
+    ...collection(flags),
   };
   const path = kind === "speech" ? "audio/speech" : "audio/music";
   const res = await fetch(`${baseUrl}/api/v1/${path}`, {
@@ -397,7 +401,7 @@ async function cmdAudio(kind, prompt, flags) {
   const json = await res.json();
   const item = json.data?.[0];
   if (!item) die("no audio returned", 2);
-  if (item.url) console.log(item.url);
+  if (item.url) console.log(outputLine(item));
   if (flags.out) {
     if (item.b64_json) {
       const bytes = Buffer.from(item.b64_json, "base64");
@@ -409,6 +413,45 @@ async function cmdAudio(kind, prompt, flags) {
   }
 }
 
+/** `--collection <id>` keeps the results for good instead of letting them expire. */
+function collection(flags) {
+  return last(flags.collection) ? { collection: last(flags.collection) } : {};
+}
+
+/** The URL to use — the kept one when the result was saved — and what became of the save. */
+function outputLine(item, label = "") {
+  const saved = item.asset_id ? `  (saved as asset ${item.asset_id})` : item.asset_error ? `  (not saved: ${item.asset_error})` : "";
+  return `${label}${item.asset_url || item.url}${saved}`;
+}
+
+async function cmdCollections(action, name, flags) {
+  const { baseUrl, apiKey } = config(flags);
+  if (action === "create") {
+    if (!name) die('collections create needs a name: ottoport collections create "Spring campaign"');
+    const res = await fetch(`${baseUrl}/api/v1/collections`, {
+      method: "POST", headers: headers(apiKey),
+      body: JSON.stringify({ name, ...(last(flags.description) ? { description: last(flags.description) } : {}), ...(last(flags["external-id"]) ? { external_id: last(flags["external-id"]) } : {}) }),
+    });
+    if (!res.ok) die(await readError(res));
+    const created = await res.json();
+    if (flags.json) return void console.log(JSON.stringify(created, null, 2));
+    return void console.log(`${created.id}  ${created.name}`);
+  }
+  if (action && action !== "list") die(`unknown collections action: ${action} (list | create)`);
+  const res = await fetch(`${baseUrl}/api/v1/collections?limit=200`, { 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 { access } = body;
+  if (!access.enabled) {
+    console.error(access.override === false
+      ? "collections are disabled for this account"
+      : `collections are locked: top up $${(access.threshold_cents / 100).toFixed(2)} in total to unlock ($${(access.remaining_cents / 100).toFixed(2)} to go)`);
+  }
+  for (const c of body.data) console.log(`${c.id}  ${c.name}  (${c.asset_count ?? 0} asset${c.asset_count === 1 ? "" : "s"})`);
+  if (!body.data.length) console.error("no collections in this project yet");
+}
+
 const HELP = `OttoPort — one command for every model.
 
 Usage:
@@ -434,6 +477,8 @@ Usage:
   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 collections [list] [--json]          collections in the key's project
+  ottoport collections create "<name>" [--description "..."] [--external-id <id>]
   ottoport mcp
   ottoport install <host>   wire the MCP server (and skill) into an agent
                             hosts: codex, claude, hermes, cursor, windsurf, claude-desktop
@@ -443,6 +488,8 @@ 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)
+  --collection <id>     on image, video, speech, music: keep the results in
+                        that collection instead of letting them expire
 
 Examples:
   export OTTOPORT_API_KEY=op-...
@@ -459,6 +506,8 @@ Examples:
   ottoport image --model seedream-5.0-layers --image https://…/poster.png
   ottoport speech "Welcome to OttoPort" --voice alloy --out welcome.mp3
   ottoport music "lo-fi focus beat" --duration 20 --out focus.mp3
+  ottoport collections create "Spring campaign"
+  ottoport image "spring hero banner" --collection <collection-id>
   ottoport mcp
   ottoport install codex
 `;
@@ -477,6 +526,7 @@ async function main() {
       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 "collections": return await cmdCollections(rest[0], rest.slice(1).join(" "), flags);
       case "mcp": return await import(new URL("../mcp/server.mjs", import.meta.url));
       case "install": {
         const { cmdInstall } = await import(new URL("./install.mjs", import.meta.url));

package/mcp/server.mjs

@@ -6,14 +6,16 @@
 // transport directly (newline-delimited messages).
 //
 // Config via env:
-//   OTTOPORT_API_KEY   your op-… key (or the dev OTTOPORT_KEY_SECRET)
-//   OTTOPORT_BASE_URL  gateway base URL (default http://localhost:3014)
+//   OTTOPORT_API_KEY     your op-… key (or the dev OTTOPORT_KEY_SECRET)
+//   OTTOPORT_BASE_URL    gateway base URL (default http://localhost:3014)
+//   OTTOPORT_COLLECTION  optional collection (id or name) every generation is saved into
 //
 // Register with Claude Code:
 //   claude mcp add ottoport -- node /abs/path/to/mcp/server.mjs
 
 import { createInterface } from "node:readline";
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
+import { basename, extname, resolve as resolvePath } from "node:path";
 
 const PROTOCOL_VERSION = "2024-11-05";
 // Read from the package rather than repeated here: a version that says 0.1.0
@@ -43,6 +45,113 @@ async function gwError(res) {
   return `${res.status} ${res.statusText}`;
 }
 
+// ── collections ──────────────────────────────────────────────────────
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+async function api(path, init = {}) {
+  const res = await fetch(`${BASE}${path}`, { ...init, headers: { ...headers(Boolean(init.body)), ...(init.headers ?? {}) } });
+  if (!res.ok) throw new Error(await gwError(res));
+  return res.json();
+}
+
+/**
+ * The collection id for what the agent (or OTTOPORT_COLLECTION) named.
+ *
+ * The gateway takes ids only, because names repeat and get renamed. People
+ * say names, though — "save it to Spring campaign" — so a name is looked up
+ * here: one match is used, several or none is an error that lists what
+ * exists, so the agent asks rather than guesses.
+ */
+async function collectionId(ref) {
+  const wanted = typeof ref === "string" && ref.trim() ? ref.trim() : process.env.OTTOPORT_COLLECTION?.trim();
+  if (!wanted) return undefined;
+  if (UUID.test(wanted)) return wanted;
+  const { data } = await api("/api/v1/collections?limit=200");
+  const matches = data.filter((c) => c.name.toLowerCase() === wanted.toLowerCase());
+  if (matches.length === 1) return matches[0].id;
+  const known = data.map((c) => `"${c.name}" (${c.id})`).join(", ") || "none yet";
+  if (matches.length > 1) throw new Error(`Several collections are named "${wanted}": ${matches.map((c) => c.id).join(", ")}. Pass the id.`);
+  throw new Error(`No collection named "${wanted}". Existing collections: ${known}. Create one with ottoport_create_collection.`);
+}
+
+/** One output line: the kept URL when it was saved, and what became of the save. */
+function outputLine(item, label = "") {
+  const url = item.asset_url || item.url;
+  const saved = item.asset_id ? ` (saved as asset ${item.asset_id})` : item.asset_error ? ` (not saved: ${item.asset_error})` : "";
+  return `${label}${url}${saved}`;
+}
+
+const withCollection = (id) => (id ? { collection: id } : {});
+
+const dollars = (cents) => `$${(cents / 100).toFixed(2)}`;
+const megabytes = (bytes) => `${(bytes / 1_048_576).toFixed(1)} MB`;
+
+async function listCollections() {
+  const { data, access } = await api("/api/v1/collections?limit=200");
+  const state = access.enabled
+    ? `Collections are on: ${megabytes(access.used_bytes)} of ${megabytes(access.quota_bytes)} used.`
+    : access.override === false
+      ? "Collections are disabled for this account; nothing can be saved."
+      : `Collections are locked: they unlock once the account has topped up ${dollars(access.threshold_cents)} in total (${dollars(access.remaining_cents)} to go, at ${BASE}/dashboard). Existing collections can still be read.`;
+  const rows = data.map((c) => `${c.name} — id ${c.id} · ${c.asset_count ?? 0} asset${c.asset_count === 1 ? "" : "s"}${c.external_id ? ` · external_id ${c.external_id}` : ""}${c.description ? ` — ${c.description}` : ""}`);
+  return [state, ...(rows.length ? rows : ["No collections in this project yet."])].join("\n");
+}
+
+async function createCollection({ name, description, external_id }) {
+  if (!name) throw new Error("`name` is required");
+  const c = await api("/api/v1/collections", { method: "POST", body: JSON.stringify({ name, ...(description ? { description } : {}), ...(external_id ? { external_id } : {}) }) });
+  return `Created collection "${c.name}" — id ${c.id}. Pass it as \`collection\` to any generate tool to save the results there.`;
+}
+
+async function listAssets({ collection, kind, limit = 20 }) {
+  const id = await collectionId(collection);
+  const qs = new URLSearchParams({ limit: String(limit), ...(id ? { collection_id: id } : {}), ...(kind ? { kind } : {}) });
+  const { data, total } = await api(`/api/v1/assets?${qs}`);
+  if (!data.length) return "No saved assets.";
+  const lines = data.map((a) => `${a.kind} ${a.id}: ${a.url}${a.model ? ` · ${a.model}` : ""}${a.prompt ? ` — "${a.prompt.slice(0, 80)}${a.prompt.length > 80 ? "…" : ""}"` : ""}`);
+  return `${lines.join("\n")}${total > data.length ? `\n(${total - data.length} more)` : ""}`;
+}
+
+async function saveAsset({ url, collection, prompt }) {
+  if (!url) throw new Error("`url` is required");
+  const id = await collectionId(collection);
+  if (!id) throw new Error("`collection` is required (an id or a name), or set OTTOPORT_COLLECTION");
+  const a = await api("/api/v1/assets", { method: "POST", body: JSON.stringify({ url, collection: id, ...(prompt ? { prompt } : {}) }) });
+  return `Saved as asset ${a.id}: ${a.url}`;
+}
+
+async function deleteAsset({ asset_id }) {
+  if (!asset_id) throw new Error("`asset_id` is required");
+  await api(`/api/v1/assets/${encodeURIComponent(asset_id)}`, { method: "DELETE" });
+  return `Deleted asset ${asset_id}.`;
+}
+
+const UPLOAD_TYPES = {
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif",
+  ".mp4": "video/mp4", ".mov": "video/quicktime", ".webm": "video/webm",
+  ".mp3": "audio/mpeg", ".wav": "audio/wav", ".ogg": "audio/ogg", ".m4a": "audio/mp4", ".flac": "audio/flac",
+};
+
+/**
+ * Put a local file where a model can read it. Agents hold paths, and every
+ * model input is a URL, so without this a reference image on disk is out of
+ * reach. The upload itself is temporary; `collection` also keeps it.
+ */
+async function uploadFile({ path, collection }) {
+  if (!path) throw new Error("`path` is required");
+  const file = resolvePath(path);
+  const type = UPLOAD_TYPES[extname(file).toLowerCase()];
+  if (!type) throw new Error(`Cannot upload ${basename(file)}: use PNG, JPEG, WebP, GIF, MP4, MOV, WebM, MP3, WAV, OGG, M4A or FLAC.`);
+  const { size } = statSync(file);
+  const signed = await api("/api/v1/uploads", { method: "POST", body: JSON.stringify({ content_type: type, size }) });
+  const put = await fetch(signed.upload_url, { method: "PUT", headers: signed.headers, body: readFileSync(file) });
+  if (!put.ok) throw new Error(`Upload failed (HTTP ${put.status})`);
+  const id = await collectionId(collection);
+  if (!id) return `Uploaded ${basename(file)}: ${signed.url}\nUse this URL as a model input until ${signed.expires_at}. Pass \`collection\` to keep it.`;
+  const a = await api("/api/v1/assets", { method: "POST", body: JSON.stringify({ url: signed.url, collection: id, metadata: { filename: basename(file) } }) });
+  return `Uploaded ${basename(file)} and saved it as asset ${a.id}: ${a.url}`;
+}
+
 // ── tool implementations ─────────────────────────────────────────────
 /**
  * What a model takes, in one clause.
@@ -179,7 +288,7 @@ async function waitForJob(statusPath, job, { timeoutMs, label }) {
 const IMAGE_JOB_PATH = "/api/v1/images/generations/{id}";
 const VIDEO_JOB_PATH = "/api/v1/videos/generations/{id}";
 
-async function generateImage({ prompt, model, ...rest }) {
+async function generateImage({ prompt, model, collection, ...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
   // knows which is which and says so.
@@ -197,7 +306,7 @@ async function generateImage({ prompt, model, ...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 }),
+    body: JSON.stringify({ model: model || "gpt-image-2", ...(prompt ? { prompt } : {}), ...rest, ...withCollection(await collectionId(collection)), async: true }),
   });
   if (!res.ok) throw new Error(await gwError(res));
   let json = await res.json();
@@ -211,12 +320,12 @@ async function generateImage({ prompt, model, ...rest }) {
   // 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) =>
-    d.layer ? `layer ${d.layer.index}${d.layer.name ? ` (${d.layer.name})` : ""}: ${d.url}` : d.url,
+    outputLine(d, d.layer ? `layer ${d.layer.index}${d.layer.name ? ` (${d.layer.name})` : ""}: ` : ""),
   );
   return lines.length ? lines.join("\n") : "(no image returned)";
 }
 
-async function generateVideo({ prompt, model, webhook_url, webhook_secret, ...rest }) {
+async function generateVideo({ prompt, model, webhook_url, webhook_secret, collection, ...rest }) {
   // A depth model takes only `video_url`; the gateway says which models need a prompt.
   // 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");
@@ -228,7 +337,7 @@ async function generateVideo({ prompt, model, webhook_url, webhook_secret, ...re
     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 ? { prompt } : {}), ...rest, ...(webhook_url ? { webhook_url, webhook_secret: secret } : {}) }),
+    body: JSON.stringify({ model: model || "kling-3.0", ...(prompt ? { prompt } : {}), ...rest, ...withCollection(await collectionId(collection)), ...(webhook_url ? { webhook_url, webhook_secret: secret } : {}) }),
   });
   if (!res.ok) throw new Error(await gwError(res));
   const submitted = await res.json();
@@ -241,7 +350,8 @@ async function generateVideo({ prompt, model, webhook_url, webhook_secret, ...re
   // job rather than returning a queued-job JSON blob to the agent.
   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;
+  const output = job.data?.[0];
+  const url = output?.url ? outputLine(output) : undefined;
   // 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);
@@ -259,7 +369,7 @@ async function videoWebhook({ job_id, action = "status" }) {
   return JSON.stringify({ id: body.id, status: body.status, webhook: body.webhook ?? null }, null, 2);
 }
 
-async function generateAudio(kind, { prompt, model, voice, duration, format }) {
+async function generateAudio(kind, { prompt, model, voice, duration, format, collection }) {
   if (!prompt) throw new Error("`prompt` is required");
   const res = await fetch(`${BASE}/api/v1/audio/${kind === "tts" ? "speech" : "music"}`, {
     method: "POST",
@@ -270,13 +380,15 @@ async function generateAudio(kind, { prompt, model, voice, duration, format }) {
       ...(voice ? { voice } : {}),
       ...(duration ? { duration } : {}),
       ...(format ? { format } : {}),
+      ...withCollection(await collectionId(collection)),
     }),
   });
   if (!res.ok) throw new Error(await gwError(res));
   const json = await res.json();
   const audio = json.data?.[0];
   if (!audio) return "(no audio returned)";
-  return audio.url || (audio.b64_json ? `data:audio;base64,${audio.b64_json}` : "(no audio returned)");
+  if (audio.url || audio.asset_url) return outputLine(audio);
+  return audio.b64_json ? `data:audio;base64,${audio.b64_json}` : "(no audio returned)";
 }
 
 // ── tool registry ────────────────────────────────────────────────────
@@ -334,6 +446,7 @@ const TOOLS = [
         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)." },
+        collection: { type: "string", description: "Save the result for good into this collection — its id or exact name (see ottoport_list_collections). Without it the file expires after a few days. Needs collections unlocked on the account. Defaults to OTTOPORT_COLLECTION when set." },
       },
     },
     handler: generateImage,
@@ -366,6 +479,7 @@ const TOOLS = [
         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." },
+        collection: { type: "string", description: "Save the result for good into this collection — its id or exact name (see ottoport_list_collections). Without it the file expires after a few days. Needs collections unlocked on the account. Defaults to OTTOPORT_COLLECTION when set." },
       },
       required: [],
     },
@@ -394,6 +508,7 @@ const TOOLS = [
         model: { type: "string", description: "TTS model id. Default gpt-4o-mini-tts." },
         voice: { type: "string", description: "Optional provider voice id." },
         format: { type: "string", description: 'e.g. "mp3" or "wav".' },
+        collection: { type: "string", description: "Save the result for good into this collection — its id or exact name (see ottoport_list_collections). Without it the file expires after a few days. Needs collections unlocked on the account. Defaults to OTTOPORT_COLLECTION when set." },
       },
       required: ["prompt"],
     },
@@ -409,11 +524,82 @@ const TOOLS = [
         model: { type: "string", description: "Music model id. Default suno-v5." },
         duration: { type: "number", description: "Requested duration in seconds." },
         format: { type: "string", description: 'e.g. "mp3" or "wav".' },
+        collection: { type: "string", description: "Save the result for good into this collection — its id or exact name (see ottoport_list_collections). Without it the file expires after a few days. Needs collections unlocked on the account. Defaults to OTTOPORT_COLLECTION when set." },
       },
       required: ["prompt"],
     },
     handler: (args) => generateAudio("music", args),
   },
+  {
+    name: "ottoport_list_collections",
+    description: "Collections in this API key's project — where generated files are kept for good instead of expiring after a few days — with each one's id and asset count, and whether this account may save (collections unlock once the account has topped up $10 in total). Read it before saving, to find the collection the user means.",
+    inputSchema: { type: "object", properties: {} },
+    handler: listCollections,
+  },
+  {
+    name: "ottoport_create_collection",
+    description: "Create a collection: the user's own project, campaign or character, whose generations should be kept together. Returns its id, to pass as `collection` to the generate tools. Needs collections unlocked.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Up to 80 characters." },
+        description: { type: "string" },
+        external_id: { type: "string", description: "The caller's own id for what this collection holds, unique in the project." },
+      },
+      required: ["name"],
+    },
+    handler: createCollection,
+  },
+  {
+    name: "ottoport_list_assets",
+    description: "Saved assets, newest first: each one's id, kind, permanent URL, model and prompt. Filter to one collection (id or name) and one kind.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        collection: { type: "string", description: "Collection id or exact name. Omit for every collection in the project." },
+        kind: { type: "string", enum: ["image", "video", "audio"] },
+        limit: { type: "number", description: "Default 20, at most 200." },
+      },
+    },
+    handler: listAssets,
+  },
+  {
+    name: "ottoport_save_asset",
+    description: "Keep a file that was already generated or uploaded — its OttoPort URL, before it expires — in a collection. Use when the user picks a result after the fact; to save while generating, pass `collection` to the generate tool instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "The OttoPort URL a generate tool or ottoport_upload_file returned." },
+        collection: { type: "string", description: "Collection id or exact name." },
+        prompt: { type: "string", description: "The prompt that made it, to keep alongside." },
+      },
+      required: ["url"],
+    },
+    handler: saveAsset,
+  },
+  {
+    name: "ottoport_upload_file",
+    description: "Upload a local image, video or audio file and get a URL any model accepts as input (a reference image, a first frame, a motion clip). The URL lasts a day; pass `collection` to also keep the file for good.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path of the file on this machine." },
+        collection: { type: "string", description: "Collection id or exact name to save it into." },
+      },
+      required: ["path"],
+    },
+    handler: uploadFile,
+  },
+  {
+    name: "ottoport_delete_asset",
+    description: "Delete a saved asset and its file for good. Ask the user first.",
+    inputSchema: {
+      type: "object",
+      properties: { asset_id: { type: "string" } },
+      required: ["asset_id"],
+    },
+    handler: deleteAsset,
+  },
 ];
 
 const TOOL_MAP = new Map(TOOLS.map((t) => [t.name, t]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ottoport",
-  "version": "1.11.0",
+  "version": "1.12.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

@@ -21,6 +21,15 @@ and do not call the HTTP API, when a tool covers the job:
 | `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`. |
+| `ottoport_list_collections` | The project's collections (ids, asset counts) and whether this account may save. Read it to find the collection the user means. |
+| `ottoport_create_collection` | `name`, plus optional `description`, `external_id`. |
+| `ottoport_list_assets` | Saved files, optionally by `collection` and `kind`. |
+| `ottoport_save_asset` | `url` (an OttoPort result or upload, before it expires) and `collection` — for keeping a result the user picks after the fact. |
+| `ottoport_upload_file` | `path` of a local file → a URL any model takes as input; with `collection` it is kept too. |
+| `ottoport_delete_asset` | `asset_id`. Permanent — confirm with the user first. |
+
+Every generate tool also takes `collection` (an id or exact name) to keep its
+results; the server's `OTTOPORT_COLLECTION` sets a default.
 
 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
@@ -90,8 +99,12 @@ as given rather than converting yourself.
 
 ## What comes back
 
-- Image, video and audio tools return **URLs**, not files. Provider URLs expire;
-  download anything worth keeping.
+- Image, video and audio tools return **URLs**, not files. They expire after a
+  few days. To keep one, pass `collection` (or save it with
+  `ottoport_save_asset` while it lasts) — the returned URL is then permanent.
+  Collections unlock once the account has topped up $10 in total; when
+  `ottoport_list_collections` says they are locked, tell the user that rather
+  than retrying.
 - Video blocks until the job is terminal, often a minute or more. Say so before
   starting, and never retry a slow call — a retry is a second generation, billed
   again.