@evolinkai/cli 0.13.0 → 0.14.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.
Files changed (28) hide show
  1. package/README.md +20 -6
  2. package/package.json +1 -1
  3. package/skills/evolink-cli/SKILL.md +21 -7
  4. package/skills/evolink-cli/references/capabilities.md +1 -1
  5. package/skills/evolink-cli/references/media-workflows.md +1 -1
  6. package/skills/evolink-cli/references/usage-and-budget.md +5 -3
  7. package/src/cli.mjs +76 -21
  8. package/src/help.mjs +12 -5
  9. package/src/media.mjs +142 -37
  10. package/src/platform/core/src/data/model-constraints.js +8 -5
  11. package/src/platform/core/src/data/model-params.overrides.generated.js +1 -1
  12. package/src/platform/core/src/services/api-client.js +1 -1
  13. package/src/platform/core/src/services/batch-generation.js +117 -0
  14. package/src/platform/core/src/services/gpt-image-tokens.js +264 -0
  15. package/src/platform/core/src/services/omni-tokens.js +245 -0
  16. package/src/platform/core/src/services/param-validator.js +48 -1
  17. package/src/platform/core/src/services/pricing-call-limit.js +4 -4
  18. package/src/platform/core/src/services/pricing-derived.js +3 -3
  19. package/src/platform/core/src/services/pricing-rules-client.js +23 -5
  20. package/src/platform/core/src/services/pricing-rules-estimate.js +266 -67
  21. package/src/platform/core/src/tool-guidance.js +25 -2
  22. package/src/platform/core/src/tools/estimate-cost.js +201 -60
  23. package/src/platform/core/src/tools/generate.js +497 -75
  24. package/src/platform/core/src/tools/get-model.js +15 -3
  25. package/src/platform/core/src/tools/get-pricing-rules.js +4 -3
  26. package/src/platform/core/src/tools/shared.js +1 -1
  27. package/src/platform/core/src/version.js +1 -1
  28. package/src/platform/source.json +41 -35
@@ -174,9 +174,44 @@ export function validateInput(spec, input) {
174
174
  if (present.length > 1)
175
175
  result.errors.push({ param: present.join(', '), problem: 'are mutually exclusive; pass only one reference type.' });
176
176
  }
177
+ // A documented condition: an input that matches its `if` must also meet its `then`.
178
+ for (const condition of spec.conditions ?? []) {
179
+ const meets = (name, limits) => {
180
+ const check = { errors: [], warnings: [] };
181
+ checkValue(name, limits, rest[name], check);
182
+ return check.errors.length === 0;
183
+ };
184
+ const matches = (condition.if.required ?? []).every(name => rest[name] !== undefined)
185
+ && Object.entries(condition.if.properties ?? {}).every(([name, limits]) => rest[name] === undefined || meets(name, limits));
186
+ if (!matches)
187
+ continue;
188
+ const then = { errors: [], warnings: [] };
189
+ for (const name of condition.then.required ?? [])
190
+ if (rest[name] === undefined)
191
+ then.errors.push({ param: name, problem: 'is required.' });
192
+ for (const [name, limits] of Object.entries(condition.then.properties ?? {}))
193
+ checkValue(name, limits, rest[name], then);
194
+ for (const issue of then.errors)
195
+ result.errors.push({ param: issue.param, problem: `${issue.problem.replace(/\.$/, '')} (documented condition: when ${conditionText(condition.if)}).` });
196
+ }
197
+ // A body documented as one of several shapes: the given parameters must fit one, with everything it requires.
198
+ if (spec.requestShapes?.length) {
199
+ const given = Object.keys(rest).filter(name => spec.params[name] && rest[name] !== undefined && rest[name] !== null && rest[name] !== '');
200
+ const fits = spec.requestShapes.some(shape => shape.required.every(name => given.includes(name)) && given.every(name => shape.params.includes(name)));
201
+ if (!fits)
202
+ result.errors.push({ param: given.join(', ') || 'input', problem: `must fit one of the documented request shapes: ${spec.requestShapes.map(shapeText).join('; or ')}.` });
203
+ }
177
204
  const size = spec.constraints?.imageSize;
178
205
  const value = size ? rest[size.param] : undefined;
179
- if (size && typeof value === 'string' && !size.allowed.includes(value)) {
206
+ const frames = size?.frames && rest.output_format === size.frames.outputFormat ? size.frames : undefined;
207
+ if (frames && typeof value === 'string' && value !== 'auto') {
208
+ const pixels = /^(\d+)[x×](\d+)$/.exec(value), width = Number(pixels?.[1]), height = Number(pixels?.[2]);
209
+ if (!pixels || width < frames.minEdge || height < frames.minEdge || width > frames.maxEdge || height > frames.maxEdge
210
+ || width % frames.step !== 0 || height % frames.step !== 0) {
211
+ result.errors.push({ param: size.param, problem: `with output_format ${frames.outputFormat} is each frame's size: auto, or WxH with edges ${frames.minEdge}–${frames.maxEdge} in multiples of ${frames.step}.` });
212
+ }
213
+ }
214
+ else if (size && typeof value === 'string' && !size.allowed.includes(value)) {
180
215
  const pixels = /^(\d+)[x×](\d+)$/.exec(value);
181
216
  if (!pixels || !size.allowPixels) {
182
217
  result.errors.push({ param: size.param, problem: `must be one of ${size.allowed.join(', ')}${size.allowPixels ? ', or a valid WxH pixel size' : ''}.` });
@@ -196,6 +231,18 @@ export function validateInput(spec, input) {
196
231
  }
197
232
  return result;
198
233
  }
234
+ /** One side of a documented condition in words, e.g. "image_urls minItems 2" or "duration minimum 11". */
235
+ export function conditionText(part) {
236
+ const limits = Object.entries(part.properties ?? {}).map(([name, limit]) => `${name} ${Object.entries(limit)
237
+ .filter(([key]) => key !== 'type' && key !== 'description').map(([key, value]) => `${key} ${show(value)}`).join(', ')}`.trim());
238
+ const present = (part.required ?? []).filter(name => !(part.properties ?? {})[name]).map(name => `${name} is given`);
239
+ return [...limits, ...present].join(' and ');
240
+ }
241
+ /** One request shape in words: what it requires, then what else it accepts. */
242
+ export function shapeText(shape) {
243
+ const optional = shape.params.filter(name => !shape.required.includes(name));
244
+ return `${shape.required.join(', ')}${optional.length ? ` (optional: ${optional.join(', ')})` : ''}`;
245
+ }
199
246
  export function formatIssues(issues) {
200
247
  return issues.map(issue => `- ${issue.param} ${issue.problem}`);
201
248
  }
@@ -6,10 +6,10 @@ const MAX_KEYS = 10_000;
6
6
  const calls = new Map();
7
7
  let clock = () => Date.now();
8
8
  /**
9
- * Price checks (estimate_cost, get_pricing_rules) each signed-in account may make per minute, per tool. The hosted
10
- * service reaches the platform's per-IP catalog limit from one address for everyone, so one busy assistant must not
11
- * use it up. A local server serves one user and is not limited here. EVOLINK_MCP_PRICING_CALLS_PER_MINUTE changes
12
- * the number; 0 turns the limit off.
9
+ * Price checks (estimate_cost, get_pricing_rules) that read the platform's pricing rules, per signed-in account, per
10
+ * minute and tool; one answered from rules read moments ago is not counted. The hosted service reaches the platform's
11
+ * per-IP catalog limit from one address for everyone, so one busy assistant must not use it up. A local server serves
12
+ * one user and is not limited here. EVOLINK_MCP_PRICING_CALLS_PER_MINUTE changes the number; 0 turns the limit off.
13
13
  */
14
14
  export function pricingCallsPerMinute() {
15
15
  const raw = process.env.EVOLINK_MCP_PRICING_CALLS_PER_MINUTE;
@@ -45,10 +45,10 @@ export const CONSERVATIVE_QUOTE_PARAMETERS = {
45
45
  note: 'Assumes the source draft was generated without the content filter (10% more); if it kept the default content_filter=true, pass pricing_parameters.content_filter=true.' },
46
46
  };
47
47
  /**
48
- * A documented setting value that stands for the rule's own default. Kling 4.0 video edit documents duration "auto"
49
- * (as long as the input video); its rule reads duration_seconds 0 as the input length.
48
+ * A documented setting value that stands for the rule's own default. Kling 4.0 and 4.0 Flash video edit document
49
+ * duration "auto" (as long as the input video); their rules read duration_seconds 0 as the input length.
50
50
  */
51
- const RULE_DEFAULT_WORDS = { 'kling-v4-video-edit duration_seconds': 'auto' };
51
+ const RULE_DEFAULT_WORDS = { 'kling-v4-video-edit duration_seconds': 'auto', 'kling-v4-flash-video-edit duration_seconds': 'auto' };
52
52
  export function isRuleDefaultWord(model, name, value) {
53
53
  const word = RULE_DEFAULT_WORDS[`${model.toLowerCase()} ${name}`];
54
54
  return word !== undefined && typeof value === 'string' && value.trim().toLowerCase() === word;
@@ -226,19 +226,37 @@ function cachedModel(model, usable) {
226
226
  export function recentModelRules(model, maxAgeMs) {
227
227
  return cachedModel(model, entry => Date.now() - entry.fetchedAt <= maxAgeMs);
228
228
  }
229
+ /** The cached answer to a query that `usable` accepts: a model's full rules may come from its row in the cached full list. */
230
+ function reusable(query, usable) {
231
+ if (query.model && query.view === 'full' && !query.product_id && !query.operation && !query.modality && !query.lifecycle)
232
+ return cachedModel(query.model, usable);
233
+ const old = cache.get(rulesURL(query).href);
234
+ return old && usable(old) ? old : undefined;
235
+ }
236
+ /** Whether getPricingRules(input, { reuseUntilFresh: true }) would answer from the cache now, without reading the platform. */
237
+ export function reusablePricingRules(input) {
238
+ return reusable(PricingRulesQuery.parse(input), stillFresh) !== undefined;
239
+ }
229
240
  /**
230
241
  * `reuseUntilFresh` serves a model's full rules from the cache (its own entry or the full list) until the rules' own
231
242
  * fresh_until, which estimates use so a burst of them does not spend the platform's per-IP catalog limit; generation
232
- * reads `fresh` rules and asks for a new approval when the price moved.
243
+ * reads `fresh` rules and asks for a new approval when the price moved. `maxAgeMs` lets a fresh read take rules read
244
+ * that recently, still within their fresh_until, so a batch of generations reads them once. Concurrent reads of one
245
+ * query always share a single request.
233
246
  */
234
247
  export async function getPricingRules(input, options = {}) {
235
248
  const query = PricingRulesQuery.parse(input), url = rulesURL(query);
236
249
  const key = url.href, old = cache.get(key);
237
250
  if (options.reuseUntilFresh) {
238
- const reusable = query.model && query.view === 'full' && !query.product_id && !query.operation && !query.modality && !query.lifecycle
239
- ? cachedModel(query.model, stillFresh) : old && stillFresh(old) ? old : undefined;
240
- if (reusable)
241
- return { body: reusable.body, source: 'cache' };
251
+ const cached = reusable(query, stillFresh);
252
+ if (cached)
253
+ return { body: cached.body, source: 'cache' };
254
+ }
255
+ if (options.maxAgeMs !== undefined) {
256
+ const maxAgeMs = options.maxAgeMs;
257
+ const recent = reusable(query, entry => stillFresh(entry) && Date.now() - entry.fetchedAt <= maxAgeMs);
258
+ if (recent)
259
+ return { body: recent.body, source: 'recent' };
242
260
  }
243
261
  if (!options.fresh && old && old.expires > Date.now())
244
262
  return { body: old.body, source: 'cache' };
@@ -2,17 +2,20 @@
2
2
  // Generated from Evolink-AI/evolink-mcp; adapted for direct REST operations. See platform/LICENSE and platform/NOTICE.
3
3
  import { z } from 'zod';
4
4
  import { PricingRulesError, getPricingRules, recentModelRules } from './pricing-rules-client.js';
5
- import { QuoteError, isUsageParameter, prepareQuoteParameters, quoteRequestHash } from './pricing-quote-client.js';
5
+ import { QuoteError, compareDecimal, isUsageParameter, prepareQuoteParameters, quoteRequestHash } from './pricing-quote-client.js';
6
6
  import { prepareSeedanceInput } from './seedance-input.js';
7
7
  import { searchUsage } from './search-usage.js';
8
8
  import { CONSERVATIVE_QUOTE_PARAMETERS } from './pricing-derived.js';
9
+ import { INPUT_IMAGE_TOKENS, isTokenImageModel, tokenImageReservation } from './gpt-image-tokens.js';
10
+ import { OMNI_IMAGE_TOKENS, OMNI_UNREAD_TIER, isOmniTokenModel, omniLowerInputTier, omniReservation } from './omni-tokens.js';
9
11
  /**
10
- * How long an approval from estimate_cost may be passed to generate_*. The rules' own
11
- * `fresh_until` is a short refresh window (minutes); people confirming a price in a chat
12
- * need longer. generate_* re-evaluates the current rules and refuses with `price_changed`
13
- * when the price moved, so a longer approval cannot submit at a stale price.
12
+ * How long an approval from estimate_cost is shown as current. The rules' own `fresh_until`
13
+ * is a short refresh window (minutes); people confirming a price in a chat may come back much
14
+ * later. generate_* re-evaluates the current rules and refuses with `price_changed` when the
15
+ * price moved, so an approval never submits at a stale price; one past this time still holds
16
+ * for the same input and price (checkRulesApproval).
14
17
  */
15
- export const APPROVAL_TTL_MS = 30 * 60_000;
18
+ export const APPROVAL_TTL_MS = 24 * 60 * 60_000;
16
19
  function fail(code, message) { throw new QuoteError(code, message); }
17
20
  function gcd(a, b) { while (b)
18
21
  [a, b] = [b, a % b]; return a < 0n ? -a : a; }
@@ -71,12 +74,25 @@ export function amountsForUC(uc) {
71
74
  const a = decimal(uc);
72
75
  return { uc, credits: display(div(a, rat(10000n)), 4), cny: display(div(a, rat(100000n)), 5), usd: display(div(a, rat(680000n)), 8) };
73
76
  }
74
- export function rulesBudgetExceeded(uc, budget) {
77
+ function budgetUC(budget) {
75
78
  // String(number) may use scientific notation for a small, explicit budget.
76
79
  const [mantissa, exp = '0'] = String(budget).split('e');
77
80
  const power = Number(exp), b = decimal(mantissa);
78
81
  const value = power < 0 ? div(b, rat(10n ** BigInt(-power))) : mul(b, rat(10n ** BigInt(power)));
79
- return cmp(decimal(uc), mul(value, rat(680000n))) > 0;
82
+ return mul(value, rat(680000n));
83
+ }
84
+ export function rulesBudgetExceeded(uc, budget) {
85
+ return cmp(decimal(uc), budgetUC(budget)) > 0;
86
+ }
87
+ /**
88
+ * A token-billed reference price fits a budget only with room for the tokens a task actually uses: 1.5 times the
89
+ * reference must fit. The largest overrun on record is 20% (gpt-image-2, 4K high); large reference images are unmeasured.
90
+ */
91
+ export const REFERENCE_BUDGET_FACTOR = '1.5';
92
+ /** The amount a budget has to cover for a reference price, for messages. */
93
+ export function referenceAllowance(uc) { return amountsForUC(display(mul(decimal(uc), decimal(REFERENCE_BUDGET_FACTOR)), 4)); }
94
+ export function referenceBudgetExceeded(uc, budget) {
95
+ return cmp(mul(decimal(uc), decimal(REFERENCE_BUDGET_FACTOR)), budgetUC(budget)) > 0;
80
96
  }
81
97
  const arity = { constant: [0, 0], variable: [0, 0], lookup: [0, 0],
82
98
  add: [2, 32], multiply: [2, 32], subtract: [2, 2], divide: [2, 2], min: [2, 32], max: [2, 32], clamp: [3, 3],
@@ -117,6 +133,8 @@ function componentReads(c) {
117
133
  }
118
134
  /** How to give a usage value an estimate lacks, or why only the finished task knows it. */
119
135
  function usageHint(name, entry, declared) {
136
+ if (name === 'media_seconds')
137
+ return 'pass the length of the input video in seconds as media_seconds (for several reference videos, the longest one\'s): EvoLink measures it at submission and reserves its tokens with the output\'s.';
120
138
  if (name === 'input_seconds' || name === 'first_input_video_seconds')
121
139
  return 'pass the length of the input video or audio, in seconds, as media_seconds.';
122
140
  if (name === 'source_output_seconds')
@@ -147,9 +165,112 @@ function helpLines(names, entry, rule, declared) {
147
165
  }
148
166
  /** Every usage value a rule can bill by, with how to give it; get_model lists them before any estimate. */
149
167
  export function billingUsageHelp(rule, entry) {
168
+ if (reservesTokens(rule, entry))
169
+ return [];
150
170
  const declared = new Set((rule.parameters ?? []).map(p => p.name));
151
171
  return helpLines([...declared].filter(name => isUsageParameter(entry.id, name)).sort(), entry, rule, declared);
152
172
  }
173
+ // GPT Image and Gemini Omni token models: the reference price counts the tokens the gateway reserves at submission for the input.
174
+ const RESERVED_TOKENS = new Set(['image_input_tokens', 'image_cached_input_tokens', 'image_output_tokens',
175
+ 'text_input_tokens', 'text_cached_input_tokens', 'text_output_tokens']);
176
+ const OMNI_TOKENS = new Set(['input_tokens', 'video_output_tokens', 'other_output_tokens']);
177
+ /** GPT Image 2.6 rules also bill an SVG's author model. SVG output is not quoted, so a reference price uses none. */
178
+ const NO_SVG_AUTHOR = { svg_model: 'none', svg_input_tokens: 0, svg_output_tokens: 0 };
179
+ const svgAuthor = (name) => Object.hasOwn(NO_SVG_AUTHOR, name);
180
+ /** Only a rule billed by these token counts alone, with an output component, can price the reservation. */
181
+ function reservesTokens(rule, entry) {
182
+ const id = entry.id.toLowerCase();
183
+ if (rule.settlement_basis !== 'actual_usage')
184
+ return false;
185
+ if (isOmniTokenModel(id)) {
186
+ return (rule.parameters ?? []).every(p => OMNI_TOKENS.has(p.name))
187
+ && rule.components.some(c => c.role === 'video_output' && c.pricing_status === 'available' && componentReads(c).has('video_output_tokens'));
188
+ }
189
+ return isTokenImageModel(id)
190
+ && (rule.parameters ?? []).every(p => RESERVED_TOKENS.has(p.name)
191
+ || svgAuthor(p.name) && (p.name !== 'svg_model' || (p.values ?? p.enum ?? []).includes(NO_SVG_AUTHOR.svg_model)))
192
+ && rule.components.some(c => c.role === 'image_output' && c.pricing_status === 'available' && componentReads(c).has('image_output_tokens'));
193
+ }
194
+ /** How estimate_cost prices a token model, for get_model. */
195
+ export function tokenReferenceHelp(rule, entry) {
196
+ if (!reservesTokens(rule, entry))
197
+ return undefined;
198
+ const rates = rule.components.filter(c => ![...componentReads(c)].some(svgAuthor))
199
+ .map(c => `${c.id} $${c.rate.usd} per ${c.unit === '1k_tokens' ? '1K tokens' : c.unit.replace(/_/g, ' ')}`);
200
+ if (isOmniTokenModel(entry.id.toLowerCase())) {
201
+ return `Billed by actual token usage. estimate_cost gives a reference price for the exact input: the tokens EvoLink reserves at submission for its resolution, duration, prompt, images and input videos, at the published rates (public default rates: ${rates.join('; ')}). Give an input or reference video's length as media_seconds; its resolution is read at submission, so the reference counts the highest (${OMNI_UNREAD_TIER}). The task settles at the tokens it actually uses.`;
202
+ }
203
+ return `Billed by actual token usage. estimate_cost gives a reference price for the exact input: the tokens EvoLink reserves at submission for its size, quality, n, prompt and reference images, at the published rates (public default rates: ${rates.join('; ')}). The task settles at the tokens it actually uses.`;
204
+ }
205
+ /** An Omni reservation's tokens as the rule's parameters. */
206
+ const omniParameters = (rule, usage) => Object.fromEntries((rule.parameters ?? []).map(p => [p.name, usage.tokens[p.name] ?? 0]));
207
+ function reservation(rule, entry, input, countPromptTokens, mediaSeconds) {
208
+ if (!reservesTokens(rule, entry))
209
+ return undefined;
210
+ const id = entry.id.toLowerCase();
211
+ if (isOmniTokenModel(id)) {
212
+ const usage = omniReservation(id, input, mediaSeconds, { countPromptTokens });
213
+ return 'needs' in usage ? usage : { omni: usage, parameters: omniParameters(rule, usage) };
214
+ }
215
+ const usage = tokenImageReservation(id, input, countPromptTokens);
216
+ const parameters = {};
217
+ for (const p of rule.parameters ?? []) {
218
+ parameters[p.name] = svgAuthor(p.name) ? NO_SVG_AUTHOR[p.name] : usage.per_image[p.name] ?? 0;
219
+ }
220
+ return { gpt: usage, parameters };
221
+ }
222
+ const CONFIRM_REFERENCE = 'Confirm this reference price before generation. It is billed by actual token usage: EvoLink reserves this amount at submission and settles the task at the tokens it actually uses, refunding or charging the difference when it finishes, so the final charge may be lower or slightly higher.';
223
+ const ignoredNote = (ignored) => `pricing_parameters ${ignored.join(', ')} ${ignored.length > 1 ? 'are' : 'is'} not used for this model: the reference price comes from the generation input.`;
224
+ function reservationNotes(usage, ignored) {
225
+ const notes = [CONFIRM_REFERENCE];
226
+ const gif = usage.output.gif;
227
+ if (gif)
228
+ notes.push(`output_format is gif: the ${gif.frames} frames of ${gif.frame_width}×${gif.frame_height}${usage.output.size === 'auto' ? ' (size auto)' : ''} are drawn ${gif.columns}×${gif.rows} on one ${usage.output.width}×${usage.output.height} image, and the reference counts that image's output tokens.`);
229
+ else if (usage.output.size === 'auto')
230
+ notes.push('size is auto, so the reference counts a 2048×2048 output, as EvoLink reserves for auto; the image is often smaller, so set a size for a closer reference price.');
231
+ if (usage.reference_images)
232
+ notes.push(`Each reference image or mask counts ${INPUT_IMAGE_TOKENS.toLocaleString('en-US')} input tokens; larger reference images can use more.`);
233
+ if (usage.images > 1)
234
+ notes.push(`n=${usage.images}: the reference covers ${usage.images} images; the model often returns fewer, and the task is billed for what it returns.`);
235
+ notes.push('Prompt tokens are approximated; EvoLink counts them exactly at submission.');
236
+ if (ignored.length)
237
+ notes.push(ignoredNote(ignored));
238
+ return notes;
239
+ }
240
+ const tokenText = (tokens) => tokens.toLocaleString('en-US');
241
+ function omniBasis(usage) {
242
+ const t = usage.tokens, videos = usage.input_videos;
243
+ const parts = [`${tokenText(t.video_output_tokens)} video output tokens (${usage.upscale ? `upscale ${usage.upscale.source} to ${usage.upscale.target}` : usage.output.resolution}, ${usage.output.seconds} s)`];
244
+ if (t.input_tokens) {
245
+ const inputs = [`about ${tokenText(usage.prompt_tokens)} prompt tokens`, ...usage.images ? [`${usage.images} image${usage.images > 1 ? 's' : ''}`] : [],
246
+ ...videos ? [`${videos.count > 1 ? `${videos.count} reference videos of` : 'an input video of'} ${videos.seconds} s at ${videos.resolution}`] : []];
247
+ parts.push(`${tokenText(t.input_tokens)} input tokens (${inputs.join(', ')})`);
248
+ }
249
+ if (t.other_output_tokens)
250
+ parts.push(`${tokenText(t.other_output_tokens)} other output tokens`);
251
+ return `Reference price: published token rates applied to what EvoLink reserves at submission for this input: ${parts.join(', ')}, each part rounded up.`;
252
+ }
253
+ function omniNotes(usage, ignored, lower) {
254
+ const notes = [CONFIRM_REFERENCE];
255
+ const videos = usage.input_videos;
256
+ if (videos?.resolution_assumed) {
257
+ notes.push(`EvoLink reads the input video's resolution at submission; the request does not give it, so the reference counts the highest, ${videos.resolution}, as EvoLink reserves when it cannot read it.${lower ? ` A ${lower.tier} input video reserves ${lower.amounts.credits} credits (about $${lower.amounts.usd}) instead.` : ''}`);
258
+ }
259
+ if (usage.upscale?.source_assumed) {
260
+ notes.push(`EvoLink reads the source video's resolution at submission; the reference counts the source that costs most for ${usage.upscale.target}, ${usage.upscale.source}.${lower ? ` A ${lower.tier} source reserves ${lower.amounts.credits} credits (about $${lower.amounts.usd}) instead.` : ''}`);
261
+ }
262
+ if (videos && usage.route !== 'upscale')
263
+ notes.push(`media_seconds counts ${videos.count > 1 ? 'each reference video' : 'the input video'} at ${videos.seconds} s (rounded up); EvoLink measures ${videos.count > 1 ? 'each' : 'it'} at submission.`);
264
+ if (usage.output.follows_input)
265
+ notes.push('quality is auto, so the output follows the input video\'s resolution.');
266
+ if (usage.images)
267
+ notes.push(`Each input image counts ${tokenText(OMNI_IMAGE_TOKENS)} input tokens.`);
268
+ if (usage.prompt_tokens)
269
+ notes.push('Prompt tokens are approximated; EvoLink counts them exactly at submission.');
270
+ if (ignored.length > 0)
271
+ notes.push(ignoredNote(ignored));
272
+ return notes;
273
+ }
153
274
  function evaluate(node, params) {
154
275
  const nodes = node.args ?? [], at = (i) => evaluate(nodes[i], params), number = (i) => numeric(at(i));
155
276
  switch (node.op) {
@@ -201,42 +322,11 @@ function evaluate(node, params) {
201
322
  default: return fail('invalid_pricing_expression', 'The pricing rule uses an unsupported operation.');
202
323
  }
203
324
  }
204
- export const ApprovedRulesEstimate = z.object({ source: z.literal('pricing_rules'), price_scope: z.literal('public_default'),
205
- model_id: z.string().min(1).max(100), request_hash: z.string().regex(/^[a-f0-9]{64}$/),
206
- fingerprint: z.string().regex(/^[a-f0-9]{64}$/), total_uc: z.string().max(32).regex(/^\d+$/),
207
- expires_at: z.string().datetime({ offset: true }) }).strict();
208
- function economicRules(rule) {
209
- // Freshness and configuration timestamps do not change the approved price.
210
- return { ...rule, components: rule.components.map(({ effective_at, official_rate, ...c }) => ({ ...c,
211
- tiers: c.tiers.map(({ effective_at, official_rate, ...t }) => t) })) };
212
- }
213
- export function calculateRulesEstimate(body, entry, input, options = {}) {
214
- const rule = 'model' in body ? body.model : body.models.find(model => model.model_id === entry.id);
215
- if (!rule || rule.model_id !== entry.id.toLowerCase() || rule.modality !== entry.kind || rule.policy_source !== 'published' || rule.pricing_status !== 'available') {
216
- fail('pricing_rules_unavailable', 'This model has no available published media pricing policy.');
217
- }
218
- const prepared = prepareSeedanceInput(entry, input);
219
- if (prepared.errors.length)
220
- throw new QuoteError('invalid_quote_parameter', `${prepared.errors[0].param} ${prepared.errors[0].problem}`, prepared.errors[0].param);
221
- const effectiveInput = prepared.input;
222
- const params = prepareQuoteParameters(rule, entry, effectiveInput, options.pricingParameters, options.mediaSeconds, true);
223
- const declared = new Set((rule.parameters ?? []).map(p => p.name)), ids = new Set();
325
+ /** The rule's components for these parameters: each subtotal rounded and at least its minimum, times count. */
326
+ function chargeComponents(rule, declared, params, images, missing) {
224
327
  const components = [];
328
+ const ids = new Set();
225
329
  let total = 0n;
226
- const missing = new Set();
227
- const searchCharges = searchUsage(entry, effectiveInput).filter(search => search.enabled).map(search => {
228
- const component = rule.components.find(item => item.role === search.role);
229
- if (!declared.has(search.parameter) || !component || component.pricing_status !== 'available' || component.unit !== 'search'
230
- || component.billing_unit_size !== 1 || component.tiers.length) {
231
- fail('search_pricing_unavailable', 'The enabled search unit price could not be verified. Refresh pricing before generation.');
232
- }
233
- const expected = options.pricingParameters?.[search.parameter] !== undefined || effectiveInput[search.parameter] !== undefined;
234
- if (!expected)
235
- missing.add(search.parameter);
236
- return { role: search.role, input_parameter: search.input_parameter, usage_parameter: search.parameter,
237
- assumed_count: String(params[search.parameter]), assumption: expected ? 'expected_usage' : 'zero_searches',
238
- actual_count_known: false, unit: 'search', unit_price_amounts: amountsForUC(component.rate.uc) };
239
- });
240
330
  for (const c of rule.components) {
241
331
  if (ids.has(c.id) || !c.quantity_rule || !c.rounding)
242
332
  fail('invalid_pricing_expression', 'The pricing rule is incomplete or has duplicate components.');
@@ -268,9 +358,9 @@ export function calculateRulesEstimate(body, entry, input, options = {}) {
268
358
  const charge = cmp(subtotal, minimum) < 0 ? minimum : subtotal;
269
359
  if (charge.d !== 1n || charge.n < 0n || charge.n > BigInt(Number.MAX_SAFE_INTEGER))
270
360
  fail('invalid_pricing_expression', 'The pricing rule does not produce a supported integer UC charge.');
271
- total += charge.n;
272
- components.push({ id: c.id, sku_id: selected.sku_id, quantity: exact(q), billed_quantity: exact(billed),
273
- subtotal_uc: String(charge.n), minimum_charge_applied: cmp(subtotal, minimum) < 0 });
361
+ total += charge.n * images;
362
+ components.push({ id: c.id, sku_id: selected.sku_id, quantity: exact(mul(q, rat(images))), billed_quantity: exact(mul(billed, rat(images))),
363
+ subtotal_uc: String(charge.n * images), minimum_charge_applied: cmp(subtotal, minimum) < 0 });
274
364
  }
275
365
  catch (error) {
276
366
  if (error instanceof QuoteError && error.code === 'quote_usage_required' && error.param) {
@@ -284,26 +374,115 @@ export function calculateRulesEstimate(body, entry, input, options = {}) {
284
374
  throw error;
285
375
  }
286
376
  }
377
+ return { components, total };
378
+ }
379
+ /** The most inputs one estimate_cost or generate_* call takes (`inputs`), all for one model. */
380
+ export const MAX_BATCH_ITEMS = 50;
381
+ /** `batch_items` marks an approval of a whole batch (inputs); it never approves a single input, nor the reverse. */
382
+ export const ApprovedRulesEstimate = z.object({ source: z.literal('pricing_rules'), price_scope: z.literal('public_default'),
383
+ model_id: z.string().min(1).max(100), request_hash: z.string().regex(/^[a-f0-9]{64}$/),
384
+ fingerprint: z.string().regex(/^[a-f0-9]{64}$/), total_uc: z.string().max(32).regex(/^\d+$/),
385
+ expires_at: z.string().datetime({ offset: true }), batch_items: z.number().int().min(1).max(MAX_BATCH_ITEMS).optional() }).strict();
386
+ function economicRules(rule) {
387
+ // Freshness and configuration timestamps do not change the approved price.
388
+ return { ...rule, components: rule.components.map(({ effective_at, official_rate, ...c }) => ({ ...c,
389
+ tiers: c.tiers.map(({ effective_at, official_rate, ...t }) => t) })) };
390
+ }
391
+ /** countPromptTokens replaces the approximate prompt token count, for comparing with the gateway's exact count. */
392
+ export function calculateRulesEstimate(body, entry, input, options = {}) {
393
+ const rule = 'model' in body ? body.model : body.models.find(model => model.model_id === entry.id);
394
+ if (!rule || rule.model_id !== entry.id.toLowerCase() || rule.modality !== entry.kind || rule.policy_source !== 'published' || rule.pricing_status !== 'available') {
395
+ fail('pricing_rules_unavailable', 'This model has no available published media pricing policy.');
396
+ }
397
+ const prepared = prepareSeedanceInput(entry, input);
398
+ if (prepared.errors.length)
399
+ throw new QuoteError('invalid_quote_parameter', `${prepared.errors[0].param} ${prepared.errors[0].problem}`, prepared.errors[0].param);
400
+ const effectiveInput = prepared.input;
401
+ const declared = new Set((rule.parameters ?? []).map(p => p.name));
402
+ const id = entry.id.toLowerCase();
403
+ // GPT Image and Gemini Omni token models never use token counts from pricing_parameters: the reference counts what
404
+ // the gateway reserves for this input. Leaving them out of the request hash lets a generation pass them or not.
405
+ const ignored = isTokenImageModel(id) || isOmniTokenModel(id)
406
+ ? Object.keys(options.pricingParameters ?? {}).filter(name => declared.has(name) && (/tokens$/.test(name) || svgAuthor(name))).sort() : [];
407
+ const pricingParameters = ignored.length
408
+ ? Object.fromEntries(Object.entries(options.pricingParameters).filter(([name]) => !ignored.includes(name))) : options.pricingParameters;
409
+ const reserved = reservation(rule, entry, effectiveInput, options.countPromptTokens, options.mediaSeconds);
410
+ const params = { ...prepareQuoteParameters(rule, entry, effectiveInput, pricingParameters, options.mediaSeconds, true), ...reserved?.parameters };
411
+ // The gateway rounds each image's charge up separately, then reserves it once per image.
412
+ const images = BigInt(reserved?.gpt?.images ?? 1);
413
+ const missing = new Set();
414
+ // An Omni input video is billed by its length, which only media_seconds gives before submission.
415
+ if (reserved?.needs)
416
+ missing.add('media_seconds');
417
+ const searchCharges = searchUsage(entry, effectiveInput).filter(search => search.enabled).map(search => {
418
+ const component = rule.components.find(item => item.role === search.role);
419
+ if (!declared.has(search.parameter) || !component || component.pricing_status !== 'available' || component.unit !== 'search'
420
+ || component.billing_unit_size !== 1 || component.tiers.length) {
421
+ fail('search_pricing_unavailable', 'The enabled search unit price could not be verified. Refresh pricing before generation.');
422
+ }
423
+ const expected = options.pricingParameters?.[search.parameter] !== undefined || effectiveInput[search.parameter] !== undefined;
424
+ if (!expected)
425
+ missing.add(search.parameter);
426
+ return { role: search.role, input_parameter: search.input_parameter, usage_parameter: search.parameter,
427
+ assumed_count: String(params[search.parameter]), assumption: expected ? 'expected_usage' : 'zero_searches',
428
+ actual_count_known: false, unit: 'search', unit_price_amounts: amountsForUC(component.rate.uc) };
429
+ });
430
+ const { components, total } = reserved?.needs ? { components: [], total: 0n } : chargeComponents(rule, declared, params, images, missing);
287
431
  if (total > BigInt(Number.MAX_SAFE_INTEGER))
288
432
  fail('invalid_pricing_expression', 'The estimated charge exceeds its supported range.');
289
- const amounts = amountsForUC(String(total)), requestHash = quoteRequestHash(entry.id, effectiveInput, options.mediaSeconds, options.pricingParameters);
433
+ // No media generation is free. A total of 0 comes only from usage given as 0, which then counts as missing, so
434
+ // nothing is quoted; if no usage explains it, the published rules themselves price the input at 0.
435
+ const zeroUsage = total === 0n ? [...declared].filter(name => isUsageParameter(entry.id, name) && pricingParameters?.[name] !== undefined
436
+ && /^\d+(?:\.\d+)?$/.test(String(params[name])) && compareDecimal(String(params[name]), '0') === 0
437
+ && rule.components.some(c => componentReads(c).has(name))) : [];
438
+ if (total === 0n) {
439
+ if (!zeroUsage.length && !missing.size)
440
+ fail('pricing_rules_unavailable', 'The published rules price this input at 0, and no media generation is free, so it cannot be quoted.');
441
+ for (const name of zeroUsage)
442
+ missing.add(name);
443
+ components.length = 0;
444
+ }
445
+ const amounts = amountsForUC(String(total)), requestHash = quoteRequestHash(entry.id, effectiveInput, options.mediaSeconds, pricingParameters);
290
446
  const approval = { source: 'pricing_rules', price_scope: 'public_default', model_id: entry.id,
291
447
  request_hash: requestHash, total_uc: amounts.uc, expires_at: new Date(Date.now() + APPROVAL_TTL_MS).toISOString(),
292
448
  fingerprint: quoteRequestHash(entry.id, { rules: economicRules(rule), parameters: params,
293
- exchange_rate_version: body.meta.exchange_rate_version, components, missing: [...missing].sort(), total_uc: amounts.uc }) };
294
- const status = missing.size ? components.length ? 'partial' : 'needs_input' : 'estimated';
449
+ exchange_rate_version: body.meta.exchange_rate_version, components, missing: [...missing].sort(), total_uc: amounts.uc,
450
+ ...(reserved?.gpt || reserved?.omni ? { reservation: reserved.gpt ?? reserved.omni } : {}) }) };
451
+ const status = missing.size ? components.length ? 'partial' : 'needs_input'
452
+ : reserved?.gpt || reserved?.omni ? 'token_billed' : 'estimated';
295
453
  const missingUsage = [...missing].sort(), usageHelp = helpLines(missingUsage, entry, rule, declared);
454
+ const usage = reserved?.gpt, omni = reserved?.omni;
455
+ // An Omni input video of unknown resolution counts the highest; the same input at a lower one, for the notes.
456
+ const lowerTier = omni && status === 'token_billed' ? omniLowerInputTier(omni) : undefined;
457
+ let lower;
458
+ if (omni && lowerTier) {
459
+ const alternative = omniReservation(id, effectiveInput, options.mediaSeconds, { countPromptTokens: options.countPromptTokens, inputTier: lowerTier });
460
+ const cost = 'needs' in alternative ? undefined : chargeComponents(rule, declared, { ...params, ...omniParameters(rule, alternative) }, 1n, new Set()).total;
461
+ if (cost !== undefined && cost < total)
462
+ lower = { tier: lowerTier, amounts: amountsForUC(String(cost)) };
463
+ }
296
464
  const estimate = { status,
297
465
  // Nothing could be priced: a zero amount would read as free.
298
466
  ...(status === 'needs_input' ? {} : { min_usd: Number(amounts.usd), max_usd: Number(amounts.usd),
299
467
  min_credits: Number(amounts.credits), max_credits: Number(amounts.credits) }),
300
468
  total_known: status === 'estimated',
301
- basis: ['Published full pricing rules evaluated for the supplied generation parameters; exact UC rounding and component minimums.'],
469
+ basis: [status === 'token_billed' && usage
470
+ ? `Reference price: published token rates applied to what EvoLink reserves at submission for this input. Per image: ${usage.per_image.image_output_tokens.toLocaleString('en-US')} output tokens (${usage.output.width}×${usage.output.height}${usage.output.gif ? `, ${usage.output.gif.frames} GIF frames` : ''}, quality ${usage.output.quality}), about ${usage.per_image.text_input_tokens.toLocaleString('en-US')} prompt tokens and ${usage.per_image.image_input_tokens.toLocaleString('en-US')} reference-image tokens, each part rounded up; ${usage.images} image${usage.images > 1 ? 's' : ''}.`
471
+ : status === 'token_billed' && omni ? omniBasis(omni)
472
+ : 'Published full pricing rules evaluated for the supplied generation parameters; exact UC rounding and component minimums.'],
302
473
  ...(missing.size ? { uncheckable_reason: 'usage', missing_usage: missingUsage, usage_help: usageHelp } : {}),
474
+ ...(status === 'token_billed' && usage ? { reference_usage: usage } : {}),
475
+ ...(status === 'token_billed' && omni ? { reference_usage: { ...omni, ...(lower ? { lower_input: { resolution: lower.tier, amounts: lower.amounts } } : {}) } } : {}),
303
476
  possible_extras: status === 'partial' ? usageHelp.map(line => `Additional charge depends on ${line}`) : [],
304
- notes: ['Public default prices; account discounts are not included.', status === 'needs_input'
305
- ? 'No total is quoted until the missing usage is known, and generate_* will not submit before then.'
306
- : 'Confirm the estimated cost before generation. Actual billed usage and final charges may differ.'] };
477
+ notes: ['Public default prices; account discounts are not included.', ...status === 'needs_input'
478
+ ? ['No total is quoted until the missing usage is known, and generate_* will not submit before then.']
479
+ : status === 'token_billed' && usage ? reservationNotes(usage, ignored)
480
+ : status === 'token_billed' && omni ? omniNotes(omni, ignored, lower)
481
+ : ['Confirm the estimated cost before generation. Actual billed usage and final charges may differ.']] };
482
+ if (zeroUsage.length)
483
+ estimate.notes.push(`pricing_parameters ${zeroUsage.join(', ')} given as 0 would price this generation at 0. No media generation is free, so ${zeroUsage.length > 1 ? 'they count' : 'it counts'} as missing.`);
484
+ if (ignored.length && status !== 'token_billed')
485
+ estimate.notes.push(`pricing_parameters ${ignored.join(', ')} ${ignored.length > 1 ? 'are' : 'is'} not used for this model.`);
307
486
  for (const p of rule.parameters ?? []) {
308
487
  const assumed = CONSERVATIVE_QUOTE_PARAMETERS[`${entry.id.toLowerCase()} ${p.name}`];
309
488
  if (assumed && options.pricingParameters?.[p.name] === undefined)
@@ -325,6 +504,8 @@ export function calculateRulesEstimate(body, entry, input, options = {}) {
325
504
  export const RECENT_RULES_MAX_AGE_MS = 10 * 60_000;
326
505
  /** The longest Retry-After a generation waits, once, before its fresh rules read gives up. */
327
506
  export const GENERATION_RULES_RETRY_MAX_SECONDS = 5;
507
+ /** Generation takes a model's rules read this recently (and still fresh), so a batch of submissions reads them once. */
508
+ export const GENERATION_RULES_REUSE_MS = 10_000;
328
509
  const limited = (error) => error instanceof PricingRulesError && error.code === 'rate_limit_exceeded';
329
510
  function pause(ms, signal) {
330
511
  return new Promise(resolve => {
@@ -337,7 +518,7 @@ function pause(ms, signal) {
337
518
  }
338
519
  async function generationRules(model, signal) {
339
520
  try {
340
- return (await getPricingRules({ model, view: 'full' }, { fresh: true })).body;
521
+ return (await getPricingRules({ model, view: 'full' }, { fresh: true, maxAgeMs: GENERATION_RULES_REUSE_MS })).body;
341
522
  }
342
523
  catch (error) {
343
524
  const wait = limited(error) ? error.retryAfter ?? 1 : undefined;
@@ -346,40 +527,58 @@ async function generationRules(model, signal) {
346
527
  await pause(wait * 1000, signal);
347
528
  if (signal?.aborted)
348
529
  throw error;
349
- return (await getPricingRules({ model, view: 'full' }, { fresh: true })).body;
530
+ return (await getPricingRules({ model, view: 'full' }, { fresh: true, maxAgeMs: GENERATION_RULES_REUSE_MS })).body;
350
531
  }
351
532
  }
352
533
  /**
353
- * Generation reads the rules fresh. A hosted estimate (`reuseRules`) reuses them until their fresh_until and, while
354
- * the platform limits requests, may use rules read in the last 10 minutes; any other estimate reads them fresh. An
355
- * approval from cached or recent rules can never submit at a changed price: checkRulesApproval refuses it.
534
+ * The rules an estimate or a generation evaluates. Generation reads them fresh, or takes them from a read in the last
535
+ * 10 seconds. A hosted estimate (`reuseRules`) reuses them until their fresh_until and, while the platform limits
536
+ * requests, may use rules read in the last 10 minutes (`readAt`); any other estimate reads them fresh. A batch reads
537
+ * them once for all its inputs.
356
538
  */
357
- export async function createRulesEstimate(entry, input, options = {}) {
539
+ export async function readPricingRulesFor(entry, options = {}) {
358
540
  const model = entry.id.toLowerCase();
359
541
  if (options.purpose === 'generation')
360
- return calculateRulesEstimate(await generationRules(model, options.signal), entry, input, options);
542
+ return { body: await generationRules(model, options.signal) };
361
543
  if (!options.reuseRules)
362
- return calculateRulesEstimate((await getPricingRules({ model, view: 'full' }, { fresh: true })).body, entry, input, options);
544
+ return { body: (await getPricingRules({ model, view: 'full' }, { fresh: true })).body };
363
545
  try {
364
- const { body } = await getPricingRules({ model, view: 'full' }, { reuseUntilFresh: true });
365
- return calculateRulesEstimate(body, entry, input, options);
546
+ return { body: (await getPricingRules({ model, view: 'full' }, { reuseUntilFresh: true })).body };
366
547
  }
367
548
  catch (error) {
368
549
  const recent = limited(error) ? recentModelRules(model, RECENT_RULES_MAX_AGE_MS) : undefined;
369
550
  if (!recent)
370
551
  throw error;
371
- const result = calculateRulesEstimate(recent.body, entry, input, options), readAt = new Date(recent.fetchedAt).toISOString();
372
- result.estimate.notes.push(`The platform is limiting pricing requests right now, so this estimate uses the published rules read at ${readAt}. generate_* reads the current rules again before submitting and asks for a new approval if the price changed.`);
373
- return { ...result, rules_read_at: readAt };
552
+ return { body: recent.body, readAt: new Date(recent.fetchedAt).toISOString() };
374
553
  }
375
554
  }
555
+ /** Said with an estimate made from rules read earlier, while the platform limits pricing requests. */
556
+ export function recentRulesNote(readAt) {
557
+ return `The platform is limiting pricing requests right now, so this estimate uses the published rules read at ${readAt}. generate_* reads the current rules again before submitting and asks for a new approval if the price changed.`;
558
+ }
559
+ /** An approval from cached or recent rules can never submit at a changed price: checkRulesApproval refuses it. */
560
+ export async function createRulesEstimate(entry, input, options = {}) {
561
+ const { body, readAt } = await readPricingRulesFor(entry, options);
562
+ const result = calculateRulesEstimate(body, entry, input, options);
563
+ if (!readAt)
564
+ return result;
565
+ result.estimate.notes.push(recentRulesNote(readAt));
566
+ return { ...result, rules_read_at: readAt };
567
+ }
568
+ /**
569
+ * An approval holds for the same input at the same price. Past its expires_at it still holds when neither changed
570
+ * (`expired: true`, for the result to say so); a changed input or price needs a new estimate and approval.
571
+ */
376
572
  export function checkRulesApproval(approval, fresh) {
377
- if (Date.parse(approval.expires_at) <= Date.now())
378
- fail('quote_expired', 'The approved estimate expired. Estimate again and obtain approval.');
573
+ const expired = Date.parse(approval.expires_at) <= Date.now();
574
+ if (approval.batch_items !== undefined) {
575
+ fail('quote_input_changed', 'This pricing_quote approves a batch (inputs); pass the same inputs, or estimate this input and obtain approval.');
576
+ }
379
577
  if (approval.request_hash !== fresh.approval.request_hash || approval.model_id !== fresh.approval.model_id) {
380
578
  fail('quote_input_changed', 'The generation input differs from the approved estimate.');
381
579
  }
382
580
  if (approval.fingerprint !== fresh.approval.fingerprint || approval.total_uc !== fresh.approval.total_uc) {
383
581
  fail('price_changed', 'The pricing rules or estimated price changed. Estimate again and obtain approval.');
384
582
  }
583
+ return { expired };
385
584
  }