ottoport 1.14.0 → 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.14.0",
+  "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

@@ -95,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
@@ -150,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

@@ -26,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 = [];
@@ -267,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)) } : {}),
@@ -291,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) =>
@@ -325,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() },
@@ -335,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));
@@ -344,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) {
@@ -353,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));
   }
 }
 
@@ -400,6 +436,7 @@ async function cmdAudio(kind, prompt, flags) {
   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 } : {}),
     ...(video ? { video_url: video } : {}),
@@ -411,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));
@@ -486,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]
@@ -537,6 +580,8 @@ Examples:
   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
@@ -554,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/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,12 +390,13 @@ 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, video_url, collection }) {
+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 } : {}),
       ...(voice ? { voice } : {}),
@@ -391,7 +407,14 @@ async function generateAudio(kind, { prompt, model, voice, duration, format, vid
     }),
   });
   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);
@@ -400,6 +423,12 @@ async function generateAudio(kind, { prompt, model, voice, duration, format, vid
 
 // ── 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.",
@@ -430,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`.' },
@@ -444,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." },
@@ -453,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." },
       },
     },
@@ -460,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." },
@@ -507,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." },
@@ -523,10 +559,11 @@ const TOOLS = [
   },
   {
     name: "ottoport_generate_music",
-    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. 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: {
+        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." },

package/package.json

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

@@ -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
@@ -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.