craterview 0.4.27 → 0.4.31

package/README.md

@@ -152,7 +152,7 @@ above tells the two apart.
 
 | Class | Meaning |
 |---|---|
-| `RateLimited` | 429 — one of five limits, and `.code` says which: `rate_limited` (the key's request rate), `too_many_uploads`, `too_many_keys`, `too_many_jobs` or `queue_full`. `.retryAfter` is seconds to wait: until the window rolls over for the two per-minute limits, until a new key can be made for the hourly one, or an interval to poll on for the other two. |
+| `RateLimited` | 429 — one of five limits, and `.code` says which: `rate_limited` (the account's request rate), `too_many_uploads`, `too_many_keys`, `too_many_jobs` or `queue_full`. `.retryAfter` is seconds to wait: until the window rolls over for the two per-minute limits, until a new key can be made for the hourly one, or an interval to poll on for the other two. |
 | `JobFailed` | The job ran and did not succeed. `.message` says what you can do about it; `.errorCode` is the half to branch on; `.jobId` is the job. |
 | `InvalidSignature` | A webhook delivery did not verify. Do not act on its body. |
 | `CraterViewError` | Everything else, including 4xx and 5xx from the API, and storage refusing an upload or a download. |
@@ -187,8 +187,9 @@ result's file are getters onto `result.output` rather than separate fields — t
 those links once. A model with no file to hand back returns its answer in `result` and leaves
 every one of them null; the fields it answers with are its `result_schema` in `cv.models()`.
 
-`credits` is the only figure about cost the API states, and the price is fixed and published
-per model, so an invoice reconciles against `credits` alone. For how long a job took, subtract
+`credits` is the only figure about cost the API states, and each model publishes its price in
+`cv.models()` — `credits_per_image`, and `credit_steps` where a smaller image costs less — so
+an invoice reconciles against `credits` alone. For how long a job took, subtract
 `createdAt` from `finishedAt` — that is the wait you had, queue included.
 
 **Uploads declare their size.** `upload()` and `run()` take the length from the `Blob`
@@ -197,8 +198,8 @@ accepts exactly that length and nothing else. You do not pass it — it is read
 in hand, which is what makes it impossible to get wrong.
 
 **Running out of credit does not stop you.** A job submitted against a balance of zero is
-accepted and run, and charged when it succeeds — it goes to the community queue, which runs
-on shared, free capacity and can wait longer at busy times. It comes back with `community`
+accepted, and unless a subscription has work left this period it runs free on the community
+queue, which runs on shared, free capacity and can wait longer at busy times. It comes back with `community`
 set, and `usage()` reports the same flag for your next job before you send it. There is no
 payment error to handle: paying — with credit, or with a subscription — moves work onto paid
 compute that scales with demand, rather than buying the right to submit.

package/index.ts

@@ -18,7 +18,7 @@ import { imageSize } from "image-size";
 // Mirrored from package.json, which is the number a release bumps. It cannot be imported
 // from there — this ships as TypeScript, so the import would have to resolve in the
 // consumer's toolchain — so test/version.test.ts asserts the two agree.
-export const VERSION = "0.4.27";
+export const VERSION = "0.4.31";
 const DEFAULT_BASE_URL = "https://api.craterview.ai";
 // The server rejects a longer wait outright, so asking for one costs a 422 rather than the
 // wait you asked for. `run()` clamps to this rather than letting that happen.
@@ -154,7 +154,8 @@ export class CraterViewError extends Error {
  * says which — `rate_limited`, `too_many_keys`, `too_many_uploads`, `too_many_jobs` or
  * `queue_full`, in this order:
  *
- * - the key's request rate, per minute;
+ * - the account's request rate, per minute — counted across all its keys, for submitting
+ *   jobs, creating keys and gallery calls. No other call counts;
  * - the account's new keys, per hour — counted across all its keys, and only from
  *   `createKey`;
  * - the account's upload URLs, per minute — counted across all its keys;
@@ -436,8 +437,23 @@ export interface ModelInfo {
    * runs, as `input_too_small`, and is not charged. The same for every key.
    */
   min_input_side: number;
-  /** Whole credits. The price is flat and knowable before you send anything. */
+  /**
+   * Whole credits: what one still image costs, or the most one costs where `credit_steps`
+   * charges less for a smaller one. Knowable before you send anything.
+   */
   credits_per_image: number;
+  /**
+   * A lower price for a smaller still image, or null where every one costs
+   * `credits_per_image`. `by` is `megapixels` — the part of the image a job works on, the
+   * region you name with `roi` or the whole image, in millions of pixels, divided by 4 at
+   * `binning` 2x2, 9 at 3x3 and 16 at 4x4 — or `faces`, the faces the model redraws, counted
+   * when the job finishes. A still costs the first step its measure is at or under, and
+   * `credits_per_image` past the last.
+   */
+  credit_steps?: {
+    by: "megapixels" | "faces";
+    steps: { up_to: number; credits: number }[];
+  } | null;
   /** Whole credits. Null means this model takes stills only. */
   credits_per_video_second?: number | null;
   reference_fps: number;
@@ -480,7 +496,6 @@ export interface KeyInfo {
   created_at: string | null;
   /** When it stopped working, or null while it still does. */
   revoked_at?: string;
-  rate_limit_per_minute: number;
   /**
    * Whether this is the key you are calling with. It cannot be revoked by id while it is;
    * `DELETE /v1/keys/current` ends it on request, unless it is the account's only way
@@ -496,7 +511,6 @@ export interface NewKey {
   key: string;
   prefix: string;
   name: string;
-  rate_limit_per_minute: number;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craterview",
-  "version": "0.4.27",
+  "version": "0.4.31",
   "dependencies": {
     "image-size": "^2.0.4"
   },