corent-sdk 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Corent TypeScript SDK — one API for AI image, video, and voice.
+ * Corent TypeScript SDK — one API for AI image, video, voice, and text.
  *
  *   import { Corent } from "corent-sdk";
  *   const client = new Corent("co_live_...");
@@ -16,6 +16,8 @@ interface GeneratedImage {
     /** MEASURED pixels of the delivered file — Corent parses the file, never echoes the request. */
     width?: number;
     height?: number;
+    /** The tier that served it ("image-premium"), or the model you pinned,
+     * always in its published spelling ("corent-flux-schnell"). */
     model?: string;
     costCents?: number;
 }
@@ -26,15 +28,90 @@ interface GeneratedVideo {
     height?: number;
     resolution?: string;
     durationS?: number;
+    /** The tier that served it ("video-premium"), or the model you pinned,
+     * always in its published spelling ("corent-seedance-2.0"). */
     model?: string;
     costCents?: number;
 }
 interface GeneratedSpeech {
     id: string;
     url: string;
+    /** The tier that served it ("corent-speech-tts"), or the model you pinned,
+     * always in its published spelling ("corent-eleven-multilingual-v2"). */
     model?: string;
     costCents?: number;
 }
+/** One voice `speech.generate` accepts. Descriptors are neutral labels a
+ * picker can filter on; no supplier or model name is published. */
+interface Voice {
+    voice_id: string;
+    name?: string;
+    preview_url?: string;
+    gender?: string;
+    age?: string;
+    accent?: string;
+    use_case?: string;
+}
+interface Balance {
+    balanceCents: number;
+    /** Reserved by generations still running. */
+    heldCents: number;
+    /** What a new request can actually spend: balance minus holds. */
+    availableCents: number;
+}
+/** One image in a batch. Batch items are tier-routed: to pin an exact model,
+ * use images.generate() one at a time. */
+interface ImageBatchItem {
+    prompt: string;
+    tier?: Tier;
+    style?: string;
+    aspectRatio?: string;
+}
+interface VideoBatchItem {
+    prompt: string;
+    tier?: Tier;
+    style?: string;
+    aspectRatio?: string;
+    durationS?: number;
+    resolution?: "720p" | "1080p" | "4k";
+}
+/** The 202 from a batch submission: the batch id and one job id per item. */
+interface SubmittedBatch {
+    batchId: string;
+    jobIds: string[];
+}
+interface BatchProgress {
+    batchId: string;
+    total: number;
+    completed: number;
+    failed: number;
+    pending: number;
+    jobs: {
+        id: string;
+        status: string;
+    }[];
+}
+/** OpenAI-shaped message, for callers driving a real conversation. */
+interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content?: unknown;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: Record<string, unknown>[];
+}
+interface GeneratedText {
+    id: string;
+    text: string;
+    /** The tier that served it ("corent/text-premium"), or the model you pinned,
+     * always in its published spelling ("corent-claude-opus-5"). */
+    model?: string;
+    finishReason?: string;
+    /** Present when the model answered with tool calls instead of prose. */
+    toolCalls?: Record<string, unknown>[];
+    promptTokens?: number;
+    completionTokens?: number;
+    costCents?: number;
+}
 interface Job {
     id: string;
     status: "processing" | "completed" | "failed";
@@ -67,14 +144,34 @@ declare class Corent {
     readonly images: Images;
     readonly videos: Videos;
     readonly speech: Speech;
+    readonly text: Text;
     readonly jobs: Jobs;
+    readonly batches: Batches;
     constructor(apiKey: string, options?: ClientOptions);
-    /** Prepaid balance in cents. */
+    /** Prepaid balance in cents. See `balance()` for what is actually spendable. */
     balanceCents(): Promise<number>;
+    /** 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. */
+    balance(): Promise<Balance>;
+    /** 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. */
+    voices(): Promise<Voice[]>;
+    /** What this account has spent, by lane and over time. */
+    usage(): Promise<Record<string, unknown>>;
+    /** Live operational status of the generation tiers. Public. */
+    status(): Promise<Record<string, unknown>>;
     /** The live tier catalog with honest min–max price ranges. Public. */
     tiers(): Promise<Record<string, unknown>[]>;
+    /** 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. */
+    models(): Promise<Record<string, unknown>[]>;
     /** @internal */
-    request(method: string, path: string, body?: Record<string, unknown>, idempotent?: boolean): Promise<Record<string, any>>;
+    request(method: string, path: string, body?: Record<string, unknown>, idempotent?: boolean, retryTransport?: boolean, idempotencyKey?: string): Promise<Record<string, any>>;
     /** @internal */
     waitForJob(jobId: string, timeoutMs: number): Promise<Record<string, any>>;
 }
@@ -82,27 +179,109 @@ declare class Images {
     private c;
     constructor(c: Corent);
     /** 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. */
     generate(prompt: string, options?: {
         tier?: Tier;
+        model?: string;
         style?: string;
         aspectRatio?: string;
+        /** 1–4 public https image URLs that keep a character, face, or product
+         * consistent across generations: the prompt is applied as an EDIT of
+         * these references. Served only by edit-capable models, which sit at
+         * premium and up — pass tier "premium" | "pro" | "max_pro" (or no tier
+         * at all), never "air" or "lite". Omit for plain text-to-image. */
+        referenceImageUrls?: string[];
+        /** Reproducibility. The same seed, prompt and model give the same
+         * image, so you can render it again and change one thing. The seed that
+         * was actually used comes back on the result. */
+        seed?: number;
+        /** What must NOT appear, e.g. "text, watermark". */
+        negativePrompt?: string;
+        /** Image-to-image: start from this picture instead of from noise.
+         * Different from referenceImageUrls, which pins an identity. */
+        sourceImageUrl?: string;
+        /** How far the render may travel from sourceImageUrl. 0 keeps it, 1 ignores it. */
+        strength?: number;
+        /** Delivered file type: png | jpeg | webp. png is the one with transparency. */
+        outputFormat?: "png" | "jpeg" | "webp";
+        /** Transparent background, for logos and cutouts. Forces png. */
+        transparent?: boolean;
+        /** Explicit pixel size. Pass both or neither. */
+        width?: number;
+        height?: number;
+        /** Corent rewrites your prompt before dispatch to get a better render.
+         * Set false to send it exactly as typed. */
+        enhancePrompt?: boolean;
+        /** Deliver the finished job to your own https endpoint instead of
+         * polling. Returns the Job immediately when set. */
+        webhookUrl?: string;
+        /** Signs each delivery: X-Corent-Signature: t=<unix>,v1=HMAC-SHA256. */
+        webhookSecret?: string;
+        /** Your own idempotency key, so a retry from another process or after a
+         * restart replays the original job instead of generating again. */
+        idempotencyKey?: string;
         wait?: false | true;
         timeoutMs?: number;
     }): Promise<GeneratedImage | Job>;
+    /** 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. */
+    generateMany(prompt: string, count: number, options?: Omit<Parameters<Images["generate"]>[1], "wait">): Promise<{
+        images: GeneratedImage[];
+        totalCostCents?: number;
+    }>;
 }
 declare class Videos {
     private c;
     constructor(c: Corent);
     /** 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. */
     generate(prompt: string, options?: {
         tier?: Tier;
+        model?: string;
+        style?: string;
         aspectRatio?: string;
         durationS?: number;
         resolution?: "720p" | "1080p" | "4k";
         imageUrl?: string;
+        /** Ask for native sound. Some models render audio and some are
+         * silent. true routes only to models that deliver sound, so a silent
+         * model can never quietly serve the request; false prefers a silent
+         * one; omit to let routing choose. */
+        audio?: boolean;
+        /** The frame the clip should END on. With imageUrl this is the
+         * go-from-A-to-B effect. */
+        endImageUrl?: string;
+        /** Camera move: static | pan_left | pan_right | zoom_in | zoom_out |
+         * orbit_left | orbit_right | tilt_up | tilt_down. */
+        camera?: string;
+        /** What must NOT appear in the clip. */
+        negativePrompt?: string;
+        seed?: number;
+        fps?: number;
+        /** Set false to send your prompt exactly as typed. */
+        enhancePrompt?: boolean;
+        /** Deliver the finished clip to your own https endpoint instead of
+         * polling. Recommended for video, which takes 1–5 minutes. */
+        webhookUrl?: string;
+        webhookSecret?: string;
+        idempotencyKey?: string;
         wait?: false | true;
         timeoutMs?: number;
     }): Promise<GeneratedVideo | Job>;
@@ -110,16 +289,92 @@ declare class Videos {
 declare class Speech {
     private c;
     constructor(c: Corent);
-    /** 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". */
     generate(text: string, options?: {
         voiceId?: string;
+        model?: string;
+        /** 0–1. Low is more expressive and more variable; high is steadier. */
+        stability?: number;
+        /** 0–1. How closely to hold the original voice's character. */
+        similarity?: number;
+        /** 0–1. Extra expressiveness. */
+        style?: number;
+        /** Playback speed; 1.0 is natural pace. */
+        speed?: number;
+        /** ISO code for the multilingual models, e.g. "en" or "pt-BR". */
+        language?: string;
+        /** "mp3" | "wav" | "pcm", or an exact "mp3_44100_128". */
+        outputFormat?: string;
+        idempotencyKey?: string;
     }): Promise<GeneratedSpeech>;
 }
+interface TextOptions {
+    tier?: Tier;
+    model?: string;
+    maxTokens?: number;
+    /** OpenAI's newer alias; honoured by the API when maxTokens is absent. */
+    maxCompletionTokens?: number;
+    temperature?: number;
+    tools?: Record<string, unknown>[];
+    /** "auto" | "none" | "required" | { type: "function", function: { name } } */
+    toolChoice?: unknown;
+    responseFormat?: Record<string, unknown>;
+}
+declare class Text {
+    private c;
+    constructor(c: Corent);
+    /** 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. */
+    generate(prompt: string, options?: TextOptions & {
+        system?: string;
+    }): Promise<GeneratedText>;
+    /** 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. */
+    chat(messages: ChatMessage[], options?: TextOptions): Promise<GeneratedText>;
+}
+/** Up to 50 renders in one call. Every item bills at the normal rate, so a
+ * 30-item image batch costs 30 generations — check client.balance() first.
+ * Asynchronous: submit returns immediately, then poll progress() or give the
+ * server a webhookUrl and let it deliver each item. */
+declare class Batches {
+    private c;
+    constructor(c: Corent);
+    images(items: ImageBatchItem[], options?: {
+        webhookUrl?: string;
+        webhookSecret?: string;
+        idempotencyKey?: string;
+    }): Promise<SubmittedBatch>;
+    videos(items: VideoBatchItem[], options?: {
+        webhookUrl?: string;
+        webhookSecret?: string;
+        idempotencyKey?: string;
+    }): Promise<SubmittedBatch>;
+    /** How far along a submitted batch is, and each item's job id. Fetch a
+     * finished item's media with client.jobs.get(). */
+    progress(batchId: string): Promise<BatchProgress>;
+    private submit;
+}
 declare class Jobs {
     private c;
     constructor(c: Corent);
     get(jobId: string): Promise<Job>;
+    /** 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. */
+    cancel(jobId: string): Promise<{
+        id: string;
+        status: string;
+        cancelled: boolean;
+    }>;
     wait(jobId: string, timeoutMs?: number): Promise<Job>;
 }
 
-export { Corent, CorentError, type GeneratedImage, type GeneratedSpeech, type GeneratedVideo, GenerationFailedError, InsufficientBalanceError, InvalidRequestError, type Job, RateLimitedError, type Tier };
+export { type Balance, type BatchProgress, type ChatMessage, Corent, CorentError, type GeneratedImage, type GeneratedSpeech, type GeneratedText, type GeneratedVideo, GenerationFailedError, type ImageBatchItem, InsufficientBalanceError, InvalidRequestError, type Job, RateLimitedError, type SubmittedBatch, type Tier, type VideoBatchItem, type Voice };