@aaronjmars/openroutercli 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -73,7 +73,7 @@ and run `openrouter login --management`.
73
73
  | **OAuth PKCE login** | `openrouter login` opens the browser, catches the callback locally, exchanges the code, and stores the key - `0600` perms in `~/.config/openrouter/`. No paste-an-API-key dance. |
74
74
  | **Two-slot key management** | User key + management/provisioning key live in separate slots. `keys`, `byok`, `guardrails`, `workspaces`, `observability`, `activity` auto-pick the management key; everything else uses the user key. `--key` always wins. |
75
75
  | **Streaming + JSON modes** | Streams in a TTY, switches to JSON when piped or `--json` is set. No global flag plumbing - works on every command. |
76
- | **Chat with everything** | Tool calls (`--tool @file.json --tool-choice required`), server tools (`--server-tool web_search`), deferred tool loading, structured output (`--schema schema.json`), JSON mode, multimodal images (`--image url\|path`), image output (`--modalities text,image`), reasoning effort, automatic prompt caching (`--cache --cache-ttl 1h`), alignment rules (`--rule`), provider routing, fallback models, service tiers, sessions and traces, full sampling controls. |
76
+ | **Chat with everything** | Tool calls (`--tool @file.json --tool-choice required`), server tools (`--server-tool web_search`), deferred tool loading, structured output (`--schema schema.json`), JSON mode, multimodal images (`--image url\|path`), image output (`--modalities text,image`), reasoning effort, automatic prompt caching (`--cache --cache-ttl 1h`) and OpenAI explicit caching (`--cache-ttl 30m|12h`), alignment rules (`--rule`), provider routing, fallback models, service tiers, sessions and traces, full sampling controls. |
77
77
  | **Interactive REPL** | `openrouter chat -i` - slash commands `/model <id>`, `/reset`, `/exit`. History preserved per session. |
78
78
  | **Multi-format inference** | `chat` (OpenAI), `messages` (Anthropic), `responses` (OpenAI Responses) - same auth, same flags, same JSON contract. |
79
79
  | **Batches** | `batches {create,list,get,wait,results,delete}` - send a JSONL file of chat / responses / messages / embeddings requests as one async job at about half price. |
@@ -132,15 +132,15 @@ openrouter tools list
132
132
  openrouter chat "What's new today?" -m openai/gpt-4o-mini --server-tool web_search
133
133
 
134
134
  # Batches at about half price
135
- openrouter batches create --endpoint chat -m openai/gpt-4o-mini --file reqs.jsonl
135
+ openrouter batches create --endpoint chat -m openai/gpt-4o-mini --file reqs.jsonl --callback-url https://example.com/webhook
136
136
  openrouter batches wait <id> && openrouter batches results <id> -o out.jsonl
137
137
 
138
138
  # Discovery
139
139
  openrouter models --filter claude --sort prompt
140
+ openrouter models user --order newest
140
141
  openrouter models show anthropic/claude-sonnet-4.5
141
142
  openrouter models endpoints anthropic/claude-sonnet-4.5 --sort throughput --best
142
143
  openrouter providers
143
-
144
144
  # Spend / runs
145
145
  openrouter credits
146
146
  openrouter whoami
package/SKILL.md CHANGED
@@ -163,6 +163,9 @@ openrouter chat "summarize this" -m google/gemini-2.5-flash --file ./report.pdf
163
163
  # Prompt caching: automatic (top-level cache_control, optional 1h TTL) or explicit breakpoints
164
164
  openrouter chat "answer from the doc" -m anthropic/claude-sonnet-4.5 -s "$(cat big-context.txt)" --cache --cache-ttl 1h
165
165
  openrouter chat "answer from the doc" -m anthropic/claude-sonnet-4.5 -s "$(cat big-context.txt)" --cache-system
166
+ # OpenAI explicit caching (GPT-5.6+): 30m or 12h TTL, marks the system prompt (else the prompt);
167
+ # works on chat and responses, 12h writes bill at a higher rate
168
+ openrouter chat "answer from the doc" -m openai/gpt-5.6 -s "$(cat big-context.txt)" --cache-ttl 12h
166
169
 
167
170
  # Tracing, sessions, priority: works on chat / messages / responses
168
171
  openrouter chat "..." -m openai/gpt-4o-mini --session-id run-42 --user u_123 \
@@ -191,11 +194,11 @@ openrouter chat -i -m openrouter/auto
191
194
  openrouter messages "..." -m anthropic/claude-sonnet-4.5 --thinking-budget 2000
192
195
  openrouter messages "..." -m anthropic/claude-sonnet-4.5 --thinking adaptive --effort high --speed fast
193
196
  openrouter messages "..." -m anthropic/claude-sonnet-4.5 --provider '{"order":["Anthropic"]}' --plugins @plugins.json
194
- openrouter responses "..." -m openai/gpt-4o-mini --store --include reasoning.encrypted_content
197
+ openrouter responses "..." -m openai/gpt-4o-mini --stop "END,STOP" --store --include reasoning.encrypted_content
195
198
  openrouter responses "..." -m openai/gpt-5-mini --verbosity low --truncation auto
196
199
 
197
200
  # Batches: async jobs at ~half price (chat, responses, messages, embeddings)
198
- openrouter batches create --endpoint chat -m openai/gpt-4o-mini --file reqs.jsonl # {custom_id, body} per line
201
+ openrouter batches create --endpoint chat -m openai/gpt-4o-mini --file reqs.jsonl --callback-url https://example.com/webhook # {custom_id, body} per line
199
202
  openrouter batches wait <id> && openrouter batches results <id> -o out.jsonl
200
203
 
201
204
  # Embeddings (text or images), rerank
@@ -203,7 +206,7 @@ openrouter embed -m openai/text-embedding-3-small "hello" "world"
203
206
  openrouter embed -m <multimodal-embed-model> "a cat" --image ./cat.png
204
207
  openrouter rerank -m cohere/rerank-v3.5 --query "italian food" -d pizza -d sushi -d pasta
205
208
 
206
- # Text to speech (mp3 by default; pcm also allowed): tone, multi-speaker, voice cloning
209
+ # Text to speech (mp3 by default, pcm for HeyGen Voice + Gemini TTS which only return pcm): tone, multi-speaker, voice cloning
207
210
  openrouter speech "Hello there" -m elevenlabs/eleven-v4 --voice <voice> -o out.mp3
208
211
  openrouter speech "Welcome back" -m openai/gpt-4o-mini-tts --voice alloy --instructions "warm, slow"
209
212
  openrouter speech -m google/gemini-2.5-flash-preview-tts --turns @dialogue.json # [{text, voice}]
@@ -235,8 +238,8 @@ openrouter models --order intelligence-high-to-low # server-side ranking
235
238
  openrouter models --free # only :free models
236
239
  openrouter models --input-modalities image # image-INPUT (vision) models
237
240
  openrouter models --output-modalities image # image-OUTPUT models
241
+ openrouter models user --order newest # account-filtered models, server-side sort
238
242
  openrouter models --supported tools # filter by capability
239
-
240
243
  # Full detail for one model: pricing breakdown, architecture, supported params,
241
244
  # reasoning config, supported voices
242
245
  openrouter models show anthropic/claude-sonnet-4.5
@@ -311,8 +314,8 @@ openrouter guardrails list
311
314
  openrouter guardrails create "no-paid-models" --allowed-providers "" --enforce-zdr
312
315
  openrouter guardrails update <id> --limit-usd 10 --reset-interval daily --include-byok
313
316
  openrouter guardrails update <id> --regions europe --builtin-filters email:redact,secrets:block --no-paid-training
317
+ openrouter guardrails update <id> --allow-safety-retention-google --no-allow-safety-retention-other
314
318
  openrouter guardrails assign-key <id> <key-hash> # up to 500 hashes per call
315
- openrouter guardrails delete <id>
316
319
 
317
320
  openrouter workspaces list
318
321
  openrouter workspaces create "staging" --slug staging --default-text-model openai/gpt-4o-mini
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aaronjmars/openroutercli",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
4
4
  "description": "Command-line interface for the OpenRouter API. Built for humans and LLM agents.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -30,6 +30,7 @@ create options:
30
30
  (a line without "body" is used as the body itself and
31
31
  gets custom_id req-<n>). Reads stdin when omitted.
32
32
  --completion-window <w> Default: 24h
33
+ --callback-url <url> Webhook URL called on terminal status events
33
34
  --provider <json|@file> Routing: {"only": [...], "allow_fallbacks": false}
34
35
  --only <csv> Shortcut for provider.only
35
36
  --no-fallbacks Shortcut for provider.allow_fallbacks = false
@@ -228,6 +229,7 @@ export async function batchesCommand(argv) {
228
229
  endpoint: { type: "string" },
229
230
  file: { type: "string" },
230
231
  "completion-window": { type: "string" },
232
+ "callback-url": { type: "string" },
231
233
  provider: { type: "string" },
232
234
  only: { type: "string" },
233
235
  "no-fallbacks": { type: "boolean" },
@@ -257,8 +259,8 @@ export async function batchesCommand(argv) {
257
259
  const body = { endpoint: resolveEndpoint(values.endpoint), model: values.model };
258
260
  if (provider) body.provider = provider;
259
261
  if (values["completion-window"]) body.completion_window = values["completion-window"];
262
+ if (values["callback-url"]) body.callback_url = values["callback-url"];
260
263
  body.requests = requests;
261
-
262
264
  const data = await api("POST", "/batches", { auth: authFromValues(values), body });
263
265
  printBatch(data);
264
266
  info(`Submitted ${requests.length} request(s). Next: openrouter batches wait ${data.id}`);
@@ -42,7 +42,9 @@ export const SERVER_TOOL_HELP = ` --server-tool <name>[=<json|@file>] Open
42
42
  `;
43
43
 
44
44
  export const CACHE_HELP = ` --cache Automatic prompt caching (top-level cache_control)
45
- --cache-ttl <ttl> 5m | 1h (implies --cache)
45
+ --cache-ttl <ttl> 5m | 1h (implies --cache). chat/responses also take
46
+ 30m | 12h: OpenAI explicit prompt_cache_options
47
+ (GPT-5.6+; 12h writes bill higher)
46
48
  `;
47
49
 
48
50
  export const ALIGNMENT_HELP = ` --rule <text> Alignment plugin rule (repeatable, max 128, <=200 chars,
@@ -80,11 +82,25 @@ export async function applyToolExtras(body, values) {
80
82
  }
81
83
  }
82
84
 
83
- export function applyCache(body, values) {
84
- if (!values.cache && !values["cache-ttl"]) return;
85
+ const EXPLICIT_CACHE_TTLS = ["30m", "12h"];
86
+
87
+ // 5m | 1h: top-level cache_control (Anthropic style). 30m | 12h: OpenAI
88
+ // explicit prompt_cache_options, which only caches blocks marked with
89
+ // prompt_cache_breakpoint, so the caller must mark one. Returns true for the
90
+ // explicit form. `explicit` = the endpoint accepts it (chat, responses).
91
+ export function applyCache(body, values, { explicit = false } = {}) {
92
+ if (!values.cache && !values["cache-ttl"]) return false;
85
93
  const ttl = values["cache-ttl"];
86
- if (ttl && ttl !== "5m" && ttl !== "1h") throw new Error(`--cache-ttl must be 5m or 1h`);
94
+ if (EXPLICIT_CACHE_TTLS.includes(ttl)) {
95
+ if (!explicit) throw new Error("--cache-ttl 30m|12h works with chat and responses only");
96
+ body.prompt_cache_options = { mode: "explicit", ttl };
97
+ return true;
98
+ }
99
+ if (ttl && ttl !== "5m" && ttl !== "1h") {
100
+ throw new Error(`--cache-ttl must be ${explicit ? "5m, 1h, 30m or 12h" : "5m or 1h"}`);
101
+ }
87
102
  body.cache_control = { type: "ephemeral", ...(ttl ? { ttl } : {}) };
103
+ return false;
88
104
  }
89
105
 
90
106
  // Adds the alignment plugin from --rule/--alignment-*. An alignment entry
@@ -355,15 +371,18 @@ async function buildPlugins(values) {
355
371
  return addAlignmentPlugin(list, values);
356
372
  }
357
373
 
358
- // Wrap a string into a single text content part so a cache_control breakpoint
359
- // can be attached; content already in part form is returned untouched.
360
- function markCache(content) {
361
- if (typeof content === "string") {
362
- return [{ type: "text", text: content, cache_control: { type: "ephemeral" } }];
363
- }
374
+ // Wrap a string into a single text content part so a cache breakpoint can be
375
+ // attached; content already in part form gets it on its last part. Explicit
376
+ // mode uses prompt_cache_breakpoint, which only text parts accept.
377
+ function markCache(content, explicit) {
378
+ const mark = explicit
379
+ ? { prompt_cache_breakpoint: { mode: "explicit" } }
380
+ : { cache_control: { type: "ephemeral" } };
381
+ if (typeof content === "string") return [{ type: "text", text: content, ...mark }];
364
382
  if (Array.isArray(content) && content.length) {
365
383
  const parts = content.map((p) => ({ ...p }));
366
- parts[parts.length - 1].cache_control = { type: "ephemeral" };
384
+ const i = explicit ? parts.findLastIndex((p) => p.type === "text") : parts.length - 1;
385
+ if (i !== -1) Object.assign(parts[i], mark);
367
386
  return parts;
368
387
  }
369
388
  return content;
@@ -427,22 +446,23 @@ async function applyRequestOptions(body, values) {
427
446
  }
428
447
  if (values["prompt-cache-key"]) body.prompt_cache_key = values["prompt-cache-key"];
429
448
  if (values.metadata) body.metadata = await loadJsonOrFile(values.metadata, "--metadata");
430
- applyCache(body, values);
449
+ const explicit = applyCache(body, values, { explicit: true });
431
450
  await applyRequestFields(body, values);
432
451
 
433
452
  const plugins = await buildPlugins(values);
434
453
  if (plugins.length) body.plugins = plugins;
435
454
 
436
- // cache_control breakpoints are attached to message content, so this must
437
- // run after the messages are assembled.
438
- if (values["cache-system"]) {
439
- const sys = body.messages.find((m) => m.role === "system");
440
- if (sys) sys.content = markCache(sys.content);
441
- }
442
- if (values["cache-user"]) {
455
+ // Cache breakpoints are attached to message content, so this must run after
456
+ // the messages are assembled. Explicit mode caches nothing unmarked, so with
457
+ // no --cache-system/--cache-user it marks the system prompt, else the prompt.
458
+ const sys = body.messages.find((m) => m.role === "system");
459
+ const markSystem = values["cache-system"] || (explicit && !values["cache-user"] && sys);
460
+ const markUser = values["cache-user"] || (explicit && !values["cache-system"] && !sys);
461
+ if (markSystem && sys) sys.content = markCache(sys.content, explicit);
462
+ if (markUser) {
443
463
  for (let i = body.messages.length - 1; i >= 0; i--) {
444
464
  if (body.messages[i].role === "user") {
445
- body.messages[i].content = markCache(body.messages[i].content);
465
+ body.messages[i].content = markCache(body.messages[i].content, explicit);
446
466
  break;
447
467
  }
448
468
  }
@@ -53,6 +53,10 @@ create / update options:
53
53
  --free-publication / --no-free-publication Allow free endpoints that publish prompts
54
54
  --free-training / --no-free-training Allow free endpoints that train on data
55
55
  --paid-training / --no-paid-training Allow paid endpoints that train on data
56
+ --allow-safety-retention-google / --no-allow-safety-retention-google
57
+ Allow ZDR requests to google/* to use endpoints that retain for safety
58
+ --allow-safety-retention-other / --no-allow-safety-retention-other
59
+ Allow ZDR requests to other models to use endpoints that retain for safety
56
60
  --include-byok / --no-include-byok Count BYOK spend toward the budget
57
61
  --workspace <uuid> (create only)
58
62
  --extra <json|@file> Extra body fields, merged last (e.g. enforce_zdr_xai:false)
@@ -60,7 +64,7 @@ create / update options:
60
64
 
61
65
  const ZDR_PROVIDERS = ["anthropic", "openai", "google", "xai", "other"];
62
66
  const REGIONS = ["global", "europe", "us"];
63
- const MAX_KEY_HASHES = 500;
67
+ const MAX_BULK_IDS = 500;
64
68
 
65
69
  function toggle(values, on, off) {
66
70
  if (values[on] && values[off]) throw new Error(`Pass only one of --${on} or --${off}.`);
@@ -145,6 +149,8 @@ async function buildBody(values) {
145
149
  ["enable_free_model_publication", "free-publication"],
146
150
  ["enable_free_model_training", "free-training"],
147
151
  ["enable_paid_model_training", "paid-training"],
152
+ ["allow_safety_retention_google", "allow-safety-retention-google"],
153
+ ["allow_safety_retention_other", "allow-safety-retention-other"],
148
154
  ];
149
155
  for (const [field, flag] of toggles) {
150
156
  const v = toggle(values, flag, `no-${flag}`);
@@ -182,6 +188,10 @@ const COMMON_FIELDS = {
182
188
  "no-free-training": { type: "boolean" },
183
189
  "paid-training": { type: "boolean" },
184
190
  "no-paid-training": { type: "boolean" },
191
+ "allow-safety-retention-google": { type: "boolean" },
192
+ "no-allow-safety-retention-google": { type: "boolean" },
193
+ "allow-safety-retention-other": { type: "boolean" },
194
+ "no-allow-safety-retention-other": { type: "boolean" },
185
195
  extra: { type: "string" },
186
196
  };
187
197
 
@@ -329,9 +339,9 @@ export async function guardrailsCommand(argv) {
329
339
  if (positionals.length < 2) throw new Error("Usage: <id> <hash>...");
330
340
  const id = positionals[0];
331
341
  const hashes = positionals.slice(1);
332
- if (hashes.length > MAX_KEY_HASHES) {
342
+ if (hashes.length > MAX_BULK_IDS) {
333
343
  throw new Error(
334
- `Too many key hashes (${hashes.length}); the API takes at most ${MAX_KEY_HASHES} per call. Split into batches.`,
344
+ `Too many key hashes (${hashes.length}); the API takes at most ${MAX_BULK_IDS} per call. Split into batches.`,
335
345
  );
336
346
  }
337
347
  const path =
@@ -352,6 +362,11 @@ export async function guardrailsCommand(argv) {
352
362
  if (positionals.length < 2) throw new Error("Usage: <id> <user_id>...");
353
363
  const id = positionals[0];
354
364
  const userIds = positionals.slice(1);
365
+ if (userIds.length > MAX_BULK_IDS) {
366
+ throw new Error(
367
+ `Too many user ids (${userIds.length}); the API takes at most ${MAX_BULK_IDS} per call. Split into batches.`,
368
+ );
369
+ }
355
370
  const path =
356
371
  sub === "assign-member"
357
372
  ? `/guardrails/${encodeURIComponent(id)}/assignments/members`
@@ -71,8 +71,8 @@ Options:
71
71
  --temperature <n>
72
72
  --top-p <n>
73
73
  --seed <n>
74
+ --stop <text> Stop sequence (repeatable via comma, max 4)
74
75
  --reasoning <effort> none|minimal|low|medium|high|xhigh|max
75
- --verbosity <v> low | medium | high | xhigh | max (text.verbosity)
76
76
  --truncation <t> auto | disabled
77
77
  --models <csv> Fallback models
78
78
  --provider <json|@file> Provider routing (order, only, sort, ...;
@@ -308,9 +308,9 @@ export async function responsesCommand(argv) {
308
308
  temperature: { type: "string" },
309
309
  "top-p": { type: "string" },
310
310
  seed: { type: "string" },
311
+ stop: { type: "string" },
311
312
  reasoning: { type: "string" },
312
313
  models: { type: "string" },
313
- provider: { type: "string" },
314
314
  plugins: { type: "string" },
315
315
  metadata: { type: "string" },
316
316
  "parallel-tools": { type: "boolean" },
@@ -349,8 +349,8 @@ export async function responsesCommand(argv) {
349
349
  "top-p": "top_p",
350
350
  seed: "seed",
351
351
  });
352
+ if (values.stop) body.stop = values.stop.includes(",") ? values.stop.split(",") : values.stop;
352
353
  if (values.reasoning) body.reasoning = { effort: values.reasoning };
353
- if (values.verbosity) body.text = { verbosity: values.verbosity };
354
354
  if (values.truncation) body.truncation = values.truncation;
355
355
  if (values.models) body.models = csv(values.models);
356
356
  if (values.provider) body.provider = await loadJson(values.provider, "--provider");
@@ -374,7 +374,22 @@ export async function responsesCommand(argv) {
374
374
  if (values.background) body.background = true;
375
375
  if (values["prompt-cache-key"]) body.prompt_cache_key = values["prompt-cache-key"];
376
376
  if (values["safety-identifier"]) body.safety_identifier = values["safety-identifier"];
377
- applyCache(body, values);
377
+ // Explicit mode caches only marked blocks: mark the prompt, which caches
378
+ // the instructions before it too.
379
+ if (applyCache(body, values, { explicit: true }) && typeof body.input === "string") {
380
+ body.input = [
381
+ {
382
+ role: "user",
383
+ content: [
384
+ {
385
+ type: "input_text",
386
+ text: body.input,
387
+ prompt_cache_breakpoint: { mode: "explicit" },
388
+ },
389
+ ],
390
+ },
391
+ ];
392
+ }
378
393
  await applyRequestFields(body, values);
379
394
  if (values.extra) Object.assign(body, await loadJson(values.extra, "--extra"));
380
395
  }
@@ -424,13 +424,15 @@ export async function modelsCommand(argv) {
424
424
  parsed = parseArgs(rest, {
425
425
  ...PAGINATION_OPTIONS,
426
426
  "output-modalities": { type: "string" },
427
+ order: { type: "string" },
428
+ sort: { type: "string" },
427
429
  });
428
430
  } catch (err) {
429
431
  // `models user` used to forward every list filter; the endpoint only
430
- // takes these three, so say so instead of a bare "Unknown option".
432
+ // takes these, so say so instead of a bare "Unknown option".
431
433
  if (err.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
432
434
  throw new Error(
433
- `${err.message.split(".")[0]}. models user only supports --output-modalities, --limit and --offset; use \`openrouter models list\` for search filters.`,
435
+ `${err.message.split(".")[0]}. models user only supports --output-modalities, --order/--sort, --limit and --offset; use \`openrouter models list\` for search filters.`,
434
436
  );
435
437
  }
436
438
  throw err;
@@ -438,13 +440,20 @@ export async function modelsCommand(argv) {
438
440
  const { values } = parsed;
439
441
  if (values.help) {
440
442
  process.stdout.write(
441
- "Usage: openrouter models user [--output-modalities <csv>] [--limit <n>] [--offset <n>]\n\n" +
443
+ "Usage: openrouter models user [options]\n\n" +
442
444
  "List models filtered by your provider preferences, privacy settings, and\n" +
443
445
  "guardrails. Uses your API key; on a regional host (eu/us) only models that\n" +
444
446
  "can route in-region are returned.\n\n" +
445
447
  "Options:\n" +
446
448
  " --output-modalities <csv> text,image,embeddings,audio,video,rerank,decisions,\n" +
447
449
  ' speech,transcription (or "all"). Default: text\n' +
450
+ " --order <sort> Server-side sort: most-popular|newest|top-weekly|\n" +
451
+ " pricing-low-to-high|pricing-high-to-low|\n" +
452
+ " context-high-to-low|throughput-high-to-low|\n" +
453
+ " latency-low-to-high|intelligence-high-to-low|\n" +
454
+ " coding-high-to-low|agentic-high-to-low|\n" +
455
+ " design-arena-elo-high-to-low\n" +
456
+ " --sort <sort> Alias for --order\n" +
448
457
  " --limit <n> Max rows (1-1000). Omit limit and offset for all\n" +
449
458
  " --offset <n> Rows to skip\n",
450
459
  );
@@ -452,6 +461,7 @@ export async function modelsCommand(argv) {
452
461
  }
453
462
  const query = paginationQuery(values);
454
463
  if (values["output-modalities"]) query.output_modalities = values["output-modalities"];
464
+ if (values.order || values.sort) query.sort = values.order || values.sort;
455
465
  const data = await api("GET", "/models/user", {
456
466
  auth: authFromValues(values),
457
467
  query,
@@ -26,7 +26,8 @@ Options:
26
26
  or one image (.png/.jpg/.webp) for voice design.
27
27
  Local files are sent as data URLs.
28
28
  --ref-text <t> Transcript of a --ref clip (repeatable, in --ref order)
29
- --format <fmt> mp3 | pcm (default: mp3; pcm is raw 16-bit audio)
29
+ --format <fmt> mp3 | pcm (default: mp3, or pcm for HeyGen Voice and
30
+ Gemini TTS, which only return pcm; pcm is raw 16-bit audio)
30
31
  --speed <n> Speech speed (e.g. 1.0)
31
32
  -o, --out <file> Output audio file (default: out.mp3 / out.pcm, or stdout if -)
32
33
  --provider <json|@file> Routing and provider options, e.g.
@@ -86,8 +87,10 @@ export async function speechCommand(argv) {
86
87
  input = text;
87
88
  }
88
89
 
89
- // The API defaults to raw PCM; ask for mp3 so the default out.mp3 plays.
90
- const format = values.format || "mp3";
90
+ // The API defaults to raw PCM; ask for mp3 so the default out.mp3 plays,
91
+ // except on HeyGen Voice and Gemini TTS, which return only pcm (400 on mp3).
92
+ const pcmOnly = /^heygen\//.test(values.model) || /^google\/.*-tts\b/.test(values.model);
93
+ const format = values.format || (pcmOnly ? "pcm" : "mp3");
91
94
  const body = { model: values.model, input, response_format: format };
92
95
  if (values.voice) body.voice = values.voice;
93
96
  if (values.instructions) body.instructions = values.instructions;