ottoport 1.15.2 → 1.16.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 \u2014 as MCP tools, slash commands, or the bundled CLI.",
-  "version": "1.15.2",
+  "version": "1.16.0",
   "author": {
     "name": "LITBOX LLC",
     "email": "support@ottoport.ai"

package/README.md

@@ -21,23 +21,23 @@ ottoport chat  "<prompt>" [--model claude-sonnet-5] [--system "..."] [--no-strea
                           [--temperature 0.7] [--max-tokens 512]
 ottoport image "<prompt>" [--model gpt-image-2] [--size 1024x1024 | --resolution 2k]
                           [--quality high] [--aspect-ratio 16:9] [--n 1] [--seed 7]
-                          [--image <url>] [--ref <url>[,<url>…]] [--out file.png]
+                          [--image <url>] [--ref <url>[,<url>…]] [--wait --out file.png]
 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]
+                          [--ref <url>[,<url>…]] [--wait --out clip.mp4]
+                          [--webhook-url https://…]
 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-v6] [--duration 15] [--out song.mp3]
+ottoport speech "<text>"  [--model gpt-4o-mini-tts] [--voice alloy] [--wait --out speech.mp3]
+ottoport music "<prompt>" [--model suno-v6] [--duration 15] [--wait --out song.mp3]
 ottoport music --model mirelo-sfx-2.0 --video <url> [--duration 8]   # soundtrack for a video
 
 ottoport install <host>   # wire the MCP server into an agent
 ottoport mcp              # run the MCP server on stdio
 ```
 
-Chat streams by default. Image, video and audio commands print the result URL;
-`--out` downloads it. `--url` and `--key` override the environment for a single
+Chat streams by default. Image, video and audio commands return a job at once;
+`--wait` waits for the result URL and `--wait --out` also downloads it. `--url` and `--key` override the environment for a single
 call.
 
 Every command is a thin client over the public REST API, so anything the CLI
@@ -159,9 +159,9 @@ https://ottoport.ai/docs#webhooks.
 
 - 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, unless a webhook is given or `--no-wait` is passed. A retry is a
-  second billable generation, not a resumption.
+- Video generation takes a minute or more. The call returns a job at once and
+  only blocks with `--wait`. A retry is a second billable generation, not a
+  resumption.
 - `resolution` and `quality` are price multipliers, not formatting hints. Leave
   them unset to bill at the model's base tier.
 - Requests are billed against the prepaid balance on your OttoPort account.
@@ -183,6 +183,6 @@ ottoport job image <job-id> --wait --out lake.png
 ottoport image "a mountain lake" --wait --out lake.png
 ```
 
-Use job kinds `image`, `video`, `speech`, or `music`. `--out` downloads only when a result is available; otherwise query the returned job with `--wait --out`. Pending and failed job responses retain the task ID and status route.
+Use job kinds `image`, `video`, `speech`, or `music`. On generation commands `--out` needs `--wait`, and is refused before anything is submitted without it. `ottoport job <kind> <id> --out file` saves a finished job and exits 3 if it is still running. `--wait` gives up after 30 minutes by default (`--timeout <seconds>`) and exits 3; the job keeps running and can be resumed with `ottoport job`. Pending and failed job responses retain the task ID and status route.
 
 MCP generation tools return `job_id`, `status`, `status_path`, and the next tool call. Query with `ottoport_get_job({kind, job_id})`. Optional `wait: true` waits up to 45 seconds per MCP call, returning the same job if still pending. Querying a job does not submit another generation. Existing scripts that expected immediate URLs should add `--wait`, or adopt job polling.

package/cli/ottoport.mjs

@@ -6,10 +6,10 @@
 //   ottoport models [--modality chat|image|video]
 //   ottoport chat   "prompt" [--model claude-sonnet-5] [--system "..."] [--no-stream]
 //                   [--video <url|file>]   ask about a video (defaults to video-understanding)
-//   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-v6] [--duration 15] [--out song.mp3]
+//   ottoport image  "prompt" [--model gpt-image-2] [--resolution 2k] [--ref a.png,b.png] [--wait --out img.png]
+//   ottoport video  "prompt" [--model kling-3.0] [--duration 5] [--wait --out clip.mp4]
+//   ottoport speech "text" [--model gpt-4o-mini-tts] [--voice alloy] [--wait --out speech.mp3]
+//   ottoport music  "prompt" [--model suno-v6] [--duration 15] [--wait --out song.mp3]
 //   ottoport music  --model mirelo-sfx-2.0 --video <url> [--duration 8]
 //   ottoport collections [list | create "name"]
 //   ottoport mcp
@@ -270,12 +270,43 @@ function references(flags, name = "ref") {
 }
 
 const JOB_PATHS = { image: "images/generations", video: "videos/generations", speech: "audio/speech", music: "audio/music" };
+const PENDING = ["queued", "processing"];
+// Long enough for a slow video queue; the job itself carries on past it either way.
+const DEFAULT_WAIT_SECONDS = 1800;
+
+function waitSeconds(flags) {
+  if (flags.timeout === undefined) return DEFAULT_WAIT_SECONDS;
+  const seconds = Number(last(flags.timeout));
+  if (!(seconds > 0)) die("--timeout takes a number of seconds above 0");
+  return seconds;
+}
+
+/**
+ * Jobs are asynchronous and only --wait blocks. With neither a wait nor a later
+ * process to save it, --out could never produce a file, so it is refused before
+ * anything is spent.
+ */
+function checkSubmitFlags(kind, flags) {
+  waitSeconds(flags);
+  if (!flags.out || flags.wait === true) return;
+  const file = last(flags.out);
+  die(`--out needs --wait: jobs run asynchronously, so no file would be saved. Nothing was submitted.
+  wait and save now:  add --wait to this command
+  save it later:      drop --out, then run: ottoport job ${kind} <job-id> --wait --out ${file}`);
+}
+
 async function resolveJob(kind, job, flags) {
-  if (!job.id || !job.status) return job;
+  if (!job.id || !job.status || flags.wait !== true) return job;
   const { baseUrl, apiKey } = config(flags);
   // Always expose the ID before a caller opts into waiting.
-  if (flags.wait === true) console.error(`job ${job.id} accepted`);
-  while (flags.wait === true && ["queued", "processing"].includes(job.status)) {
+  console.error(`job ${job.id} accepted`);
+  const seconds = waitSeconds(flags);
+  const deadline = Date.now() + seconds * 1000;
+  while (PENDING.includes(job.status)) {
+    if (Date.now() >= deadline) {
+      printJob(kind, job);
+      die(`job ${job.id} is still ${job.status} after ${seconds}s and keeps running. Resume with: ottoport job ${kind} ${job.id} --wait${flags.out ? ` --out ${last(flags.out)}` : ""}`, 3);
+    }
     await new Promise((resolve) => setTimeout(resolve, 3000));
     const res = await fetch(`${baseUrl}/api/v1/${JOB_PATHS[kind]}/${encodeURIComponent(job.id)}`, { headers: headers(apiKey, false) });
     if (!res.ok) die(await readError(res));
@@ -287,13 +318,16 @@ function printJob(kind, job) {
   console.log(JSON.stringify({ ...job, job_id: job.id, kind, status_path: `/api/v1/${JOB_PATHS[kind]}/${encodeURIComponent(job.id)}`, next: `ottoport job ${kind} ${job.id}` }, null, 2));
 }
 async function cmdJob(kind, id, flags) {
-  if (!Object.hasOwn(JOB_PATHS, kind) || !id) die("usage: ottoport job image|video|speech|music <id> [--wait] [--out file]");
+  if (!Object.hasOwn(JOB_PATHS, kind) || !id) die("usage: ottoport job image|video|speech|music <id> [--wait [--timeout seconds]] [--out file]");
+  waitSeconds(flags);
   const { baseUrl, apiKey } = config(flags);
   const res = await fetch(`${baseUrl}/api/v1/${JOB_PATHS[kind]}/${encodeURIComponent(id)}`, { headers: headers(apiKey, false) });
   if (!res.ok) die(await readError(res));
   const job = await resolveJob(kind, await res.json(), flags);
   printJob(kind, job);
   if (job.status === "failed") die(job.error || "generation failed", 2);
+  // Looking at a job never blocks unless asked, but a file that was named and not saved must not read as success.
+  if (flags.out && PENDING.includes(job.status)) die(`job ${id} is still ${job.status}, so nothing was saved. Wait and save with: ottoport job ${kind} ${id} --wait --out ${last(flags.out)}`, 3);
   const item = job.data?.[0];
   if (flags.out && (item?.asset_url || item?.url)) await download(item.asset_url || item.url, last(flags.out));
 }
@@ -309,6 +343,7 @@ async function cmdImage(prompt, flags) {
   if (wantsFile && outExtension && outExtension !== format) {
     die(`--format ${format} returns a .${format} file, but --out names a .${outExtension} one. Change one of them.`);
   }
+  checkSubmitFlags("image", flags);
   const body = {
     async: true,
     // The default model has no GIF or SVG output, so asking for one picks a model that does.
@@ -351,6 +386,7 @@ async function cmdVideo(prompt, flags) {
   // A draft's 1080p render takes everything from the draft, the prompt included.
   const draftId = last(flags["draft-id"]);
   if (!prompt && !last(flags.video) && !draftId) die("video requires a prompt: ottoport video \"a drone shot\" (or --video <url> on a depth model)");
+  checkSubmitFlags("video", flags);
   const { baseUrl, apiKey } = config(flags);
   // Drafts are Seedance 2.5's, so a draft with no model named is one of its.
   const model = last(flags.model) || (flags.draft === true || draftId ? "seedance-2.5" : "kling-3.0");
@@ -382,15 +418,7 @@ async function cmdVideo(prompt, flags) {
   let job = await res.json();
   if (job.status === "failed") die(job.error || "video generation failed", 2);
   if (body.webhook_url) process.stderr.write(`webhook: ${body.webhook_url} will be notified when the job finishes\n`);
-  if (flags.wait === true) {
-    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));
-      const status = await fetch(`${baseUrl}/api/v1/videos/generations/${encodeURIComponent(job.id)}`, { headers: headers(apiKey, false) });
-      if (!status.ok) die(await readError(status));
-      job = await status.json();
-    }
-  }
+  job = await resolveJob("video", job, flags);
   printJob("video", job);
   if (job.status === "failed") die(job.error || "video generation failed", 2);
   const url = job.data?.[0]?.url;
@@ -444,6 +472,7 @@ async function cmdAudio(kind, prompt, flags) {
   // A sound-effects model scores a video, so the prompt is optional with one.
   const video = kind === "music" ? last(flags.video) : undefined;
   if (!prompt && !video) die(`${kind} requires a prompt: ottoport ${kind} "hello"`);
+  checkSubmitFlags(kind, flags);
   const { baseUrl, apiKey } = config(flags);
   const body = {
     async: true,
@@ -537,7 +566,7 @@ Usage:
                             [--temperature 0.7] [--max-tokens 512]
   ottoport image "<prompt>" [--model gpt-image-2] [--size 1024x1024 | --resolution 2k] [--quality high]
                             [--aspect-ratio 16:9] [--n 1] [--seed 7]
-                            [--image <url>] [--ref <url>[,<url>…]] [--out file.png]
+                            [--image <url>] [--ref <url>[,<url>…]] [--wait --out file.png]
   ottoport image "<prompt>" --format gif|svg [--model gpt-image-2.6] [--frames 8] [--frame-ms 200] [--wait --out loop.gif]
   ottoport image --model qwen-image-layered --image <url> [--layers 4]
                             split one image into RGBA layers (prompt optional)
@@ -546,17 +575,18 @@ Usage:
                             [--last-frame <url>] [--ref <url>[,<url>…]]
                             [--ref-video <url>[,<url>…]] [--ref-audio <url>[,<url>…]]
                             [--draft] [--webhook-url https://…] [--webhook-secret <s>]
-                            [--no-wait] [--out clip.mp4]
-  ottoport video --draft-id <job-id> [--model seedance-2.5] [--out clip.mp4]
+                            [--wait --out clip.mp4]
+  ottoport video --draft-id <job-id> [--model seedance-2.5] [--wait --out clip.mp4]
                             render a Seedance 2.5 draft (--draft, or the
                             seedance-2.5-draft model) in 1080p, within 7 days
-  ottoport video --model video-depth-anything --video <url> [--out depth.mp4]
+  ottoport video --model video-depth-anything --video <url> [--wait --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-v6] [--duration 15] [--format mp3] [--out song.mp3]
-  ottoport music  ["<prompt>"] --model mirelo-sfx-2.0 --video <url> [--duration 8] [--out sfx.wav]
+  ottoport speech "<text>" [--model gpt-4o-mini-tts] [--voice alloy] [--format mp3] [--wait --out speech.mp3]
+  ottoport music  "<prompt>" [--model suno-v6] [--duration 15] [--format mp3] [--wait --out song.mp3]
+                            On Suno, --duration is a target length; the price per request stays flat
+  ottoport music  ["<prompt>"] --model mirelo-sfx-2.0 --video <url> [--duration 8] [--wait --out sfx.wav]
                             a soundtrack synced to the video, dialogue kept;
                             set --duration to the clip's length (it bills)
   ottoport collections [list] [--json]          collections in the key's project
@@ -572,6 +602,10 @@ Global flags:
   --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
+  --wait                on image, video, speech, music, job: block until the job
+                        finishes. Exit 3 if it is still running at the timeout
+  --timeout <seconds>   how long --wait blocks (default ${DEFAULT_WAIT_SECONDS})
+  --out <file>          save the result; generation commands need --wait with it
 
 Examples:
   export OTTOPORT_API_KEY=op-...
@@ -579,19 +613,19 @@ Examples:
   ottoport models veo-3.1               # its modes, tiers, and every parameter
   ottoport chat "explain MCP in one line" --model claude-haiku-4.5
   ottoport chat "break this clip down shot by shot" --video https://example.com/clip.mp4
-  ottoport image "isometric city at dusk" --model gpt-image-2 --out city.png
+  ottoport image "isometric city at dusk" --model gpt-image-2 --wait --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 video "drone over fjords" --webhook-url https://example.com/hooks/ottoport
   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
-  ottoport music "lo-fi focus beat" --duration 20 --out focus.mp3
-  ottoport music "rain on a tin roof" --model mirelo-sfx-2.0 --duration 10 --format mp3 --out rain.mp3
-  ottoport music --model mirelo-sfx-2.0 --video https://example.com/chase.mp4 --duration 8 --out chase.wav
-  Media commands return jobs immediately. Add --wait to wait for results.
-  ottoport job image|video|speech|music <id> [--wait] [--out file]
+  ottoport speech "Welcome to OttoPort" --voice alloy --wait --out welcome.mp3
+  ottoport music "lo-fi focus beat" --duration 20 --wait --out focus.mp3
+  ottoport music "rain on a tin roof" --model mirelo-sfx-2.0 --duration 10 --format mp3 --wait --out rain.mp3
+  ottoport music --model mirelo-sfx-2.0 --video https://example.com/chase.mp4 --duration 8 --wait --out chase.wav
+  Media commands return jobs immediately. Add --wait to wait for the result, and --wait --out to save it.
+  ottoport job image|video|speech|music <id> [--wait] [--out file]   --out alone saves a finished job, exit 3 if it is not done
   ottoport collections create "Spring campaign"
   ottoport image "spring hero banner" --collection <collection-id>
   ottoport mcp

package/mcp/server.mjs

@@ -571,7 +571,7 @@ const TOOLS = [
         wait: { type: "boolean", description: "Default false: return job immediately. True waits up to 45 seconds, then returns the same job for polling." },
         prompt: { type: "string", description: "Music-generation prompt, or the sounds to make. Optional with video_url." },
         model: { type: "string", description: "Music model id. Default suno-v6; mirelo-sfx-2.0 for sound effects." },
-        duration: { type: "number", description: "Requested duration in seconds." },
+        duration: { type: "number", description: "Requested length in seconds, billed per second. On the Suno models it is a target length instead: each request has one flat price, and the song may run longer or shorter." },
         video_url: { type: "string", description: "mirelo-sfx-2.0 only: an http(s) video to score. Set duration to its length — duration is what bills." },
         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." },

package/package.json

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

@@ -123,12 +123,12 @@ export OTTOPORT_API_KEY=op-... # keys: https://ottoport.ai/api-keys
 
 ottoport models --modality image
 ottoport chat "explain MCP in one sentence" --model claude-haiku-4.5
-ottoport image "isometric city at dusk" --out city.png
-ottoport video "drone shot over a canyon" --duration 5 --out clip.mp4
-ottoport speech "Welcome to OttoPort" --voice alloy --out welcome.mp3
+ottoport image "isometric city at dusk" --wait --out city.png
+ottoport video "drone shot over a canyon" --duration 5 --wait --out clip.mp4
+ottoport speech "Welcome to OttoPort" --voice alloy --wait --out welcome.mp3
 ```
 
-`--out` downloads the result; chat streams unless `--no-stream`.
+`--wait --out` waits and downloads the result; chat streams unless `--no-stream`.
 
 ## Calling from code
 
@@ -159,6 +159,6 @@ ottoport job image <job-id> --wait --out lake.png
 ottoport image "a mountain lake" --wait --out lake.png
 ```
 
-Use job kinds `image`, `video`, `speech`, or `music`. `--out` downloads only when a result is available; otherwise query the returned job with `--wait --out`. Pending and failed job responses retain the task ID and status route.
+Use job kinds `image`, `video`, `speech`, or `music`. On generation commands `--out` needs `--wait`, and is refused before anything is submitted without it. `ottoport job <kind> <id> --out file` saves a finished job and exits 3 if it is still running. `--wait` gives up after 30 minutes by default (`--timeout <seconds>`) and exits 3; the job keeps running and can be resumed with `ottoport job`. Pending and failed job responses retain the task ID and status route.
 
 MCP generation tools return `job_id`, `status`, `status_path`, and the next tool call. Query with `ottoport_get_job({kind, job_id})`. Optional `wait: true` waits up to 45 seconds per MCP call, returning the same job if still pending. Querying a job does not submit another generation. Existing scripts that expected immediate URLs should add `--wait`, or adopt job polling.