@aaronjmars/openroutercli 0.3.0 → 0.4.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.
@@ -1,5 +1,15 @@
1
- import { parseArgs, authFromValues, numberOption, readStdinIfPiped } from "../args.js";
1
+ import {
2
+ parseArgs,
3
+ authFromValues,
4
+ numberOption,
5
+ readStdinIfPiped,
6
+ loadJson,
7
+ applyRequestFields,
8
+ MEDIA_FIELD_HELP,
9
+ MEDIA_FIELD_OPTIONS,
10
+ } from "../args.js";
2
11
  import { api } from "../api.js";
12
+ import { mediaUrl } from "../media.js";
3
13
  import { outln, pricePerMillion, printResult, table } from "../output.js";
4
14
 
5
15
  const HELP = `Usage: openrouter embed [text...] [options]
@@ -10,11 +20,14 @@ Generate embeddings, or list embedding models.
10
20
  Options:
11
21
  -m, --model <id> Embedding model id (required for inference)
12
22
  -i, --input <text> Input string (repeatable)
13
- --input-type <t> e.g. query | document
23
+ --image <url|path> Image to embed (repeatable, multimodal models); each is
24
+ its own input. Local files are sent as data URLs.
25
+ --input-type <t> e.g. search_query | search_document
14
26
  --dimensions <n>
15
27
  --encoding <fmt> float | base64
16
- --provider <json> Provider routing as JSON
17
- `;
28
+ --provider <json|@file> Provider routing as JSON
29
+ --extra <json|@file> Extra fields merged into the body (last)
30
+ ${MEDIA_FIELD_HELP}`;
18
31
 
19
32
  export async function embedCommand(argv) {
20
33
  if (argv[0] === "models") {
@@ -47,8 +60,11 @@ export async function embedCommand(argv) {
47
60
  input: { type: "string", short: "i", multiple: true },
48
61
  "input-type": { type: "string" },
49
62
  dimensions: { type: "string" },
63
+ image: { type: "string", multiple: true },
50
64
  encoding: { type: "string" },
51
65
  provider: { type: "string" },
66
+ extra: { type: "string" },
67
+ ...MEDIA_FIELD_OPTIONS,
52
68
  });
53
69
  if (values.help) {
54
70
  process.stdout.write(HELP);
@@ -59,16 +75,25 @@ export async function embedCommand(argv) {
59
75
  const inputs = [...(values.input || []), ...positionals];
60
76
  const piped = await readStdinIfPiped();
61
77
  if (piped) inputs.push(piped);
62
- if (!inputs.length) throw new Error("No input. Pass text, use --input, or pipe stdin.");
78
+ const images = values.image || [];
79
+ if (!inputs.length && !images.length)
80
+ throw new Error("No input. Pass text, use --input or --image, or pipe stdin.");
63
81
 
64
- const body = {
65
- model: values.model,
66
- input: inputs.length === 1 ? inputs[0] : inputs,
67
- };
82
+ let input = inputs.length === 1 ? inputs[0] : inputs;
83
+ if (images.length) {
84
+ // Multimodal form: one { content: [part] } item per text or image.
85
+ input = inputs.map((text) => ({ content: [{ type: "text", text }] }));
86
+ for (const img of images) {
87
+ input.push({ content: [{ type: "image_url", image_url: { url: await mediaUrl(img) } }] });
88
+ }
89
+ }
90
+ const body = { model: values.model, input };
68
91
  if (values["input-type"]) body.input_type = values["input-type"];
69
92
  if (values.dimensions) body.dimensions = numberOption(values.dimensions, "--dimensions");
70
93
  if (values.encoding) body.encoding_format = values.encoding;
71
- if (values.provider) body.provider = JSON.parse(values.provider);
94
+ if (values.provider) body.provider = await loadJson(values.provider, "--provider");
95
+ await applyRequestFields(body, values);
96
+ if (values.extra) Object.assign(body, await loadJson(values.extra, "--extra"));
72
97
 
73
98
  const data = await api("POST", "/embeddings", {
74
99
  auth: authFromValues(values),
@@ -7,16 +7,28 @@ const HELP = `Usage: openrouter files <subcommand> [options]
7
7
  Manage files stored on OpenRouter (backing store for file/PDF inputs).
8
8
 
9
9
  Subcommands:
10
- list List uploaded files
10
+ list [options] List uploaded files
11
11
  get <id> Get one file's metadata
12
12
  upload <path> [options] Upload a file (multipart)
13
13
  download <id> [-o file] Download file content
14
14
  delete <id> Delete a file
15
15
 
16
+ Every subcommand takes:
17
+ --workspace <id> Workspace UUID (defaults to the key's default workspace)
18
+ --provider <slug> Store/read on your own provider account: openai | anthropic
19
+ (uses your BYOK key; omit for OpenRouter storage)
20
+
16
21
  upload options:
17
- --purpose <p> Purpose tag for the file (e.g. assistants, user_data)
18
- --workspace <id> Workspace UUID (defaults to the key's workspace)
19
- --provider <slug> Store/read via a BYOK provider
22
+ --purpose <p> Ignored: the API no longer takes a purpose (kept so old
23
+ scripts still run)
24
+
25
+ list options:
26
+ --limit <n> Max files (1-1000)
27
+ --cursor <c> Cursor from a previous page
28
+ --after <id> OpenAI-style: list after this id
29
+ --after-id <id> Anthropic-style: list after this id
30
+ --before-id <id> Anthropic-style reverse cursor (not on OpenRouter storage)
31
+ --order <o> asc (only asc on OpenRouter storage)
20
32
  `;
21
33
 
22
34
  const FILE_SCOPE = {
@@ -53,7 +65,7 @@ export async function filesCommand(argv) {
53
65
  "before-id": { type: "string" },
54
66
  order: { type: "string" },
55
67
  });
56
- const query = scopeQuery(values);
68
+ const query = scopeQuery(values) || {};
57
69
  if (values.limit !== undefined) query.limit = numberOption(values.limit, "--limit");
58
70
  if (values.cursor) query.cursor = values.cursor;
59
71
  if (values.after) query.after = values.after;
@@ -66,9 +78,13 @@ export async function filesCommand(argv) {
66
78
  table(rows, [
67
79
  { label: "id", value: (f) => f.id || "" },
68
80
  { label: "filename", value: (f) => f.filename || f.name || "" },
69
- { label: "bytes", value: (f) => f.bytes ?? f.size ?? "" },
70
- { label: "purpose", value: (f) => f.purpose || "" },
81
+ { label: "bytes", value: (f) => f.size_bytes ?? f.bytes ?? f.size ?? "" },
82
+ { label: "type", value: (f) => f.mime_type || f.purpose || "" },
83
+ { label: "created", value: (f) => f.created_at || "" },
71
84
  ]);
85
+ if (data.has_more) {
86
+ outln(data.cursor ? `more: --cursor ${data.cursor}` : `more: --after ${data.last_id}`);
87
+ }
72
88
  });
73
89
  return 0;
74
90
  }
@@ -96,7 +112,7 @@ export async function filesCommand(argv) {
96
112
  const filename = path.split("/").pop() || "file";
97
113
  const form = new FormData();
98
114
  form.append("file", new Blob([buf]), filename);
99
- if (values.purpose) form.append("purpose", values.purpose);
115
+ // --purpose is still accepted but not sent: the multipart body is file only.
100
116
  const data = await api("POST", "/files", {
101
117
  auth: authFromValues(values),
102
118
  body: form,
@@ -1,23 +1,92 @@
1
1
  import { parseArgs, authFromValues } from "../args.js";
2
- import { api } from "../api.js";
3
- import { c, outln, printResult } from "../output.js";
2
+ import { api, APIError } from "../api.js";
3
+ import { c, info, outln, printResult } from "../output.js";
4
+
5
+ const HELP = `Usage: openrouter generation <id> [--content]
6
+ openrouter generation feedback <id> --category <c> [--comment <text>]
7
+
8
+ Fetch metadata for a generation. With --content, fetch the input/output content.
9
+ A generation can take a few seconds to show up; a 404 is retried once.
10
+
11
+ feedback: report a problem with a generation.
12
+ --category <c> latency | incoherence | incorrect_response | formatting |
13
+ billing | api_error | other
14
+ --comment <text> Optional detail (max 1000 chars)
15
+ `;
16
+
17
+ const ID_RE = /^gen-[0-9A-Za-z-]+$/;
18
+ const CATEGORIES = [
19
+ "latency",
20
+ "incoherence",
21
+ "incorrect_response",
22
+ "formatting",
23
+ "billing",
24
+ "api_error",
25
+ "other",
26
+ ];
27
+
28
+ function checkId(id) {
29
+ if (!ID_RE.test(id) || id.length > 128) {
30
+ throw new Error(`Invalid generation id: "${id}" (expected gen-..., letters, digits and -)`);
31
+ }
32
+ }
33
+
34
+ function sleep(ms) {
35
+ return new Promise((r) => setTimeout(r, ms));
36
+ }
37
+
38
+ async function feedbackCommand(argv) {
39
+ const { values, positionals } = parseArgs(argv, {
40
+ category: { type: "string" },
41
+ comment: { type: "string" },
42
+ });
43
+ if (values.help) {
44
+ process.stdout.write(HELP);
45
+ return 0;
46
+ }
47
+ const id = positionals[0];
48
+ if (!id) throw new Error("generation id required");
49
+ checkId(id);
50
+ if (!values.category) throw new Error(`--category is required (${CATEGORIES.join(", ")})`);
51
+ if (!CATEGORIES.includes(values.category)) {
52
+ throw new Error(`Invalid --category: ${values.category} (use ${CATEGORIES.join(", ")})`);
53
+ }
54
+ if (values.comment !== undefined && values.comment.length > 1000) {
55
+ throw new Error("--comment is longer than 1000 characters");
56
+ }
57
+ const body = { generation_id: id, category: values.category };
58
+ if (values.comment !== undefined) body.comment = values.comment;
59
+ const data = await api("POST", "/generation/feedback", {
60
+ auth: authFromValues(values),
61
+ body,
62
+ });
63
+ printResult(data, () => outln(`feedback recorded for ${id}`));
64
+ return 0;
65
+ }
4
66
 
5
67
  export async function generationCommand(argv) {
68
+ if (argv[0] === "feedback") return feedbackCommand(argv.slice(1));
6
69
  const { values, positionals } = parseArgs(argv, {
7
70
  content: { type: "boolean" },
8
71
  });
9
72
  if (values.help || !positionals[0]) {
10
- process.stdout.write(
11
- "Usage: openrouter generation <id> [--content]\n\nFetch metadata for a generation. With --content, fetch the input/output content.\n",
12
- );
73
+ process.stdout.write(HELP);
13
74
  return values.help ? 0 : 1;
14
75
  }
15
76
  const id = positionals[0];
77
+ checkId(id);
16
78
  const path = values.content ? "/generation/content" : "/generation";
17
- const data = await api("GET", path, {
18
- auth: authFromValues(values),
19
- query: { id },
20
- });
79
+ const fetchIt = () => api("GET", path, { auth: authFromValues(values), query: { id } });
80
+ let data;
81
+ try {
82
+ data = await fetchIt();
83
+ } catch (err) {
84
+ // Stats land a moment after the response, so a fresh id can 404 briefly.
85
+ if (!(err instanceof APIError) || err.status !== 404) throw err;
86
+ info("not found yet, retrying in 2s...");
87
+ await sleep(2000);
88
+ data = await fetchIt();
89
+ }
21
90
  printResult(data, () => {
22
91
  const d = data.data || data;
23
92
  outln(c.bold(`generation ${id}`));
@@ -4,6 +4,7 @@ import {
4
4
  PAGINATION_OPTIONS,
5
5
  paginationQuery,
6
6
  numberOption,
7
+ loadJson,
7
8
  } from "../args.js";
8
9
  import { api } from "../api.js";
9
10
  import { outln, printResult, table } from "../output.js";
@@ -13,33 +14,83 @@ const HELP = `Usage: openrouter guardrails <subcommand> [options]
13
14
  Manage guardrails (requires a management key).
14
15
 
15
16
  Subcommands:
16
- list [--offset <n>] [--limit <n>] List guardrails
17
+ list [--offset <n>] [--limit <n>] [--workspace <uuid>]
18
+ List guardrails (default workspace unless
19
+ --workspace is given)
17
20
  get <id> Get one
18
21
  create <name> [options] Create
19
22
  update <id> [options] Update
20
23
  delete <id> Delete
21
- assignments [--keys|--members] List all assignments
24
+ assignments [--keys|--members] List all assignments (--offset/--limit)
22
25
  assign-key <id> <hash>... Assign API keys to a guardrail
23
26
  unassign-key <id> <hash>... Unassign API keys
24
27
  assign-member <id> <user>... Assign org members
25
28
  unassign-member <id> <user>... Unassign members
26
29
  key-assignments <id> List key assignments for a guardrail
27
30
  member-assignments <id> List member assignments for a guardrail
31
+ (both take --offset/--limit)
28
32
 
29
33
  create / update options:
30
34
  --name <name> (update only)
31
35
  --description <text>
32
- --limit-usd <n>
36
+ --limit-usd <n> On create, pass together with --reset-interval
33
37
  --reset-interval <p> daily | weekly | monthly | null
34
- --enforce-zdr / --no-zdr
38
+ --enforce-zdr / --no-zdr ZDR for every provider (deprecated API field)
39
+ --zdr-providers <csv> Enforce ZDR only for: anthropic,openai,google,xai,other
35
40
  --allowed-models <csv>
36
41
  --ignored-models <csv>
37
42
  --allowed-providers <csv>
38
43
  --ignored-providers <csv>
44
+ --regions <csv> Allowed data regions: global,europe,us ("" clears)
45
+ --content-filters <json|@file> Custom regex filters, e.g.
46
+ [{"pattern":"sk-[a-z0-9]{48}","action":"redact","label":"[KEY]"}]
47
+ action: redact | block | flag. "null" removes them.
48
+ --builtin-filters <spec> Builtin filters as JSON/@file
49
+ ([{"slug":"email","action":"redact"}]) or shorthand
50
+ email:redact,secrets:block. Slugs: email, phone, ssn,
51
+ credit-card, ip-address, secrets, person-name, address,
52
+ regex-prompt-injection. "null" removes them.
53
+ --free-publication / --no-free-publication Allow free endpoints that publish prompts
54
+ --free-training / --no-free-training Allow free endpoints that train on data
55
+ --paid-training / --no-paid-training Allow paid endpoints that train on data
39
56
  --include-byok / --no-include-byok Count BYOK spend toward the budget
40
57
  --workspace <uuid> (create only)
58
+ --extra <json|@file> Extra body fields, merged last (e.g. enforce_zdr_xai:false)
41
59
  `;
42
60
 
61
+ const ZDR_PROVIDERS = ["anthropic", "openai", "google", "xai", "other"];
62
+ const REGIONS = ["global", "europe", "us"];
63
+ const MAX_KEY_HASHES = 500;
64
+
65
+ function toggle(values, on, off) {
66
+ if (values[on] && values[off]) throw new Error(`Pass only one of --${on} or --${off}.`);
67
+ if (values[on]) return true;
68
+ if (values[off]) return false;
69
+ return undefined;
70
+ }
71
+
72
+ // JSON array (inline or @file), or the literal "null" to remove the field.
73
+ async function jsonArray(value, flag) {
74
+ if (value === undefined) return undefined;
75
+ if (value === "null") return null;
76
+ const parsed = await loadJson(value, flag);
77
+ if (!Array.isArray(parsed)) throw new Error(`${flag} must be a JSON array`);
78
+ return parsed;
79
+ }
80
+
81
+ async function builtinFilters(value) {
82
+ if (value === undefined || value === "null" || /^\s*[[@]/.test(value)) {
83
+ return jsonArray(value, "--builtin-filters");
84
+ }
85
+ return csv(value).map((entry) => {
86
+ const [slug, action] = entry.split(":");
87
+ if (!slug || !action) {
88
+ throw new Error(`--builtin-filters entry "${entry}" must be slug:action (e.g. email:redact)`);
89
+ }
90
+ return { slug, action };
91
+ });
92
+ }
93
+
43
94
  function csv(v) {
44
95
  if (v == null) return undefined;
45
96
  if (v === "") return null;
@@ -49,7 +100,7 @@ function csv(v) {
49
100
  .filter(Boolean);
50
101
  }
51
102
 
52
- function buildBody(values) {
103
+ async function buildBody(values) {
53
104
  const body = {};
54
105
  if (values.description !== undefined) body.description = values.description;
55
106
  if (values["limit-usd"] !== undefined)
@@ -67,6 +118,45 @@ function buildBody(values) {
67
118
  body.ignored_providers = csv(values["ignored-providers"]);
68
119
  if (values["include-byok"]) body.include_byok_in_budgets = true;
69
120
  if (values["no-include-byok"]) body.include_byok_in_budgets = false;
121
+ if (values["zdr-providers"] !== undefined) {
122
+ for (const p of csv(values["zdr-providers"]) || []) {
123
+ if (!ZDR_PROVIDERS.includes(p)) {
124
+ throw new Error(
125
+ `Unknown --zdr-providers entry "${p}". Expected: ${ZDR_PROVIDERS.join(", ")}`,
126
+ );
127
+ }
128
+ body[`enforce_zdr_${p}`] = true;
129
+ }
130
+ }
131
+ if (values.regions !== undefined) {
132
+ const regions = csv(values.regions);
133
+ for (const r of regions || []) {
134
+ if (!REGIONS.includes(r)) {
135
+ throw new Error(`Unknown region "${r}". Expected: ${REGIONS.join(", ")}`);
136
+ }
137
+ }
138
+ body.allowed_data_regions = regions;
139
+ }
140
+ const filters = await jsonArray(values["content-filters"], "--content-filters");
141
+ if (filters !== undefined) body.content_filters = filters;
142
+ const builtins = await builtinFilters(values["builtin-filters"]);
143
+ if (builtins !== undefined) body.content_filter_builtins = builtins;
144
+ const toggles = [
145
+ ["enable_free_model_publication", "free-publication"],
146
+ ["enable_free_model_training", "free-training"],
147
+ ["enable_paid_model_training", "paid-training"],
148
+ ];
149
+ for (const [field, flag] of toggles) {
150
+ const v = toggle(values, flag, `no-${flag}`);
151
+ if (v !== undefined) body[field] = v;
152
+ }
153
+ const extra = await loadJson(values.extra, "--extra");
154
+ if (extra !== undefined) {
155
+ if (!extra || typeof extra !== "object" || Array.isArray(extra)) {
156
+ throw new Error("--extra must be a JSON object");
157
+ }
158
+ Object.assign(body, extra);
159
+ }
70
160
  return body;
71
161
  }
72
162
 
@@ -82,6 +172,17 @@ const COMMON_FIELDS = {
82
172
  "ignored-providers": { type: "string" },
83
173
  "include-byok": { type: "boolean" },
84
174
  "no-include-byok": { type: "boolean" },
175
+ "zdr-providers": { type: "string" },
176
+ regions: { type: "string" },
177
+ "content-filters": { type: "string" },
178
+ "builtin-filters": { type: "string" },
179
+ "free-publication": { type: "boolean" },
180
+ "no-free-publication": { type: "boolean" },
181
+ "free-training": { type: "boolean" },
182
+ "no-free-training": { type: "boolean" },
183
+ "paid-training": { type: "boolean" },
184
+ "no-paid-training": { type: "boolean" },
185
+ extra: { type: "string" },
85
186
  };
86
187
 
87
188
  export async function guardrailsCommand(argv) {
@@ -98,8 +199,9 @@ export async function guardrailsCommand(argv) {
98
199
  }
99
200
 
100
201
  if (sub === "list") {
101
- const { values } = parseArgs(rest, PAGINATION_OPTIONS);
202
+ const { values } = parseArgs(rest, { ...PAGINATION_OPTIONS, workspace: { type: "string" } });
102
203
  const query = paginationQuery(values);
204
+ if (values.workspace) query.workspace_id = values.workspace;
103
205
  const data = await api("GET", "/guardrails", {
104
206
  auth: authFromValues(values),
105
207
  requiresManagement: true,
@@ -112,7 +214,14 @@ export async function guardrailsCommand(argv) {
112
214
  { label: "name", value: (g) => g.name },
113
215
  { label: "limit_usd", value: (g) => g.limit_usd ?? "" },
114
216
  { label: "reset", value: (g) => g.reset_interval ?? "" },
115
- { label: "zdr", value: (g) => (g.enforce_zdr ? "yes" : "") },
217
+ {
218
+ label: "zdr",
219
+ value: (g) => {
220
+ if (g.enforce_zdr) return "all";
221
+ return ZDR_PROVIDERS.filter((p) => g[`enforce_zdr_${p}`]).join(",");
222
+ },
223
+ },
224
+ { label: "regions", value: (g) => (g.allowed_data_regions || []).join(",") },
116
225
  ]);
117
226
  });
118
227
  return 0;
@@ -136,8 +245,11 @@ export async function guardrailsCommand(argv) {
136
245
  });
137
246
  const name = positionals[0];
138
247
  if (!name) throw new Error("name required");
139
- const body = { name, ...buildBody(values) };
248
+ const body = { name, ...(await buildBody(values)) };
140
249
  if (values.workspace) body.workspace_id = values.workspace;
250
+ if ("limit_usd" in body !== "reset_interval" in body) {
251
+ throw new Error("--limit-usd and --reset-interval must be passed together on create.");
252
+ }
141
253
  const data = await api("POST", "/guardrails", {
142
254
  auth: authFromValues(values),
143
255
  requiresManagement: true,
@@ -153,7 +265,7 @@ export async function guardrailsCommand(argv) {
153
265
  name: { type: "string" },
154
266
  });
155
267
  if (!positionals[0]) throw new Error("id required");
156
- const body = buildBody(values);
268
+ const body = await buildBody(values);
157
269
  if (values.name) body.name = values.name;
158
270
  const data = await api("PATCH", `/guardrails/${encodeURIComponent(positionals[0])}`, {
159
271
  auth: authFromValues(values),
@@ -177,6 +289,7 @@ export async function guardrailsCommand(argv) {
177
289
 
178
290
  if (sub === "assignments") {
179
291
  const { values } = parseArgs(rest, {
292
+ ...PAGINATION_OPTIONS,
180
293
  keys: { type: "boolean" },
181
294
  members: { type: "boolean" },
182
295
  });
@@ -189,13 +302,14 @@ export async function guardrailsCommand(argv) {
189
302
  const data = await api("GET", path, {
190
303
  auth: authFromValues(values),
191
304
  requiresManagement: true,
305
+ query: paginationQuery(values),
192
306
  });
193
307
  printResult(data);
194
308
  return 0;
195
309
  }
196
310
 
197
311
  if (sub === "key-assignments" || sub === "member-assignments") {
198
- const { values, positionals } = parseArgs(rest, {});
312
+ const { values, positionals } = parseArgs(rest, PAGINATION_OPTIONS);
199
313
  if (!positionals[0]) throw new Error("id required");
200
314
  const path =
201
315
  sub === "key-assignments"
@@ -204,6 +318,7 @@ export async function guardrailsCommand(argv) {
204
318
  const data = await api("GET", path, {
205
319
  auth: authFromValues(values),
206
320
  requiresManagement: true,
321
+ query: paginationQuery(values),
207
322
  });
208
323
  printResult(data);
209
324
  return 0;
@@ -214,6 +329,11 @@ export async function guardrailsCommand(argv) {
214
329
  if (positionals.length < 2) throw new Error("Usage: <id> <hash>...");
215
330
  const id = positionals[0];
216
331
  const hashes = positionals.slice(1);
332
+ if (hashes.length > MAX_KEY_HASHES) {
333
+ throw new Error(
334
+ `Too many key hashes (${hashes.length}); the API takes at most ${MAX_KEY_HASHES} per call. Split into batches.`,
335
+ );
336
+ }
217
337
  const path =
218
338
  sub === "assign-key"
219
339
  ? `/guardrails/${encodeURIComponent(id)}/assignments/keys`
@@ -239,7 +359,7 @@ export async function guardrailsCommand(argv) {
239
359
  const data = await api("POST", path, {
240
360
  auth: authFromValues(values),
241
361
  requiresManagement: true,
242
- body: { user_ids: userIds },
362
+ body: { member_user_ids: userIds },
243
363
  });
244
364
  printResult(data);
245
365
  return 0;
@@ -1,5 +1,14 @@
1
- import { parseArgs, authFromValues, numberOption } from "../args.js";
1
+ import {
2
+ parseArgs,
3
+ authFromValues,
4
+ numberOption,
5
+ loadJson,
6
+ applyRequestFields,
7
+ MEDIA_FIELD_OPTIONS,
8
+ MEDIA_FIELD_HELP,
9
+ } from "../args.js";
2
10
  import { api } from "../api.js";
11
+ import { mediaUrl } from "../media.js";
3
12
  import {
4
13
  isJsonMode,
5
14
  outln,
@@ -19,16 +28,23 @@ Subcommands:
19
28
  create options:
20
29
  -m, --model <id> Image model id (required)
21
30
  -p, --prompt <text> Prompt (or pass as positional)
22
- --n <count> Number of images to generate
23
- --resolution <r> e.g. 1024x1024
24
- --aspect <ratio> e.g. 16:9
25
- --quality <q>
26
- --format <fmt> png|jpeg|webp
27
- --background <b>
31
+ --n <count> Number of images to generate (1-10, upper bound)
32
+ --resolution <r> Tier: 512 | 768 | 1K | 1.5K | 2K | 4K
33
+ --size <s> Tier ("2K") or exact pixels ("2048x2048"); exact pixels
34
+ win, a clashing --resolution/--aspect is a 400
35
+ --aspect <ratio> auto | 1:1 | 2:3 | 3:2 | 3:4 | 4:3 | 4:5 | 5:4 | 5:7 | 7:5 |
36
+ 9:16 | 16:9 | 9:21 | 21:9 | 1:2 | 2:1 | 1:4 | 4:1 | 1:8 |
37
+ 8:1 | 5:2 | 2.35:1 | 9:19.5 | 19.5:9 | 9:20 | 20:9
38
+ --image <url|path> Reference image for image-to-image (repeatable, max 16);
39
+ local files are sent as data URLs
40
+ --quality <q> auto | low | medium | high | xhigh | max
41
+ --format <fmt> png | jpeg | webp | svg
42
+ --compression <n> 0-100, webp/jpeg only
43
+ --background <b> auto | transparent | opaque
28
44
  --seed <n>
29
- --provider <json>
30
- --extra <json> Extra fields merged into the body
31
- -o, --out <file> Output file (prefix when generating multiple)
45
+ --provider <json|@file>
46
+ --extra <json|@file> Extra fields merged into the body (last)
47
+ ${MEDIA_FIELD_HELP} -o, --out <file> Output file (prefix when generating multiple)
32
48
  `;
33
49
 
34
50
  const KNOWN_SUBCOMMANDS = new Set(["create", "generate", "models", "endpoints"]);
@@ -99,14 +115,18 @@ export async function imageCommand(argv) {
99
115
  prompt: { type: "string", short: "p" },
100
116
  n: { type: "string" },
101
117
  resolution: { type: "string" },
118
+ size: { type: "string" },
102
119
  aspect: { type: "string" },
120
+ image: { type: "string", multiple: true },
103
121
  quality: { type: "string" },
104
122
  format: { type: "string" },
123
+ compression: { type: "string" },
105
124
  background: { type: "string" },
106
125
  seed: { type: "string" },
107
126
  provider: { type: "string" },
108
127
  extra: { type: "string" },
109
128
  out: { type: "string", short: "o" },
129
+ ...MEDIA_FIELD_OPTIONS,
110
130
  });
111
131
  if (!values.model) throw new Error("--model is required");
112
132
  const prompt = values.prompt || positionals.join(" ").trim();
@@ -115,13 +135,24 @@ export async function imageCommand(argv) {
115
135
  const body = { model: values.model, prompt };
116
136
  if (values.n) body.n = numberOption(values.n, "--n");
117
137
  if (values.resolution) body.resolution = values.resolution;
138
+ if (values.size) body.size = values.size;
118
139
  if (values.aspect) body.aspect_ratio = values.aspect;
140
+ if (values.image?.length) {
141
+ if (values.image.length > 16) throw new Error("--image accepts at most 16 references");
142
+ body.input_references = [];
143
+ for (const img of values.image) {
144
+ body.input_references.push({ type: "image_url", image_url: { url: await mediaUrl(img) } });
145
+ }
146
+ }
119
147
  if (values.quality) body.quality = values.quality;
120
148
  if (values.format) body.output_format = values.format;
149
+ if (values.compression)
150
+ body.output_compression = numberOption(values.compression, "--compression");
121
151
  if (values.background) body.background = values.background;
122
152
  if (values.seed) body.seed = numberOption(values.seed, "--seed");
123
- if (values.provider) body.provider = JSON.parse(values.provider);
124
- if (values.extra) Object.assign(body, JSON.parse(values.extra));
153
+ if (values.provider) body.provider = await loadJson(values.provider, "--provider");
154
+ await applyRequestFields(body, values);
155
+ if (values.extra) Object.assign(body, await loadJson(values.extra, "--extra"));
125
156
 
126
157
  const data = await api("POST", "/images", { auth: authFromValues(values), body });
127
158