ottoport 1.13.2 → 1.15.1

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.13.2",
+  "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.1",
   "author": {
     "name": "LITBOX LLC",
     "email": "support@ottoport.ai"

package/README.md

@@ -30,6 +30,7 @@ ottoport video "<prompt>" [--model kling-3.0] [--duration 5] [--resolution 1080p
 ottoport webhook status|retry <job-id>   # delivery attempts / redeliver now
 ottoport speech "<text>"  [--model gpt-4o-mini-tts] [--voice alloy] [--out speech.mp3]
 ottoport music "<prompt>" [--model suno-v5] [--duration 15] [--out song.mp3]
+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
@@ -94,16 +95,29 @@ the character performs the clip's movement). Images take one reference (`image_u
 (`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.
 
-The GPT Image family and `ideogram-4.5` read a `quality` on top of that — `low`, `medium` (the
-default every catalog rate is measured at), `high`, and on `gpt-image-2.5` and
-`gpt-image-2.5-flare` also `xhigh` and `max`. It is how much compute the model
-spends, and the ladder is steep: `max` bills sixteen times `medium`.
+The GPT Image family, `ideogram-4.5` and `ideogram-vector-1` read a `quality` on top of that — `low`, `medium` (the
+default every catalog rate is measured at), `high`, and on `gpt-image-2.6`,
+`gpt-image-2.6-flare`, `gpt-image-2.5` and `gpt-image-2.5-flare` also `xhigh`
+and `max`. It is how much compute the model spends, and the ladder is steep:
+`max` bills sixteen times `medium` on 2.5 and about five times on 2.6.
 
 Two image models take a picture apart instead: `qwen-image-layered` and
 `seedream-5.0-layers` split `image_url` into RGBA layers and return one URL per
 layer, bottom first (the prompt is an optional caption; `num_layers`, 2–10, is
 honoured by Qwen only). Each layer returned bills separately.
 
+Two return SVG: `ideogram-vector-1` draws editable vectors from a prompt
+(shaped by `aspect_ratio`, not `size` or `resolution`), and
+`ideogram-vector-1-vectorize` traces `image_url` into one, with no prompt
+(`vector_mode`: `default` or `simple`).
+
+`gpt-image-2.6` and `gpt-image-2.6-flare` can also return a file other than a
+raster, from a prompt alone: `output_format: "gif"` is an animation (`frame_count`
+2–16, default 8; above 8 bills double; `frame_duration_ms` 20–2000), and
+`output_format: "svg"` is a vector file at a small surcharge. One file per
+request. A GIF picks its own frame size, so `size`, `resolution` and
+`aspect_ratio` do not apply to it.
+
 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
@@ -149,3 +163,20 @@ https://ottoport.ai/docs#webhooks.
 Docs: <https://ottoport.ai/docs> · Support: support@ottoport.ai
 
 MIT © LITBOX LLC
+
+
+## Asynchronous media jobs (1.15.1)
+
+Image, video, speech and music generation return an accepted job immediately by default. Save its `job_id`; do not resubmit to check progress. Chat streaming is unchanged.
+
+```sh
+ottoport image "a mountain lake" --model midjourney-v8.2
+ottoport job image <job-id>
+ottoport job image <job-id> --wait --out lake.png
+# Explicit waiting is also available on submission:
+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.
+
+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

@@ -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 music  --model mirelo-sfx-2.0 --video <url> [--duration 8]
 //   ottoport collections [list | create "name"]
 //   ottoport mcp
 //   ottoport install <codex|claude|hermes|cursor|windsurf|claude-desktop>
@@ -25,7 +26,7 @@ const BASE = "https://ottoport.ai";
 
 // ── arg parsing ──────────────────────────────────────────────────────
 // Switches that never take a value, so `--draft "a boat"` keeps its prompt.
-const BOOLEAN_FLAGS = new Set(["draft"]);
+const BOOLEAN_FLAGS = new Set(["draft", "wait"]);
 
 function parseArgs(argv) {
   const positional = [];
@@ -266,17 +267,50 @@ function references(flags, name = "ref") {
   return list.length ? list : undefined;
 }
 
+const JOB_PATHS = { image: "images/generations", video: "videos/generations", speech: "audio/speech", music: "audio/music" };
+async function resolveJob(kind, job, flags) {
+  if (!job.id || !job.status) 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)) {
+    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));
+    job = await res.json();
+  }
+  return job;
+}
+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]");
+  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);
+  const item = job.data?.[0];
+  if (flags.out && (item?.asset_url || item?.url)) await download(item.asset_url || item.url, last(flags.out));
+}
+
 async function cmdImage(prompt, flags) {
   // A layer-decomposition model needs only --image; the prompt is a caption.
   if (!prompt && !last(flags.image)) die("image requires a prompt: ottoport image \"a red fox\" (or --image <url> on a layer model)");
   const { baseUrl, apiKey } = config(flags);
   const body = {
+    async: true,
     model: last(flags.model) || "gpt-image-2",
     ...(prompt ? { prompt } : {}),
     ...(last(flags.layers) ? { num_layers: Number(last(flags.layers)) } : {}),
     ...(last(flags.size) ? { size: last(flags.size) } : {}),
     ...(last(flags.resolution) ? { resolution: last(flags.resolution) } : {}),
     ...(last(flags.quality) ? { quality: last(flags.quality) } : {}),
+    ...(last(flags.format) ? { output_format: last(flags.format) } : {}),
+    ...(last(flags.frames) ? { frame_count: Number(last(flags.frames)) } : {}),
+    ...(last(flags["frame-ms"]) ? { frame_duration_ms: Number(last(flags["frame-ms"])) } : {}),
     ...(last(flags["aspect-ratio"]) ? { aspect_ratio: last(flags["aspect-ratio"]) } : {}),
     ...(last(flags.n) ? { n: Number(last(flags.n)) } : {}),
     ...(last(flags.seed) ? { seed: Number(last(flags.seed)) } : {}),
@@ -290,7 +324,11 @@ async function cmdImage(prompt, flags) {
     body: JSON.stringify(body),
   });
   if (!res.ok) die(await readError(res));
-  const json = await res.json();
+  const json = await resolveJob("image", await res.json(), flags);
+  if (json.id) {
+    printJob("image", json);
+    if (json.status === "failed") die(json.error || "image generation failed", 2);
+  }
   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) =>
@@ -324,7 +362,7 @@ async function cmdVideo(prompt, flags) {
     ...webhook(flags),
     ...collection(flags),
   };
-  console.error("submitting video job (this can take a minute)…");
+  console.error("submitting video job…");
   const res = await fetch(`${baseUrl}/api/v1/videos/generations`, {
     method: "POST",
     headers: { ...headers(apiKey), "idempotency-key": crypto.randomUUID() },
@@ -334,7 +372,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 !== false) {
+  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));
@@ -343,6 +381,7 @@ async function cmdVideo(prompt, flags) {
       job = await status.json();
     }
   }
+  printJob("video", job);
   if (job.status === "failed") die(job.error || "video generation failed", 2);
   const url = job.data?.[0]?.url;
   if (url) {
@@ -352,8 +391,6 @@ async function cmdVideo(prompt, flags) {
       process.stderr.write(`draft ${job.id} — render it in 1080p within seven days: ottoport video --model ${model} --draft-id ${job.id}\n`);
     }
     if (flags.out) await download(url, last(flags.out));
-  } else {
-    console.log(JSON.stringify(job, null, 2));
   }
 }
 
@@ -394,11 +431,15 @@ async function cmdWebhook(action, jobId, flags) {
 }
 
 async function cmdAudio(kind, prompt, flags) {
-  if (!prompt) die(`${kind} requires a prompt: ottoport ${kind} "hello"`);
+  // 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"`);
   const { baseUrl, apiKey } = config(flags);
   const body = {
+    async: true,
     model: last(flags.model) || (kind === "speech" ? "gpt-4o-mini-tts" : "suno-v5"),
-    prompt,
+    ...(prompt ? { prompt } : {}),
+    ...(video ? { video_url: video } : {}),
     ...(last(flags.voice) ? { voice: last(flags.voice) } : {}),
     ...(last(flags.duration) ? { duration: Number(last(flags.duration)) } : {}),
     ...(last(flags.format) ? { format: last(flags.format) } : {}),
@@ -407,11 +448,16 @@ async function cmdAudio(kind, prompt, flags) {
   const path = kind === "speech" ? "audio/speech" : "audio/music";
   const res = await fetch(`${baseUrl}/api/v1/${path}`, {
     method: "POST",
-    headers: headers(apiKey),
+    headers: { ...headers(apiKey), "idempotency-key": crypto.randomUUID() },
     body: JSON.stringify(body),
   });
   if (!res.ok) die(await readError(res));
-  const json = await res.json();
+  const json = await resolveJob(kind, await res.json(), flags);
+  if (json.id) {
+    printJob(kind, json);
+    if (json.status === "failed") die(json.error || "audio generation failed", 2);
+    if (["queued", "processing"].includes(json.status)) return;
+  }
   const item = json.data?.[0];
   if (!item) die("no audio returned", 2);
   if (item.url) console.log(outputLine(item));
@@ -482,6 +528,7 @@ Usage:
   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]
+  ottoport image "<prompt>" --model gpt-image-2.6 --format gif|svg [--frames 8] [--frame-ms 200]
   ottoport image --model qwen-image-layered --image <url> [--layers 4]
                             split one image into RGBA layers (prompt optional)
   ottoport video "<prompt>" [--model kling-3.0] [--duration 5] [--resolution 1080p]
@@ -499,6 +546,9 @@ 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 music  ["<prompt>"] --model mirelo-sfx-2.0 --video <url> [--duration 8] [--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
   ottoport collections create "<name>" [--description "..."] [--external-id <id>]
   ottoport mcp
@@ -528,6 +578,10 @@ 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 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 collections create "Spring campaign"
   ottoport image "spring hero banner" --collection <collection-id>
   ottoport mcp
@@ -545,6 +599,7 @@ async function main() {
       case "chat": return await cmdChat(prompt, flags);
       case "image": return await cmdImage(prompt, flags);
       case "video": return await cmdVideo(prompt, flags);
+      case "job": return await cmdJob(rest[0], rest[1], flags);
       case "webhook": return await cmdWebhook(rest[0], rest[1], flags);
       case "speech": return await cmdAudio("speech", prompt, flags);
       case "music": return await cmdAudio("music", prompt, flags);

package/commands/speech.md

@@ -1,5 +1,5 @@
 ---
-description: Turn text into speech, or a prompt into music, through the OttoPort gateway
+description: Turn text into speech, or a prompt into music or sound effects, through the OttoPort gateway
 argument-hint: "<text> [--voice alloy] [--music]"
 allowed-tools: mcp__ottoport__ottoport_generate_speech, mcp__ottoport__ottoport_generate_music, Bash(curl:*)
 ---
@@ -7,7 +7,9 @@ allowed-tools: mcp__ottoport__ottoport_generate_speech, mcp__ottoport__ottoport_
 Request: $ARGUMENTS
 
 Use `ottoport_generate_music` when the request is for music, a song, or a
-backing track; otherwise use `ottoport_generate_speech` to read the text aloud.
+backing track — or for sound effects, ambience or a soundtrack for a video, with
+`model` `mirelo-sfx-2.0` (pass the video as `video_url`, and `duration` as its
+length); otherwise use `ottoport_generate_speech` to read the text aloud.
 Pass `voice` and `format` only when named — speech defaults to `gpt-4o-mini-tts`
 with the `alloy` voice, music to `suno-v5`.
 

package/mcp/server.mjs

@@ -282,9 +282,13 @@ async function waitForJob(statusPath, job, { timeoutMs, label }) {
   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();
+    try {
+      const status = await fetch(`${BASE}${path}`, { headers: headers(false), signal: AbortSignal.timeout(Math.max(1, deadline - Date.now())) });
+      if (!status.ok) throw new Error(await gwError(status));
+      job = await status.json();
+    } catch (error) {
+      return { job: { ...job, poll_error: error.message }, timedOut: true, path };
+    }
   }
   if (job.status === "failed") throw new Error(job.error || `${label} generation failed`);
   return { job, timedOut: false, path };
@@ -293,7 +297,21 @@ 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, collection, ...rest }) {
+const JOB_PATHS = { image: IMAGE_JOB_PATH, video: VIDEO_JOB_PATH, speech: "/api/v1/audio/speech/{id}", music: "/api/v1/audio/music/{id}" };
+function describeJob(kind, job) {
+  return JSON.stringify({ ...job, job_id: job.id, kind, status_path: JOB_PATHS[kind].replace("{id}", encodeURIComponent(job.id)), next: { tool: "ottoport_get_job", arguments: { kind, job_id: job.id } } }, null, 2);
+}
+async function getJob({ kind, job_id, wait = false }) {
+  if (!Object.hasOwn(JOB_PATHS, kind) || !job_id) throw new Error("Valid kind and job_id are required");
+  const path = JOB_PATHS[kind].replace("{id}", encodeURIComponent(job_id));
+  const res = await fetch(`${BASE}${path}`, { headers: headers(false) });
+  if (!res.ok) throw new Error(await gwError(res));
+  let job = await res.json();
+  if (wait) ({ job } = await waitForJob(JOB_PATHS[kind], job, { timeoutMs: 45_000, label: kind }));
+  return describeJob(kind, job);
+}
+
+async function generateImage({ prompt, model, collection, wait = false, ...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.
@@ -318,8 +336,9 @@ async function generateImage({ prompt, model, collection, ...rest }) {
   // 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.`;
+    if (!wait) return describeJob("image", json);
+    const { job, timedOut, path } = await waitForJob(IMAGE_JOB_PATH, json, { timeoutMs: 45_000, label: "image" });
+    if (timedOut) return describeJob("image", job);
     json = job;
   }
   // A layer stack prints one line per layer with what the model called it, so
@@ -330,7 +349,7 @@ async function generateImage({ prompt, model, collection, ...rest }) {
   return lines.length ? lines.join("\n") : "(no image returned)";
 }
 
-async function generateVideo({ prompt, model, webhook_url, webhook_secret, collection, ...rest }) {
+async function generateVideo({ prompt, model, webhook_url, webhook_secret, collection, wait = false, ...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");
@@ -347,14 +366,10 @@ async function generateVideo({ prompt, model, webhook_url, webhook_secret, colle
   if (!res.ok) throw new Error(await gwError(res));
   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 ${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 { 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.`;
+  // Return the accepted job before the MCP client timeout; waiting is opt-in.
+  if (!wait || webhook_url) return describeJob("video", submitted);
+  const { job, timedOut, path } = await waitForJob(VIDEO_JOB_PATH, submitted, { timeoutMs: 45_000, label: "video" });
+  if (timedOut) return describeJob("video", job);
   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.
@@ -375,22 +390,31 @@ 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, collection }) {
-  if (!prompt) throw new Error("`prompt` is required");
+async function generateAudio(kind, { prompt, model, voice, duration, format, video_url, collection, wait = false }) {
+  if (!prompt && !video_url) throw new Error("`prompt` is required");
   const res = await fetch(`${BASE}/api/v1/audio/${kind === "tts" ? "speech" : "music"}`, {
     method: "POST",
-    headers: headers(),
+    headers: { ...headers(), "idempotency-key": crypto.randomUUID() },
     body: JSON.stringify({
+      async: true,
       model: model || (kind === "tts" ? "gpt-4o-mini-tts" : "suno-v5"),
-      prompt,
+      ...(prompt ? { prompt } : {}),
       ...(voice ? { voice } : {}),
+      ...(video_url ? { video_url } : {}),
       ...(duration ? { duration } : {}),
       ...(format ? { format } : {}),
       ...withCollection(await collectionId(collection)),
     }),
   });
   if (!res.ok) throw new Error(await gwError(res));
-  const json = await res.json();
+  let json = await res.json();
+  if (res.status === 202) {
+    const jobKind = kind === "tts" ? "speech" : "music";
+    if (!wait) return describeJob(jobKind, json);
+    const result = await waitForJob(JOB_PATHS[jobKind], json, { timeoutMs: 45_000, label: jobKind });
+    if (result.timedOut) return describeJob(jobKind, result.job);
+    json = result.job;
+  }
   const audio = json.data?.[0];
   if (!audio) return "(no audio returned)";
   if (audio.url || audio.asset_url) return outputLine(audio);
@@ -399,6 +423,12 @@ async function generateAudio(kind, { prompt, model, voice, duration, format, col
 
 // ── tool registry ────────────────────────────────────────────────────
 const TOOLS = [
+  {
+    name: "ottoport_get_job",
+    description: "Read an existing image, video, speech or music job, including progress, errors and result URLs. Never resubmits or bills a new generation.",
+    inputSchema: { type: "object", properties: { kind: { type: "string", enum: ["image", "video", "speech", "music"] }, job_id: { type: "string" }, wait: { type: "boolean", description: "Optionally wait up to 45 seconds." } }, required: ["kind", "job_id"] },
+    handler: getJob,
+  },
   {
     name: "ottoport_list_models",
     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.",
@@ -429,10 +459,11 @@ const TOOLS = [
   },
   {
     name: "ottoport_generate_image",
-    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. Also layer decomposition: qwen-image-layered and seedream-5.0-layers take `image_url` alone and return the image split into RGBA layers, one URL per layer, billed per layer. Which a model accepts is in its capabilities — call ottoport_list_models. 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. Also layer decomposition: qwen-image-layered and seedream-5.0-layers take `image_url` alone and return the image split into RGBA layers, one URL per layer, billed per layer. Vectors: ideogram-vector-1 returns editable SVG from a prompt (shape it with `aspect_ratio`, not `size`), and ideogram-vector-1-vectorize takes `image_url` alone and returns it traced as SVG. Which a model accepts is in its capabilities — call ottoport_list_models. Defaults to asynchronous submission: returns job_id and polling instructions. Use ottoport_get_job for results.",
     inputSchema: {
       type: "object",
       properties: {
+        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: "What to generate. On a layer-decomposition model, an optional caption of the input image." },
         model: { type: "string", description: "Model id, e.g. gpt-image-2, nano-banana-2.1, nano-banana-pro. Default gpt-image-2." },
         size: { type: "string", description: 'Exact pixels, e.g. "1024x1024". Wins over `resolution`.' },
@@ -443,7 +474,7 @@ const TOOLS = [
         // 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.' },
-        quality: { type: "string", description: 'How much compute the model spends, on the GPT Image family and ideogram-4.5 — "low", "medium" (the default), "high", and on gpt-image-2.5 "xhigh" and "max". Priced by tier, and the ladder is steep: `max` costs sixteen times `medium`. Check the model\'s `qualities` in ottoport_list_models.' },
+        quality: { type: "string", description: 'How much compute the model spends, on the GPT Image family, ideogram-4.5 and ideogram-vector-1 — "low", "medium" (the default), "high", and on gpt-image-2.5 "xhigh" and "max". Priced by tier, and the ladder is steep: `max` costs sixteen times `medium`. Check the model\'s `qualities` in ottoport_list_models.' },
         n: { type: "number" },
         seed: { type: "number" },
         image_url: { type: "string", description: "One reference image, for editing and image-to-image — or, on a layer-decomposition model, the image to split." },
@@ -452,6 +483,10 @@ 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)." },
+        output_format: { type: "string", enum: ["gif", "svg"], description: "gpt-image-2.6 and gpt-image-2.6-flare, text-to-image only: `gif` returns an animation, `svg` a vector file. One file per request. GIF picks its own frame size, so `size`, `resolution` and `aspect_ratio` do not apply; describe the motion and the loop in the prompt. SVG costs extra — see the model's rate in ottoport_list_models." },
+        frame_count: { type: "number", description: "With output_format gif: frames, 2–16, default 8. Above 8 bills double." },
+        frame_duration_ms: { type: "number", description: "With output_format gif: milliseconds per frame, 20–2000." },
+        vector_mode: { type: "string", enum: ["default", "simple"], description: "ideogram-vector-1-vectorize only: `default` keeps finer detail, `simple` traces fewer, simpler shapes. Same price." },
         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." },
       },
     },
@@ -459,10 +494,11 @@ 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`, 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` (or the model `seedance-2.5-draft`, where every request is a draft) 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. Kling motion control (`kling-2.6-motion-control`, `kling-3.0-motion-control` and their `-pro` variants) makes the character in `image_url` perform the movement in `video_url`; the prompt is optional and the output runs as long as the clip. 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` (or the model `seedance-2.5-draft`, where every request is a draft) 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. Kling motion control (`kling-2.6-motion-control`, `kling-3.0-motion-control` and their `-pro` variants) makes the character in `image_url` perform the movement in `video_url`; the prompt is optional and the output runs as long as the clip. Which a model accepts is in its capabilities — call ottoport_list_models. Defaults to asynchronous submission. Use ottoport_get_job for results.",
     inputSchema: {
       type: "object",
       properties: {
+        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: "Required, except on video-depth-anything, which takes none, and the motion-control models, where it is optional." },
         model: { type: "string", description: "Model id, e.g. veo-3.1, kling-3.0, seedance-2.0-fast, kling-3.0-motion-control, video-depth-anything. Default kling-3.0." },
         duration: { type: "number", description: "Seconds. The main lever on what this costs." },
@@ -506,10 +542,11 @@ const TOOLS = [
   },
   {
     name: "ottoport_generate_speech",
-    description: "Convert text to speech through an OttoPort TTS model. Returns an audio URL or data URL.",
+    description: "Convert text to speech through an OttoPort TTS model. Defaults to asynchronous submission; returns job_id. Query ottoport_get_job for audio results.",
     inputSchema: {
       type: "object",
       properties: {
+        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: "Text to synthesize." },
         model: { type: "string", description: "TTS model id. Default gpt-4o-mini-tts." },
         voice: { type: "string", description: "Optional provider voice id." },
@@ -522,17 +559,18 @@ const TOOLS = [
   },
   {
     name: "ottoport_generate_music",
-    description: "Generate music from a prompt through an OttoPort music model. Returns an audio URL or data URL.",
+    description: "Generate music or sound effects from a prompt through an OttoPort music model — or, with mirelo-sfx-2.0 and a video_url, a soundtrack synced to that video. Defaults to asynchronous submission; returns job_id. Query ottoport_get_job for audio results.",
     inputSchema: {
       type: "object",
       properties: {
-        prompt: { type: "string", description: "Music-generation prompt." },
-        model: { type: "string", description: "Music model id. Default suno-v5." },
+        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-v5; mirelo-sfx-2.0 for sound effects." },
         duration: { type: "number", description: "Requested duration in seconds." },
+        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." },
       },
-      required: ["prompt"],
     },
     handler: (args) => generateAudio("music", args),
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ottoport",
-  "version": "1.13.2",
+  "version": "1.15.1",
   "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

@@ -1,6 +1,6 @@
 ---
 name: ottoport
-description: Generate text, images, video, speech, and music through OttoPort — one gateway for every model (GPT, Claude, Gemini, GPT Image, Nano Banana, Veo, Kling, Seedance, Suno). Use when the user wants to call an LLM or generate an image, video, or audio and has OttoPort configured, or asks to "use OttoPort".
+description: Generate text, images, video, speech, and music through OttoPort — one gateway for every model (GPT, Claude, Gemini, GPT Image, Nano Banana, Veo, Kling, Seedance, Suno, Mirelo). Use when the user wants to call an LLM or generate an image, video, audio or sound effects and has OttoPort configured, or asks to "use OttoPort".
 ---
 
 # OttoPort
@@ -20,7 +20,7 @@ and do not call the HTTP API, when a tool covers the job:
 | `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, or the movement for motion control), `character_orientation` / `keep_original_sound` (motion control), `draft` / `draft_id` (Seedance 2.5: a 480p preview, then the same shot at 1080p from the preview's job id; the model `seedance-2.5-draft` drafts on every request without `draft`), `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`. |
+| `ottoport_generate_music` | `prompt`, plus optional `model`, `duration`, `format`. Sound effects too: `model` `mirelo-sfx-2.0` makes them from the prompt, or with `video_url` a soundtrack synced to that video, dialogue kept (prompt then optional). It bills per requested second, so set `duration` to the clip's length. |
 | `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`. |
@@ -65,11 +65,12 @@ video and `"1k"`/`"2k"`/`"4k"` for images, but **no model offers all of it**:
 `gpt-image-1.5` only 1k. Same for how many references a model takes —
 `nano-banana-lite` accepts 3, `gpt-image-2` accepts 16.
 
-`quality` is a second priced dial, on the GPT Image family and `ideogram-4.5`:
+`quality` is a second priced dial, on the GPT Image family, `ideogram-4.5` and
+`ideogram-vector-1`:
 `low`, `medium` (the default, and the tier every catalog rate was measured at),
-`high`, and `xhigh`/`max` on `gpt-image-2.5` and `gpt-image-2.5-flare`. It buys
-compute, not pixels, and the ladder is steep — `max` bills sixteen times
-`medium`. A model's tiers are its `qualities` in `ottoport_list_models`.
+`high`, and `xhigh`/`max` on `gpt-image-2.6`, `gpt-image-2.5` and their Flare
+tiers. It buys compute, not pixels, and the ladder is steep — `max` bills
+sixteen times `medium` on 2.5 and about five times on 2.6. A model's tiers are its `qualities` in `ottoport_list_models`.
 
 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
@@ -90,7 +91,7 @@ sensible default.
 | image | `gpt-image-2` | `nano-banana-2.1` (fast generation and edits), `nano-banana-pro` (high fidelity) |
 | video | `kling-3.0` | `seedance-2.0-fast` (cheap), `veo-3.1` (with audio) |
 | speech | `gpt-4o-mini-tts` | `eleven-v3` |
-| music | `suno-v5` | `lyria-2` |
+| music | `suno-v5` | `lyria-2`, `mirelo-sfx-2.0` (sound effects, or a soundtrack for a video) |
 
 Never invent a model id. Call `ottoport_list_models` when unsure — the catalog
 changes, and a wrong id is a failed billable call. Rates come back in credits (the unit the ledger
@@ -143,3 +144,20 @@ music live under `/api/v1/images/generations`, `/videos/generations`,
 - The CLI always targets `https://ottoport.ai`; pass `--url` explicitly only
   for local development or a self-hosted gateway.
 - `OTTOPORT_BASE_URL` configures the MCP server only.
+
+
+## Asynchronous media jobs (1.15.1)
+
+Image, video, speech and music generation return an accepted job immediately by default. Save its `job_id`; do not resubmit to check progress. Chat streaming is unchanged.
+
+```sh
+ottoport image "a mountain lake" --model midjourney-v8.2
+ottoport job image <job-id>
+ottoport job image <job-id> --wait --out lake.png
+# Explicit waiting is also available on submission:
+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.
+
+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.