corent-sdk 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Corent SDK
 
-One API for AI **image, video, and voice** generation. You pick a quality tier; Corent's router picks the best live model, reroutes failures, verifies the output, and returns the exact charge on every response. Failed generations are never billed.
+One API for AI **image, video, voice, and text** generation. You pick a quality tier; Corent's router picks the best live model, reroutes failures, verifies the output, and returns the exact charge on every response. Failed generations are never billed.
 
 ```bash
 npm install corent-sdk
@@ -26,6 +26,9 @@ console.log(video.url, video.resolution, video.costCents);
 
 const speech = await client.speech.generate("Welcome to Corent.");
 console.log(speech.url, speech.costCents);
+
+const answer = await client.text.generate("Name three uses for a paperclip.", { tier: "premium" });
+console.log(answer.text, answer.costCents);
 ```
 
 ## What the SDK handles for you
@@ -35,14 +38,136 @@ console.log(speech.url, speech.costCents);
 - **Backoff** — 429/5xx retried with `Retry-After` respected.
 - **Honest receipts** — `width`/`height` are the *measured* pixels of the delivered file; `costCents` is the exact charge.
 
+## Pick a model yourself (direct access)
+
+Pass `model` instead of `tier` to pin an exact model. It is never substituted:
+if that model can't deliver, the call fails and you are not charged.
+
+```ts
+const image = await client.images.generate("a lighthouse at dusk", { model: "corent-flux-schnell" });
+console.log(image.model); // "corent-flux-schnell" — the name you asked for
+
+await client.models(); // the menu: every model with its kind, quality and live status
+```
+
+Each model has one name, published as `corent-` + the model: `corent-flux-schnell`,
+`corent-seedance-2.0`, `corent-claude-opus-5`. That is the spelling `client.models()`
+lists and the one every receipt echoes back. Older spellings you may already have
+hard-coded (`flux-schnell`, `seedream-5.0-direct`) keep working — the API accepts
+them and answers with the published name.
+
+When we can reach a model by more than one route, Corent serves whichever is
+cheapest at that moment and charges you that price — you never have to shop
+between near-identical entries.
+
+## Text (language models)
+
+Every frontier lab on one key and one bill, priced per token.
+
+```ts
+const answer = await client.text.generate("Explain reserve-then-settle billing.", {
+  system: "Answer in two sentences.",
+  tier: "premium",
+});
+console.log(answer.text, answer.promptTokens, answer.completionTokens, answer.costCents);
+
+// a real conversation, tool calls included
+const reply = await client.text.chat(
+  [
+    { role: "system", content: "Be terse." },
+    { role: "user", content: "What's the weather?" },
+  ],
+  { model: "corent-claude-opus-5" },
+);
+```
+
+Streaming isn't wrapped here: point any OpenAI-compatible client at
+`https://api.corent.tech/v1` with your Corent key and it works as-is.
+
+## Keep a character or product consistent
+
+Pass 1–4 reference images and the prompt is applied as an *edit* of them, so
+the same face, character, or product carries into a new scene.
+
+```ts
+const shot = await client.images.generate("the same woman, now on a beach", {
+  tier: "pro", // edit-capable models sit at premium and up
+  referenceImageUrls: ["https://cdn.example/her.png"],
+});
+```
+
+`air` and `lite` cannot do this and say so with a 400.
+`client.tiers()` reports `capabilities.supports_reference_images` per tier.
+
+## Batches and webhooks
+
+```ts
+// Up to 50 renders in one call. Each item bills at the normal rate.
+const batch = await client.batches.images(
+  [{ prompt: "a fox", tier: "air" }, { prompt: "a heron", tier: "air" }],
+  { idempotencyKey: "campaign-9" }, // a retry replays instead of re-billing
+);
+const progress = await client.batches.progress(batch.batchId);
+
+// Or have the server deliver each result and skip polling entirely.
+await client.videos.generate("a drone shot", {
+  tier: "premium",
+  webhookUrl: "https://your-server.com/webhooks/corent",
+  webhookSecret: "your_shared_secret", // signs every delivery
+});
+```
+
+## What else you can ask for
+
+```ts
+// Repeat an image exactly, then change one thing.
+const first = await client.images.generate("a fox in a library", { tier: "pro" });
+const again = await client.images.generate("a fox in a library, wearing glasses", {
+  tier: "pro", seed: 12345, negativePrompt: "text, watermark",
+});
+
+// Four versions of one prompt in one call (four real renders, four charges).
+const { images, totalCostCents } = await client.images.generateMany("a fox", 4, { tier: "air" });
+
+// A transparent logo, at a size you choose.
+await client.images.generate("a minimal fox mark", { transparent: true, width: 1024, height: 1024 });
+
+// Video with sound, going from one picture to another.
+await client.videos.generate("the camera pulls back", {
+  tier: "premium", audio: true,
+  imageUrl: "https://.../start.png", endImageUrl: "https://.../end.png",
+  camera: "zoom_out",
+});
+
+// Pick a voice, and shape how it reads.
+const voices = await client.voices();
+await client.speech.generate("Welcome aboard.", {
+  voiceId: voices[0].voice_id, stability: 0.3, speed: 1.1,
+});
+
+// Started something by mistake? Stop it. Costs nothing.
+await client.jobs.cancel(job.id);
+```
+
+`audio: true` routes only to models that actually render sound, so a silent
+model can never quietly serve the request. Not every model takes every
+setting: anything the chosen one could not honour comes back in
+`meta.unsupported_options` rather than being silently ignored.
+
 ## Fine-grained control
 
 ```ts
 const job = await client.images.generate("...", { tier: "max_pro", wait: false });
 const done = await client.jobs.wait(job.id); // resume any time
 
-await client.tiers();        // live catalog with honest min–max price ranges
-await client.balanceCents(); // prepaid balance
+await client.tiers();    // live catalog with honest min–max price ranges
+await client.models();   // direct-access menu with per-model prices
+await client.balance();  // { balanceCents, heldCents, availableCents }
+await client.usage();    // what this account has spent
 ```
 
-Tiers: `air` | `lite` | `premium` | `pro` | `max_pro` — see [corent.tech/pricing](https://corent.tech/pricing). Docs: [corent.tech/docs](https://corent.tech/docs). MCP server for agents: [`corent-mcp`](https://www.npmjs.com/package/corent-mcp).
+Every generate call sends an `Idempotency-Key`, so the SDK's own retries can
+never double-charge. Pass your own `idempotencyKey` to make that survive a
+process restart too.
+
+Tiers: `air` | `lite` | `premium` | `pro` | `max_pro` — see [corent.tech/pricing](https://corent.tech/pricing). Models: [corent.tech/models](https://corent.tech/models). Docs: [corent.tech/docs](https://corent.tech/docs). MCP server for agents: [`corent-mcp`](https://www.npmjs.com/package/corent-mcp).

package/dist/index.cjs

@@ -31,6 +31,8 @@ var DEFAULT_BASE_URL = "https://api.corent.tech";
 var MAX_RETRIES = 3;
 var POLL_INTERVAL_MS = 3e3;
 var DEFAULT_WAIT_TIMEOUT_MS = 9e5;
+var MAX_BATCH_ITEMS = 50;
+var MAX_IMAGES_PER_REQUEST = 10;
 var CorentError = class extends Error {
   constructor(message, statusCode) {
     super(message);
@@ -58,7 +60,9 @@ var Corent = class {
   images;
   videos;
   speech;
+  text;
   jobs;
+  batches;
   constructor(apiKey, options = {}) {
     this.apiKey = apiKey;
     this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
@@ -66,26 +70,63 @@ var Corent = class {
     this.images = new Images(this);
     this.videos = new Videos(this);
     this.speech = new Speech(this);
+    this.text = new Text(this);
     this.jobs = new Jobs(this);
+    this.batches = new Batches(this);
   }
-  /** Prepaid balance in cents. */
+  /** Prepaid balance in cents. See `balance()` for what is actually spendable. */
   async balanceCents() {
     const r = await this.request("GET", "/v1/account/balance");
     return r.balance_cents;
   }
+  /** The full picture: the total, what running generations have reserved, and
+   * what a new request can actually spend. availableCents is the number a 402
+   * is decided against — check that one before an expensive batch. */
+  async balance() {
+    const r = await this.request("GET", "/v1/account/balance");
+    return {
+      balanceCents: r.balance_cents,
+      heldCents: r.held_cents ?? 0,
+      availableCents: r.available_cents ?? r.balance_cents
+    };
+  }
+  /** The voices `speech.generate` will accept as voiceId. This exists
+   * because the API requires a voice id and, until 2026-08-30, published no
+   * list of legal values. */
+  async voices() {
+    const r = await this.request("GET", "/v1/voices");
+    return r.voices ?? [];
+  }
+  /** What this account has spent, by lane and over time. */
+  async usage() {
+    return this.request("GET", "/v1/account/usage");
+  }
+  /** Live operational status of the generation tiers. Public. */
+  async status() {
+    return this.request("GET", "/v1/status");
+  }
   /** The live tier catalog with honest min–max price ranges. Public. */
   async tiers() {
     const r = await this.request("GET", "/v1/tiers");
     return r.tiers;
   }
+  /** The direct-access menu: every model you can pin by name, with its kind,
+   * quality score and live status. Names come back in their published
+   * spelling ("corent-flux-schnell") and can be passed straight back as
+   * `model`. Carries no price -- billing is flat cost-plus and the exact
+   * charge comes back on each generation. Public. */
+  async models() {
+    const r = await this.request("GET", "/v1/models");
+    return r.models;
+  }
   /** @internal */
-  async request(method, path, body, idempotent = false) {
+  async request(method, path, body, idempotent = false, retryTransport = true, idempotencyKey) {
     const headers = {
       Authorization: `Bearer ${this.apiKey}`,
-      "User-Agent": "corent-js/0.1.0"
+      "User-Agent": "corent-js/0.3.0"
     };
     if (body) headers["Content-Type"] = "application/json";
-    if (idempotent) headers["Idempotency-Key"] = crypto.randomUUID();
+    if (idempotent) headers["Idempotency-Key"] = idempotencyKey ?? crypto.randomUUID();
     let lastError;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
       let resp;
@@ -97,6 +138,7 @@ var Corent = class {
         });
       } catch (err) {
         lastError = err;
+        if (!retryTransport) throw new CorentError(`request failed: ${err}`);
         await sleep(Math.min(2 ** attempt * 1e3, 8e3));
         continue;
       }
@@ -139,22 +181,108 @@ var Images = class {
   }
   c;
   /** Render an image. Submits as a background job and polls, so a client
-   * timeout can never lose a finished render. Pass wait:false for the Job. */
+   * timeout can never lose a finished render. Pass wait:false for the Job.
+   *
+   * `model` pins an exact model from client.models() instead of letting the
+   * router choose — direct access: never substituted, flat cost-plus price.
+   * e.g. model: "corent-flux-schnell". Pass tier OR model, not both. */
   async generate(prompt, options = {}) {
+    if (options.referenceImageUrls && (options.referenceImageUrls.length < 1 || options.referenceImageUrls.length > 4)) {
+      throw new InvalidRequestError("referenceImageUrls must contain 1 to 4 image URLs", 400);
+    }
     const body = {
       prompt,
       aspect_ratio: options.aspectRatio ?? "1:1",
       async: true
     };
     if (options.tier) body.tier = options.tier;
+    if (options.model) body.model = options.model;
     if (options.style) body.style = options.style;
-    const submitted = await this.c.request("POST", "/v1/images/generate", body, true);
+    if (options.referenceImageUrls) body.reference_image_urls = options.referenceImageUrls;
+    if (options.seed !== void 0) body.seed = options.seed;
+    if (options.negativePrompt) body.negative_prompt = options.negativePrompt;
+    if (options.sourceImageUrl) body.source_image_url = options.sourceImageUrl;
+    if (options.strength !== void 0) body.strength = options.strength;
+    if (options.outputFormat) body.output_format = options.outputFormat;
+    if (options.transparent) body.transparent = true;
+    if (options.width !== void 0) body.width = options.width;
+    if (options.height !== void 0) body.height = options.height;
+    if (options.enhancePrompt === false) body.enhance_prompt = false;
+    if (options.webhookUrl) {
+      body.webhook_url = options.webhookUrl;
+      if (options.webhookSecret) body.webhook_secret = options.webhookSecret;
+      delete body.async;
+    }
+    const submitted = await this.c.request(
+      "POST",
+      "/v1/images/generate",
+      body,
+      true,
+      true,
+      options.idempotencyKey
+    );
     if (submitted.status === "completed") return imageFromJob(submitted);
-    if (options.wait === false) {
+    if (options.webhookUrl || options.wait === false) {
       return { id: submitted.id, status: submitted.status, raw: submitted };
     }
     return imageFromJob(await this.c.waitForJob(submitted.id, options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS));
   }
+  /** Render several versions of one prompt in a single call, 2–10.
+   *
+   * Each one is a real render at the normal price, so asking for four costs
+   * four images. They come back together, and `totalCostCents` is the whole
+   * charge. Partial success is a real outcome: if three of four land you get
+   * three and are billed for three.
+   *
+   * Different from client.batches.images(), which runs DIFFERENT prompts and
+   * returns job ids to poll. This one runs the SAME prompt and waits. */
+  async generateMany(prompt, count, options = {}) {
+    if (count < 2 || count > MAX_IMAGES_PER_REQUEST) {
+      throw new InvalidRequestError(
+        `generateMany takes 2 to ${MAX_IMAGES_PER_REQUEST}; use generate() for one`,
+        400
+      );
+    }
+    const body = {
+      prompt,
+      aspect_ratio: options.aspectRatio ?? "1:1",
+      n: count
+    };
+    if (options.tier) body.tier = options.tier;
+    if (options.model) body.model = options.model;
+    if (options.style) body.style = options.style;
+    if (options.referenceImageUrls) body.reference_image_urls = options.referenceImageUrls;
+    if (options.seed !== void 0) body.seed = options.seed;
+    if (options.negativePrompt) body.negative_prompt = options.negativePrompt;
+    if (options.sourceImageUrl) body.source_image_url = options.sourceImageUrl;
+    if (options.strength !== void 0) body.strength = options.strength;
+    if (options.outputFormat) body.output_format = options.outputFormat;
+    if (options.transparent) body.transparent = true;
+    if (options.width !== void 0) body.width = options.width;
+    if (options.height !== void 0) body.height = options.height;
+    if (options.enhancePrompt === false) body.enhance_prompt = false;
+    const r = await this.c.request(
+      "POST",
+      "/v1/images/generate",
+      body,
+      true,
+      true,
+      options.idempotencyKey
+    );
+    const meta = r.meta ?? {};
+    return {
+      images: (r.images ?? []).map((image) => ({
+        id: r.id,
+        url: image.url,
+        width: image.width,
+        height: image.height,
+        model: meta.model,
+        costCents: void 0
+      })),
+      // The total for every image that actually landed.
+      totalCostCents: meta.cost_cents
+    };
+  }
 };
 var Videos = class {
   constructor(c) {
@@ -163,18 +291,41 @@ var Videos = class {
   c;
   /** Render a video (1–5 minutes typical). resolution: 720p | 1080p | 4k —
    * tier-capped, clamped down rather than rejected. imageUrl animates an
-   * existing image (image-to-video). */
+   * existing image (image-to-video).
+   *
+   * `model` pins an exact model from client.models() — direct access, never
+   * substituted, and duration/resolution snap to THAT model's own menu rather
+   * than a tier cap. e.g. model: "corent-seedance-2.0". Pass tier OR model,
+   * not both. */
   async generate(prompt, options = {}) {
-    const body = {
-      prompt,
-      aspect_ratio: options.aspectRatio ?? "16:9"
-    };
+    const body = { prompt };
+    if (options.aspectRatio) body.aspect_ratio = options.aspectRatio;
     if (options.tier) body.tier = options.tier;
+    if (options.model) body.model = options.model;
+    if (options.style) body.style = options.style;
     if (options.durationS !== void 0) body.duration_s = options.durationS;
     if (options.resolution) body.resolution = options.resolution;
     if (options.imageUrl) body.image_url = options.imageUrl;
-    const submitted = await this.c.request("POST", "/v1/videos/generate", body, true);
-    if (options.wait === false) {
+    if (options.audio !== void 0) body.audio = options.audio;
+    if (options.endImageUrl) body.end_image_url = options.endImageUrl;
+    if (options.camera) body.camera = options.camera;
+    if (options.negativePrompt) body.negative_prompt = options.negativePrompt;
+    if (options.seed !== void 0) body.seed = options.seed;
+    if (options.fps !== void 0) body.fps = options.fps;
+    if (options.enhancePrompt === false) body.enhance_prompt = false;
+    if (options.webhookUrl) {
+      body.webhook_url = options.webhookUrl;
+      if (options.webhookSecret) body.webhook_secret = options.webhookSecret;
+    }
+    const submitted = await this.c.request(
+      "POST",
+      "/v1/videos/generate",
+      body,
+      true,
+      true,
+      options.idempotencyKey
+    );
+    if (options.webhookUrl || options.wait === false) {
       return { id: submitted.id, status: submitted.status, raw: submitted };
     }
     return videoFromJob(await this.c.waitForJob(submitted.id, options.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS));
@@ -185,15 +336,111 @@ var Speech = class {
     this.c = c;
   }
   c;
-  /** Text to speech; synchronous, returns the finished audio and exact charge. */
+  /** Text to speech; synchronous, returns the finished audio and exact charge.
+   * `model` pins an exact speech model from client.models(),
+   * e.g. model: "corent-eleven-multilingual-v2". */
   async generate(text, options = {}) {
     const body = { text };
     if (options.voiceId) body.voice_id = options.voiceId;
-    const r = await this.c.request("POST", "/v1/audio/speech", body, true);
+    if (options.model) body.model = options.model;
+    if (options.stability !== void 0) body.stability = options.stability;
+    if (options.similarity !== void 0) body.similarity = options.similarity;
+    if (options.style !== void 0) body.style = options.style;
+    if (options.speed !== void 0) body.speed = options.speed;
+    if (options.language) body.language = options.language;
+    if (options.outputFormat) body.output_format = options.outputFormat;
+    const r = await this.c.request("POST", "/v1/audio/speech", body, true, true, options.idempotencyKey);
     const meta = r.meta ?? {};
     return { id: r.id, url: r.audio_url, model: meta.model, costCents: meta.cost_cents };
   }
 };
+var Text = class {
+  constructor(c) {
+    this.c = c;
+  }
+  c;
+  /** One prompt in, the finished text out. `system` frames the request.
+   *
+   * `model` pins an exact text model from client.models() (kind "text"),
+   * e.g. model: "corent-claude-opus-5"; otherwise `tier` picks the routed
+   * lane. Pass tier OR model, not both. */
+  async generate(prompt, options = {}) {
+    const messages = options.system ? [{ role: "system", content: options.system }, { role: "user", content: prompt }] : [{ role: "user", content: prompt }];
+    return this.chat(messages, options);
+  }
+  /** A full OpenAI-shaped conversation, including tool results. Streaming is
+   * not wrapped here — point any OpenAI client at https://api.corent.tech/v1
+   * with your Corent key for that. */
+  async chat(messages, options = {}) {
+    const body = {
+      // The API's `model` field carries both modes: a pinned catalog name
+      // ("corent-claude-opus-5"), or "corent/text-<tier>" for the routed lane.
+      // Note the two are different namespaces -- the routed lane keeps its
+      // slash form. Whatever the caller passes goes through verbatim; the API
+      // still accepts the older bare spellings. lite matches the router's own
+      // default for an unrecognised tier.
+      model: options.model ?? `corent/text-${options.tier ?? "lite"}`,
+      messages
+    };
+    if (options.maxTokens !== void 0) body.max_tokens = options.maxTokens;
+    if (options.maxCompletionTokens !== void 0) body.max_completion_tokens = options.maxCompletionTokens;
+    if (options.temperature !== void 0) body.temperature = options.temperature;
+    if (options.tools) body.tools = options.tools;
+    if (options.toolChoice !== void 0) body.tool_choice = options.toolChoice;
+    if (options.responseFormat) body.response_format = options.responseFormat;
+    const r = await this.c.request("POST", "/v1/chat/completions", body, false, false);
+    const choice = (r.choices ?? [{}])[0];
+    const message = choice.message ?? {};
+    const usage = r.usage ?? {};
+    return {
+      id: r.id,
+      text: message.content ?? "",
+      model: r.model,
+      finishReason: choice.finish_reason,
+      toolCalls: message.tool_calls,
+      promptTokens: usage.prompt_tokens,
+      completionTokens: usage.completion_tokens,
+      costCents: (r.corent ?? {}).cost_cents
+    };
+  }
+};
+var Batches = class {
+  constructor(c) {
+    this.c = c;
+  }
+  c;
+  async images(items, options = {}) {
+    return this.submit("/v1/images/generate/batch", items.map(imageBatchItemBody), options);
+  }
+  async videos(items, options = {}) {
+    return this.submit("/v1/videos/generate/batch", items.map(videoBatchItemBody), options);
+  }
+  /** How far along a submitted batch is, and each item's job id. Fetch a
+   * finished item's media with client.jobs.get(). */
+  async progress(batchId) {
+    const r = await this.c.request("GET", `/v1/batches/${batchId}`);
+    return {
+      batchId: r.batch_id,
+      total: r.total,
+      completed: r.completed,
+      failed: r.failed,
+      pending: r.pending,
+      jobs: r.jobs ?? []
+    };
+  }
+  async submit(path, items, options) {
+    if (items.length < 1 || items.length > MAX_BATCH_ITEMS) {
+      throw new InvalidRequestError(`a batch takes 1 to ${MAX_BATCH_ITEMS} items, got ${items.length}`, 400);
+    }
+    const body = { items };
+    if (options.webhookUrl) {
+      body.webhook_url = options.webhookUrl;
+      if (options.webhookSecret) body.webhook_secret = options.webhookSecret;
+    }
+    const r = await this.c.request("POST", path, body, true, true, options.idempotencyKey);
+    return { batchId: r.batch_id, jobIds: r.job_ids ?? [] };
+  }
+};
 var Jobs = class {
   constructor(c) {
     this.c = c;
@@ -203,6 +450,15 @@ var Jobs = class {
     const raw = await this.c.request("GET", `/v1/jobs/${jobId}`);
     return { id: raw.id, status: raw.status, raw };
   }
+  /** Stop a job that has not finished and release its money hold.
+   *
+   * Charges nothing. A job that completed just before the cancel landed stays
+   * completed and stays billed for what was really delivered — `cancelled`
+   * says which happened. */
+  async cancel(jobId) {
+    const r = await this.c.request("POST", `/v1/jobs/${jobId}/cancel`);
+    return { id: r.id, status: r.status, cancelled: Boolean(r.cancelled) };
+  }
   async wait(jobId, timeoutMs = DEFAULT_WAIT_TIMEOUT_MS) {
     const raw = await this.c.waitForJob(jobId, timeoutMs);
     return { id: raw.id, status: raw.status, raw };
@@ -246,6 +502,22 @@ function videoFromJob(job) {
     costCents: meta.cost_cents
   };
 }
+function imageBatchItemBody(item) {
+  const body = { prompt: item.prompt };
+  if (item.tier) body.tier = item.tier;
+  if (item.style) body.style = item.style;
+  if (item.aspectRatio) body.aspect_ratio = item.aspectRatio;
+  return body;
+}
+function videoBatchItemBody(item) {
+  const body = { prompt: item.prompt };
+  if (item.tier) body.tier = item.tier;
+  if (item.style) body.style = item.style;
+  if (item.aspectRatio) body.aspect_ratio = item.aspectRatio;
+  if (item.durationS !== void 0) body.duration_s = item.durationS;
+  if (item.resolution) body.resolution = item.resolution;
+  return body;
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }