@evolinkai/cli 0.13.0 → 0.14.1

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 (29) hide show
  1. package/README.md +22 -7
  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 +185 -36
  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 +258 -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 +320 -70
  21. package/src/platform/core/src/services/qwen-tts-tokens.js +187 -0
  22. package/src/platform/core/src/tool-guidance.js +25 -2
  23. package/src/platform/core/src/tools/estimate-cost.js +203 -61
  24. package/src/platform/core/src/tools/generate.js +498 -75
  25. package/src/platform/core/src/tools/get-model.js +15 -3
  26. package/src/platform/core/src/tools/get-pricing-rules.js +4 -3
  27. package/src/platform/core/src/tools/shared.js +1 -1
  28. package/src/platform/core/src/version.js +1 -1
  29. package/src/platform/source.json +43 -35
@@ -2,17 +2,22 @@
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, omniInputTiers, omniLowerInputTier, omniQuotedTier, omniReservation } from './omni-tokens.js';
11
+ import { isQwenTTSModel, qwenTTSInput, qwenTTSReservation } from './qwen-tts-tokens.js';
9
12
  /**
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.
13
+ * How long an approval from estimate_cost holds: 24 hours from the estimate. The rules' own `fresh_until`
14
+ * is a short refresh window (minutes); people confirming a price in a chat may come back much
15
+ * later. generate_* re-evaluates the current rules every time: it refuses an approval past this
16
+ * time (`quote_expired`) or one whose price rose (`price_changed`), and submits at an unchanged or
17
+ * lower price (checkRulesApproval). The gateway keeps a request ID for 24 hours, so a retry under
18
+ * one approval is still within that window of the first submission.
14
19
  */
15
- export const APPROVAL_TTL_MS = 30 * 60_000;
20
+ export const APPROVAL_TTL_MS = 24 * 60 * 60_000;
16
21
  function fail(code, message) { throw new QuoteError(code, message); }
17
22
  function gcd(a, b) { while (b)
18
23
  [a, b] = [b, a % b]; return a < 0n ? -a : a; }
@@ -71,12 +76,25 @@ export function amountsForUC(uc) {
71
76
  const a = decimal(uc);
72
77
  return { uc, credits: display(div(a, rat(10000n)), 4), cny: display(div(a, rat(100000n)), 5), usd: display(div(a, rat(680000n)), 8) };
73
78
  }
74
- export function rulesBudgetExceeded(uc, budget) {
79
+ function budgetUC(budget) {
75
80
  // String(number) may use scientific notation for a small, explicit budget.
76
81
  const [mantissa, exp = '0'] = String(budget).split('e');
77
82
  const power = Number(exp), b = decimal(mantissa);
78
83
  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;
84
+ return mul(value, rat(680000n));
85
+ }
86
+ export function rulesBudgetExceeded(uc, budget) {
87
+ return cmp(decimal(uc), budgetUC(budget)) > 0;
88
+ }
89
+ /**
90
+ * A token-billed reference price fits a budget only with room for the tokens a task actually uses: 1.5 times the
91
+ * reference must fit. The largest overrun on record is 20% (gpt-image-2, 4K high); large reference images are unmeasured.
92
+ */
93
+ export const REFERENCE_BUDGET_FACTOR = '1.5';
94
+ /** The amount a budget has to cover for a reference price, for messages. */
95
+ export function referenceAllowance(uc) { return amountsForUC(display(mul(decimal(uc), decimal(REFERENCE_BUDGET_FACTOR)), 4)); }
96
+ export function referenceBudgetExceeded(uc, budget) {
97
+ return cmp(mul(decimal(uc), decimal(REFERENCE_BUDGET_FACTOR)), budgetUC(budget)) > 0;
80
98
  }
81
99
  const arity = { constant: [0, 0], variable: [0, 0], lookup: [0, 0],
82
100
  add: [2, 32], multiply: [2, 32], subtract: [2, 2], divide: [2, 2], min: [2, 32], max: [2, 32], clamp: [3, 3],
@@ -117,6 +135,8 @@ function componentReads(c) {
117
135
  }
118
136
  /** How to give a usage value an estimate lacks, or why only the finished task knows it. */
119
137
  function usageHint(name, entry, declared) {
138
+ if (name === 'media_seconds')
139
+ 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
140
  if (name === 'input_seconds' || name === 'first_input_video_seconds')
121
141
  return 'pass the length of the input video or audio, in seconds, as media_seconds.';
122
142
  if (name === 'source_output_seconds')
@@ -147,9 +167,143 @@ function helpLines(names, entry, rule, declared) {
147
167
  }
148
168
  /** Every usage value a rule can bill by, with how to give it; get_model lists them before any estimate. */
149
169
  export function billingUsageHelp(rule, entry) {
170
+ if (reservesTokens(rule, entry))
171
+ return [];
150
172
  const declared = new Set((rule.parameters ?? []).map(p => p.name));
151
173
  return helpLines([...declared].filter(name => isUsageParameter(entry.id, name)).sort(), entry, rule, declared);
152
174
  }
175
+ // GPT Image, Gemini Omni and Qwen TTS token models: the reference price counts the tokens the gateway reserves at
176
+ // submission for the input.
177
+ const RESERVED_TOKENS = new Set(['image_input_tokens', 'image_cached_input_tokens', 'image_output_tokens',
178
+ 'text_input_tokens', 'text_cached_input_tokens', 'text_output_tokens']);
179
+ const OMNI_TOKENS = new Set(['input_tokens', 'video_output_tokens', 'other_output_tokens']);
180
+ const QWEN_TOKENS = new Set(['input_tokens', 'output_tokens']);
181
+ /** GPT Image 2.6 rules also bill an SVG's author model. SVG output is not quoted, so a reference price uses none. */
182
+ const NO_SVG_AUTHOR = { svg_model: 'none', svg_input_tokens: 0, svg_output_tokens: 0 };
183
+ const svgAuthor = (name) => Object.hasOwn(NO_SVG_AUTHOR, name);
184
+ /** Only a rule billed by these token counts alone, with an output component, can price the reservation. */
185
+ function reservesTokens(rule, entry) {
186
+ const id = entry.id.toLowerCase();
187
+ if (rule.settlement_basis !== 'actual_usage')
188
+ return false;
189
+ if (isOmniTokenModel(id)) {
190
+ return (rule.parameters ?? []).every(p => OMNI_TOKENS.has(p.name))
191
+ && rule.components.some(c => c.role === 'video_output' && c.pricing_status === 'available' && componentReads(c).has('video_output_tokens'));
192
+ }
193
+ if (isQwenTTSModel(id)) {
194
+ return (rule.parameters ?? []).every(p => QWEN_TOKENS.has(p.name))
195
+ && rule.components.some(c => c.role === 'output' && c.pricing_status === 'available' && componentReads(c).has('output_tokens'));
196
+ }
197
+ return isTokenImageModel(id)
198
+ && (rule.parameters ?? []).every(p => RESERVED_TOKENS.has(p.name)
199
+ || svgAuthor(p.name) && (p.name !== 'svg_model' || (p.values ?? p.enum ?? []).includes(NO_SVG_AUTHOR.svg_model)))
200
+ && rule.components.some(c => c.role === 'image_output' && c.pricing_status === 'available' && componentReads(c).has('image_output_tokens'));
201
+ }
202
+ /** How estimate_cost prices a token model, for get_model. */
203
+ export function tokenReferenceHelp(rule, entry) {
204
+ if (!reservesTokens(rule, entry))
205
+ return undefined;
206
+ const rates = rule.components.filter(c => ![...componentReads(c)].some(svgAuthor))
207
+ .map(c => `${c.id} $${c.rate.usd} per ${c.unit === '1k_tokens' ? '1K tokens' : c.unit.replace(/_/g, ' ')}`);
208
+ if (isOmniTokenModel(entry.id.toLowerCase())) {
209
+ 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}) and the estimate also lists the price at each input resolution. The task settles at the tokens it actually uses.`;
210
+ }
211
+ if (isQwenTTSModel(entry.id)) {
212
+ return `Billed by actual token usage. estimate_cost gives a reference price for the exact input: the tokens EvoLink reserves at submission for the text (after hot_fix.replace), an instruction or [tags] and hot_fix, at the published rates (public default rates: ${rates.join('; ')}). It counts each character's worst case, so the task usually settles below it, at the tokens it actually uses.`;
213
+ }
214
+ 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.`;
215
+ }
216
+ /** An Omni or Qwen TTS reservation's tokens as the rule's parameters. */
217
+ const tokenParameters = (rule, tokens) => Object.fromEntries((rule.parameters ?? []).map(p => [p.name, tokens[p.name] ?? 0]));
218
+ const omniParameters = (rule, usage) => tokenParameters(rule, usage.tokens);
219
+ function reservation(rule, entry, input, countPromptTokens, mediaSeconds) {
220
+ if (!reservesTokens(rule, entry))
221
+ return undefined;
222
+ const id = entry.id.toLowerCase();
223
+ if (isOmniTokenModel(id)) {
224
+ const usage = omniReservation(id, input, mediaSeconds, { countPromptTokens });
225
+ return 'needs' in usage ? usage : { omni: usage, parameters: omniParameters(rule, usage) };
226
+ }
227
+ if (isQwenTTSModel(id)) {
228
+ const usage = qwenTTSReservation(input);
229
+ return { qwen: usage, parameters: tokenParameters(rule, usage.tokens) };
230
+ }
231
+ const usage = tokenImageReservation(id, input, countPromptTokens);
232
+ const parameters = {};
233
+ for (const p of rule.parameters ?? []) {
234
+ parameters[p.name] = svgAuthor(p.name) ? NO_SVG_AUTHOR[p.name] : usage.per_image[p.name] ?? 0;
235
+ }
236
+ return { gpt: usage, parameters };
237
+ }
238
+ 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.';
239
+ 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.`;
240
+ function reservationNotes(usage, ignored) {
241
+ const notes = [CONFIRM_REFERENCE];
242
+ const gif = usage.output.gif;
243
+ if (gif)
244
+ 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.`);
245
+ else if (usage.output.size === 'auto')
246
+ 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.');
247
+ if (usage.reference_images)
248
+ notes.push(`Each reference image or mask counts ${INPUT_IMAGE_TOKENS.toLocaleString('en-US')} input tokens; larger reference images can use more.`);
249
+ if (usage.images > 1)
250
+ 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.`);
251
+ notes.push('Prompt tokens are approximated; EvoLink counts them exactly at submission.');
252
+ if (ignored.length)
253
+ notes.push(ignoredNote(ignored));
254
+ return notes;
255
+ }
256
+ const tokenText = (tokens) => tokens.toLocaleString('en-US');
257
+ function omniBasis(usage) {
258
+ const t = usage.tokens, videos = usage.input_videos;
259
+ 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)`];
260
+ if (t.input_tokens) {
261
+ const inputs = [`about ${tokenText(usage.prompt_tokens)} prompt tokens`, ...usage.images ? [`${usage.images} image${usage.images > 1 ? 's' : ''}`] : [],
262
+ ...videos ? [`${videos.count > 1 ? `${videos.count} reference videos of` : 'an input video of'} ${videos.seconds} s at ${videos.resolution}`] : []];
263
+ parts.push(`${tokenText(t.input_tokens)} input tokens (${inputs.join(', ')})`);
264
+ }
265
+ if (t.other_output_tokens)
266
+ parts.push(`${tokenText(t.other_output_tokens)} other output tokens`);
267
+ return `Reference price: published token rates applied to what EvoLink reserves at submission for this input: ${parts.join(', ')}, each part rounded up.`;
268
+ }
269
+ const tierList = (prices) => prices.map(price => `${price.resolution}${price.quoted ? ' (quoted)' : ''}: ${price.amounts.credits} credits (about $${price.amounts.usd})`).join('; ');
270
+ function omniNotes(usage, ignored, prices) {
271
+ const notes = [CONFIRM_REFERENCE];
272
+ const videos = usage.input_videos;
273
+ if (videos?.resolution_assumed) {
274
+ 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.${prices.length ? ` If the ${videos.count > 1 ? 'reference videos are' : 'input video is'} ${tierList(prices)}.` : ''}`);
275
+ const output = usage.output.resolution;
276
+ if (!usage.output.follows_input && output !== '360p')
277
+ notes.push(`An input video at or below the output resolution, ${output}, reserves the same as one at ${output}.`);
278
+ }
279
+ if (usage.upscale?.source_assumed) {
280
+ 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}.${prices.length ? ` If the source video is ${tierList(prices)}.` : ''}`);
281
+ }
282
+ if (videos && usage.route !== 'upscale')
283
+ 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.`);
284
+ if (usage.output.follows_input)
285
+ notes.push('quality is auto, so the output follows the input video\'s resolution.');
286
+ if (usage.images)
287
+ notes.push(`Each input image counts ${tokenText(OMNI_IMAGE_TOKENS)} input tokens.`);
288
+ if (usage.prompt_tokens)
289
+ notes.push('Prompt tokens are approximated; EvoLink counts them exactly at submission.');
290
+ if (ignored.length > 0)
291
+ notes.push(ignoredNote(ignored));
292
+ return notes;
293
+ }
294
+ function qwenBasis(usage) {
295
+ return `Reference price: published token rates applied to what EvoLink reserves at submission for this input: ${tokenText(usage.tokens.input_tokens)} input tokens and ${tokenText(usage.tokens.output_tokens)} output tokens for ${tokenText(usage.characters)} characters of text${usage.hot_fix_characters ? ' and hot_fix' : ''}, each part rounded up.`;
296
+ }
297
+ function qwenNotes(usage, ignored) {
298
+ const notes = [CONFIRM_REFERENCE, 'EvoLink reserves the most each kind of character uses (Han characters, letters without case, lowercase letters, spaces and punctuation, other characters), so the task usually settles below the reference price.'];
299
+ if (usage.expressive)
300
+ notes.push('An instruction or a [tag] in the text raises the reserved output tokens.');
301
+ if (usage.hot_fix_characters)
302
+ notes.push('The text is counted after hot_fix.replace, as it is synthesized; hot_fix itself also counts toward the input tokens.');
303
+ if (ignored.length > 0)
304
+ notes.push(ignoredNote(ignored));
305
+ return notes;
306
+ }
153
307
  function evaluate(node, params) {
154
308
  const nodes = node.args ?? [], at = (i) => evaluate(nodes[i], params), number = (i) => numeric(at(i));
155
309
  switch (node.op) {
@@ -201,42 +355,11 @@ function evaluate(node, params) {
201
355
  default: return fail('invalid_pricing_expression', 'The pricing rule uses an unsupported operation.');
202
356
  }
203
357
  }
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();
358
+ /** The rule's components for these parameters: each subtotal rounded and at least its minimum, times count. */
359
+ function chargeComponents(rule, declared, params, images, missing) {
224
360
  const components = [];
361
+ const ids = new Set();
225
362
  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
363
  for (const c of rule.components) {
241
364
  if (ids.has(c.id) || !c.quantity_rule || !c.rounding)
242
365
  fail('invalid_pricing_expression', 'The pricing rule is incomplete or has duplicate components.');
@@ -268,9 +391,9 @@ export function calculateRulesEstimate(body, entry, input, options = {}) {
268
391
  const charge = cmp(subtotal, minimum) < 0 ? minimum : subtotal;
269
392
  if (charge.d !== 1n || charge.n < 0n || charge.n > BigInt(Number.MAX_SAFE_INTEGER))
270
393
  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 });
394
+ total += charge.n * images;
395
+ components.push({ id: c.id, sku_id: selected.sku_id, quantity: exact(mul(q, rat(images))), billed_quantity: exact(mul(billed, rat(images))),
396
+ subtotal_uc: String(charge.n * images), minimum_charge_applied: cmp(subtotal, minimum) < 0 });
274
397
  }
275
398
  catch (error) {
276
399
  if (error instanceof QuoteError && error.code === 'quote_usage_required' && error.param) {
@@ -284,26 +407,126 @@ export function calculateRulesEstimate(body, entry, input, options = {}) {
284
407
  throw error;
285
408
  }
286
409
  }
410
+ return { components, total };
411
+ }
412
+ /** The most inputs one estimate_cost or generate_* call takes (`inputs`), all for one model. */
413
+ export const MAX_BATCH_ITEMS = 50;
414
+ /** `batch_items` marks an approval of a whole batch (inputs); it never approves a single input, nor the reverse. */
415
+ export const ApprovedRulesEstimate = z.object({ source: z.literal('pricing_rules'), price_scope: z.literal('public_default'),
416
+ model_id: z.string().min(1).max(100), request_hash: z.string().regex(/^[a-f0-9]{64}$/),
417
+ fingerprint: z.string().regex(/^[a-f0-9]{64}$/), total_uc: z.string().max(32).regex(/^\d+$/),
418
+ expires_at: z.string().datetime({ offset: true }), batch_items: z.number().int().min(1).max(MAX_BATCH_ITEMS).optional() }).strict();
419
+ function economicRules(rule) {
420
+ // Freshness and configuration timestamps do not change the approved price.
421
+ return { ...rule, components: rule.components.map(({ effective_at, official_rate, ...c }) => ({ ...c,
422
+ tiers: c.tiers.map(({ effective_at, official_rate, ...t }) => t) })) };
423
+ }
424
+ /** countPromptTokens replaces the approximate prompt token count, for comparing with the gateway's exact count. */
425
+ export function calculateRulesEstimate(body, entry, input, options = {}) {
426
+ const rule = 'model' in body ? body.model : body.models.find(model => model.model_id === entry.id);
427
+ if (!rule || rule.model_id !== entry.id.toLowerCase() || rule.modality !== entry.kind || rule.policy_source !== 'published' || rule.pricing_status !== 'available') {
428
+ fail('pricing_rules_unavailable', 'This model has no available published media pricing policy.');
429
+ }
430
+ const prepared = prepareSeedanceInput(entry, qwenTTSInput(entry.id, input));
431
+ if (prepared.errors.length)
432
+ throw new QuoteError('invalid_quote_parameter', `${prepared.errors[0].param} ${prepared.errors[0].problem}`, prepared.errors[0].param);
433
+ const effectiveInput = prepared.input;
434
+ const declared = new Set((rule.parameters ?? []).map(p => p.name));
435
+ const id = entry.id.toLowerCase();
436
+ // GPT Image, Gemini Omni and Qwen TTS token models never use token counts from pricing_parameters: the reference counts
437
+ // what the gateway reserves for this input. Leaving them out of the request hash lets a generation pass them or not.
438
+ const ignored = isTokenImageModel(id) || isOmniTokenModel(id) || isQwenTTSModel(id)
439
+ ? Object.keys(options.pricingParameters ?? {}).filter(name => declared.has(name) && (/tokens$/.test(name) || svgAuthor(name))).sort() : [];
440
+ const pricingParameters = ignored.length
441
+ ? Object.fromEntries(Object.entries(options.pricingParameters).filter(([name]) => !ignored.includes(name))) : options.pricingParameters;
442
+ const reserved = reservation(rule, entry, effectiveInput, options.countPromptTokens, options.mediaSeconds);
443
+ const params = { ...prepareQuoteParameters(rule, entry, effectiveInput, pricingParameters, options.mediaSeconds, true), ...reserved?.parameters };
444
+ // The gateway rounds each image's charge up separately, then reserves it once per image.
445
+ const images = BigInt(reserved?.gpt?.images ?? 1);
446
+ const missing = new Set();
447
+ // An Omni input video is billed by its length, which only media_seconds gives before submission.
448
+ if (reserved?.needs)
449
+ missing.add('media_seconds');
450
+ const searchCharges = searchUsage(entry, effectiveInput).filter(search => search.enabled).map(search => {
451
+ const component = rule.components.find(item => item.role === search.role);
452
+ if (!declared.has(search.parameter) || !component || component.pricing_status !== 'available' || component.unit !== 'search'
453
+ || component.billing_unit_size !== 1 || component.tiers.length) {
454
+ fail('search_pricing_unavailable', 'The enabled search unit price could not be verified. Refresh pricing before generation.');
455
+ }
456
+ const expected = options.pricingParameters?.[search.parameter] !== undefined || effectiveInput[search.parameter] !== undefined;
457
+ if (!expected)
458
+ missing.add(search.parameter);
459
+ return { role: search.role, input_parameter: search.input_parameter, usage_parameter: search.parameter,
460
+ assumed_count: String(params[search.parameter]), assumption: expected ? 'expected_usage' : 'zero_searches',
461
+ actual_count_known: false, unit: 'search', unit_price_amounts: amountsForUC(component.rate.uc) };
462
+ });
463
+ const { components, total } = reserved?.needs ? { components: [], total: 0n } : chargeComponents(rule, declared, params, images, missing);
287
464
  if (total > BigInt(Number.MAX_SAFE_INTEGER))
288
465
  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);
466
+ // No media generation is free. A total of 0 comes only from usage given as 0, which then counts as missing, so
467
+ // nothing is quoted; if no usage explains it, the published rules themselves price the input at 0.
468
+ const zeroUsage = total === 0n ? [...declared].filter(name => isUsageParameter(entry.id, name) && pricingParameters?.[name] !== undefined
469
+ && /^\d+(?:\.\d+)?$/.test(String(params[name])) && compareDecimal(String(params[name]), '0') === 0
470
+ && rule.components.some(c => componentReads(c).has(name))) : [];
471
+ if (total === 0n) {
472
+ if (!zeroUsage.length && !missing.size)
473
+ fail('pricing_rules_unavailable', 'The published rules price this input at 0, and no media generation is free, so it cannot be quoted.');
474
+ for (const name of zeroUsage)
475
+ missing.add(name);
476
+ components.length = 0;
477
+ }
478
+ const amounts = amountsForUC(String(total)), requestHash = quoteRequestHash(entry.id, effectiveInput, options.mediaSeconds, pricingParameters);
290
479
  const approval = { source: 'pricing_rules', price_scope: 'public_default', model_id: entry.id,
291
480
  request_hash: requestHash, total_uc: amounts.uc, expires_at: new Date(Date.now() + APPROVAL_TTL_MS).toISOString(),
292
481
  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';
482
+ exchange_rate_version: body.meta.exchange_rate_version, components, missing: [...missing].sort(), total_uc: amounts.uc,
483
+ ...(reserved?.gpt || reserved?.omni || reserved?.qwen ? { reservation: reserved.gpt ?? reserved.omni ?? reserved.qwen } : {}) }) };
484
+ const status = missing.size ? components.length ? 'partial' : 'needs_input'
485
+ : reserved?.gpt || reserved?.omni || reserved?.qwen ? 'token_billed' : 'estimated';
295
486
  const missingUsage = [...missing].sort(), usageHelp = helpLines(missingUsage, entry, rule, declared);
487
+ const usage = reserved?.gpt, omni = reserved?.omni, qwen = reserved?.qwen;
488
+ // An Omni input video of unknown resolution counts the highest; the same input at each resolution EvoLink can read
489
+ // it at, for the notes. lower_input keeps the one lower price 1.12.0 gave (720p; an upscale: the cheaper source).
490
+ const tierPrices = [];
491
+ if (omni && status === 'token_billed') {
492
+ const quoted = omniQuotedTier(omni);
493
+ for (const tier of omniInputTiers(omni)) {
494
+ const alternative = omniReservation(id, effectiveInput, options.mediaSeconds, { countPromptTokens: options.countPromptTokens, inputTier: tier });
495
+ if ('needs' in alternative)
496
+ continue;
497
+ const cost = chargeComponents(rule, declared, { ...params, ...omniParameters(rule, alternative) }, 1n, new Set()).total;
498
+ tierPrices.push({ resolution: tier, amounts: amountsForUC(String(cost)), ...(tier === quoted ? { quoted: true } : {}) });
499
+ }
500
+ }
501
+ const lowerTier = omni && status === 'token_billed' ? omniLowerInputTier(omni) : undefined;
502
+ const lowerPrice = tierPrices.find(price => price.resolution === lowerTier);
503
+ const lower = lowerPrice && BigInt(lowerPrice.amounts.uc) < total ? { tier: lowerPrice.resolution, amounts: lowerPrice.amounts } : undefined;
296
504
  const estimate = { status,
297
505
  // Nothing could be priced: a zero amount would read as free.
298
506
  ...(status === 'needs_input' ? {} : { min_usd: Number(amounts.usd), max_usd: Number(amounts.usd),
299
507
  min_credits: Number(amounts.credits), max_credits: Number(amounts.credits) }),
300
508
  total_known: status === 'estimated',
301
- basis: ['Published full pricing rules evaluated for the supplied generation parameters; exact UC rounding and component minimums.'],
509
+ basis: [status === 'token_billed' && usage
510
+ ? `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' : ''}.`
511
+ : status === 'token_billed' && omni ? omniBasis(omni)
512
+ : status === 'token_billed' && qwen ? qwenBasis(qwen)
513
+ : 'Published full pricing rules evaluated for the supplied generation parameters; exact UC rounding and component minimums.'],
302
514
  ...(missing.size ? { uncheckable_reason: 'usage', missing_usage: missingUsage, usage_help: usageHelp } : {}),
515
+ ...(status === 'token_billed' && usage ? { reference_usage: usage } : {}),
516
+ ...(status === 'token_billed' && omni ? { reference_usage: { ...omni, ...(lower ? { lower_input: { resolution: lower.tier, amounts: lower.amounts } } : {}),
517
+ ...(tierPrices.length ? { input_resolution_prices: tierPrices } : {}) } } : {}),
518
+ ...(status === 'token_billed' && qwen ? { reference_usage: qwen } : {}),
303
519
  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.'] };
520
+ notes: ['Public default prices; account discounts are not included.', ...status === 'needs_input'
521
+ ? ['No total is quoted until the missing usage is known, and generate_* will not submit before then.']
522
+ : status === 'token_billed' && usage ? reservationNotes(usage, ignored)
523
+ : status === 'token_billed' && omni ? omniNotes(omni, ignored, tierPrices)
524
+ : status === 'token_billed' && qwen ? qwenNotes(qwen, ignored)
525
+ : ['Confirm the estimated cost before generation. Actual billed usage and final charges may differ.']] };
526
+ if (zeroUsage.length)
527
+ 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.`);
528
+ if (ignored.length && status !== 'token_billed')
529
+ estimate.notes.push(`pricing_parameters ${ignored.join(', ')} ${ignored.length > 1 ? 'are' : 'is'} not used for this model.`);
307
530
  for (const p of rule.parameters ?? []) {
308
531
  const assumed = CONSERVATIVE_QUOTE_PARAMETERS[`${entry.id.toLowerCase()} ${p.name}`];
309
532
  if (assumed && options.pricingParameters?.[p.name] === undefined)
@@ -325,6 +548,8 @@ export function calculateRulesEstimate(body, entry, input, options = {}) {
325
548
  export const RECENT_RULES_MAX_AGE_MS = 10 * 60_000;
326
549
  /** The longest Retry-After a generation waits, once, before its fresh rules read gives up. */
327
550
  export const GENERATION_RULES_RETRY_MAX_SECONDS = 5;
551
+ /** Generation takes a model's rules read this recently (and still fresh), so a batch of submissions reads them once. */
552
+ export const GENERATION_RULES_REUSE_MS = 10_000;
328
553
  const limited = (error) => error instanceof PricingRulesError && error.code === 'rate_limit_exceeded';
329
554
  function pause(ms, signal) {
330
555
  return new Promise(resolve => {
@@ -337,7 +562,7 @@ function pause(ms, signal) {
337
562
  }
338
563
  async function generationRules(model, signal) {
339
564
  try {
340
- return (await getPricingRules({ model, view: 'full' }, { fresh: true })).body;
565
+ return (await getPricingRules({ model, view: 'full' }, { fresh: true, maxAgeMs: GENERATION_RULES_REUSE_MS })).body;
341
566
  }
342
567
  catch (error) {
343
568
  const wait = limited(error) ? error.retryAfter ?? 1 : undefined;
@@ -346,40 +571,65 @@ async function generationRules(model, signal) {
346
571
  await pause(wait * 1000, signal);
347
572
  if (signal?.aborted)
348
573
  throw error;
349
- return (await getPricingRules({ model, view: 'full' }, { fresh: true })).body;
574
+ return (await getPricingRules({ model, view: 'full' }, { fresh: true, maxAgeMs: GENERATION_RULES_REUSE_MS })).body;
350
575
  }
351
576
  }
352
577
  /**
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.
578
+ * The rules an estimate or a generation evaluates. Generation reads them fresh, or takes them from a read in the last
579
+ * 10 seconds. A hosted estimate (`reuseRules`) reuses them until their fresh_until and, while the platform limits
580
+ * requests, may use rules read in the last 10 minutes (`readAt`); any other estimate reads them fresh. A batch reads
581
+ * them once for all its inputs.
356
582
  */
357
- export async function createRulesEstimate(entry, input, options = {}) {
583
+ export async function readPricingRulesFor(entry, options = {}) {
358
584
  const model = entry.id.toLowerCase();
359
585
  if (options.purpose === 'generation')
360
- return calculateRulesEstimate(await generationRules(model, options.signal), entry, input, options);
586
+ return { body: await generationRules(model, options.signal) };
361
587
  if (!options.reuseRules)
362
- return calculateRulesEstimate((await getPricingRules({ model, view: 'full' }, { fresh: true })).body, entry, input, options);
588
+ return { body: (await getPricingRules({ model, view: 'full' }, { fresh: true })).body };
363
589
  try {
364
- const { body } = await getPricingRules({ model, view: 'full' }, { reuseUntilFresh: true });
365
- return calculateRulesEstimate(body, entry, input, options);
590
+ return { body: (await getPricingRules({ model, view: 'full' }, { reuseUntilFresh: true })).body };
366
591
  }
367
592
  catch (error) {
368
593
  const recent = limited(error) ? recentModelRules(model, RECENT_RULES_MAX_AGE_MS) : undefined;
369
594
  if (!recent)
370
595
  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 };
596
+ return { body: recent.body, readAt: new Date(recent.fetchedAt).toISOString() };
374
597
  }
375
598
  }
599
+ /** Said with an estimate made from rules read earlier, while the platform limits pricing requests. */
600
+ export function recentRulesNote(readAt) {
601
+ 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 rose.`;
602
+ }
603
+ /** An approval from cached or recent rules can never submit at a higher price: checkRulesApproval refuses it. */
604
+ export async function createRulesEstimate(entry, input, options = {}) {
605
+ const { body, readAt } = await readPricingRulesFor(entry, options);
606
+ const result = calculateRulesEstimate(body, entry, input, options);
607
+ if (!readAt)
608
+ return result;
609
+ result.estimate.notes.push(recentRulesNote(readAt));
610
+ return { ...result, rules_read_at: readAt };
611
+ }
612
+ /** An approval holds until its expires_at, not at it. */
613
+ export const approvalExpired = (approval, now = Date.now()) => Date.parse(approval.expires_at) <= now;
614
+ /**
615
+ * Only a higher total needs a new approval: an unchanged or lower one submits, whatever else changed in the rules. A
616
+ * partial estimate's total is the part it prices.
617
+ */
618
+ export const priceRose = (approval, fresh) => BigInt(fresh.total_uc) > BigInt(approval.total_uc);
619
+ /**
620
+ * An approval holds for the same input until its expires_at, at the approved price or lower. A changed input
621
+ * (quote_input_changed), an expired approval (quote_expired) or a higher price (price_changed) needs a new estimate and
622
+ * approval.
623
+ */
376
624
  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.');
625
+ if (approval.batch_items !== undefined) {
626
+ fail('quote_input_changed', 'This pricing_quote approves a batch (inputs); pass the same inputs, or estimate this input and obtain approval.');
627
+ }
379
628
  if (approval.request_hash !== fresh.approval.request_hash || approval.model_id !== fresh.approval.model_id) {
380
629
  fail('quote_input_changed', 'The generation input differs from the approved estimate.');
381
630
  }
382
- if (approval.fingerprint !== fresh.approval.fingerprint || approval.total_uc !== fresh.approval.total_uc) {
383
- fail('price_changed', 'The pricing rules or estimated price changed. Estimate again and obtain approval.');
384
- }
631
+ if (approvalExpired(approval))
632
+ fail('quote_expired', `The approved estimate expired at ${approval.expires_at}. Estimate again and obtain approval.`);
633
+ if (priceRose(approval, fresh.approval))
634
+ fail('price_changed', 'The estimated price rose after it was approved. Estimate again and obtain approval.');
385
635
  }