corent-sdk 0.1.0 → 0.3.0

package/dist/index.js

@@ -3,6 +3,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);
@@ -30,7 +32,9 @@ var Corent = class {
   images;
   videos;
   speech;
+  text;
   jobs;
+  batches;
   constructor(apiKey, options = {}) {
     this.apiKey = apiKey;
     this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
@@ -38,26 +42,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;
@@ -69,6 +110,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;
       }
@@ -111,22 +153,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) {
@@ -135,18 +263,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));
@@ -157,15 +308,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;
@@ -175,6 +422,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 };
@@ -218,6 +474,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));
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "corent-sdk",
-  "version": "0.1.0",
-  "description": "Official TypeScript/JavaScript SDK for Corent — one API for AI image, video, and voice generation with built-in routing, failover, and exact receipts.",
+  "version": "0.3.0",
+  "description": "Official TypeScript/JavaScript SDK for Corent — one API for AI image, video, voice, and text generation with built-in routing, failover, and exact receipts.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -20,7 +20,7 @@
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "test": "npm run build && node --test test/*.test.js"
   },
-  "keywords": ["ai", "image-generation", "video-generation", "text-to-speech", "api", "corent"],
+  "keywords": ["ai", "image-generation", "video-generation", "text-to-speech", "llm", "api", "corent"],
   "homepage": "https://corent.tech/docs",
   "devDependencies": {
     "tsup": "^8.0.0",