@omelhorsite/sdk 0.16.0 → 0.18.0

package/dist/types/resources/tools/imageGeneration.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Image generation: a prompt in, a PNG out.
+ *
+ * Same shape as the other async tools - `POST /image_generations` enqueues a
+ * job and answers with a row plus a `job_id` and, when anonymous, a
+ * `watch_token`.
+ *
+ * What is different here is that the work can run in two places, and the
+ * caller picks: a model on the server itself, which is free, or a model at a
+ * paid provider, which is not. {@link ImageGenerationNamespace.models} lists
+ * the ones the CURRENT caller may actually use, so an anonymous caller never
+ * sees a model they would be refused for.
+ *
+ * Two daily quotas apply, not one: a count of images, which every model
+ * consumes, and a spend ceiling in USD, which only the paid ones touch.
+ */
+import { Resource } from "../../http";
+import type { Id, RequestOptions } from "../../types";
+import { type ToolCaptcha, type ToolJobHandle, type ToolRecord, type ToolRunOptions } from "./index";
+/** Where a model runs. `"local"` is the server itself and always free. */
+export type ImageProvider = "local" | "fal";
+/** One model the caller may pick, as `GET /image_generations/models` lists it. */
+export interface ImageModel {
+    readonly key: string;
+    readonly name: string;
+    readonly description: string;
+    readonly provider: ImageProvider;
+    /** True when a run costs money and counts against the spend ceiling. */
+    readonly billable: boolean;
+    /** True on models kept behind an account flag. */
+    readonly adult: boolean;
+    /** `width * height` may not exceed this. */
+    readonly max_pixels: number;
+    readonly default_width: number;
+    readonly default_height: number;
+    readonly default_steps: number;
+    readonly max_steps: number;
+    /** False on models that ignore `negative_prompt` entirely, such as FLUX. */
+    readonly supports_negative_prompt: boolean;
+    /** Millionths of a USD per megapixel, rounded up. Zero on local models. */
+    readonly cost_per_megapixel_microusd: number;
+}
+/**
+ * One generation.
+ *
+ * Both routes that answer with one - `POST /image_generations` and
+ * `GET /image_generations/:id` - answer the same shape, so `result_url` is
+ * always PRESENT and simply `null` until the run completes.
+ */
+export interface ImageGeneration extends ToolRecord {
+    readonly model_key: string;
+    readonly provider: ImageProvider;
+    readonly prompt: string;
+    readonly negative_prompt: string | null;
+    readonly width: number;
+    readonly height: number;
+    readonly steps: number;
+    /**
+     * The seed the image was made with. Null only while the run is still
+     * pending: a caller that sent none gets the one the server picked, which is
+     * what makes the image reproducible.
+     */
+    readonly seed: number | null;
+    readonly guidance: string | null;
+    /** What this run costs, in millionths of a USD. Zero on local models. */
+    readonly cost_microusd: number;
+    /**
+     * Signed URL of the PNG, or `null`. `null` covers three different
+     * situations - the run has not finished, it failed, or the 24-hour sweep
+     * took the attachment - which is why {@link ImageGenerationNamespace.resultUrl}
+     * exists rather than a bare read of this field.
+     */
+    readonly result_url: string | null;
+}
+/** What `POST /image_generations` answers with. */
+export type ImageGenerationCreated = ImageGeneration & ToolJobHandle;
+/** Arguments for starting a run. */
+export interface CreateImageGenerationInput extends ToolCaptcha {
+    /** What to draw. Cap: 2000 characters. */
+    readonly prompt: string;
+    /** Defaults to the server's own default model when omitted. */
+    readonly model?: string;
+    /** Ignored by models whose `supports_negative_prompt` is false. */
+    readonly negativePrompt?: string;
+    /** Must be a multiple of 8, at least 256. Defaults to the model's own. */
+    readonly width?: number;
+    /** Must be a multiple of 8, at least 256. Defaults to the model's own. */
+    readonly height?: number;
+    readonly steps?: number;
+    /** Pass the seed of an earlier run to reproduce its image. */
+    readonly seed?: number;
+    readonly guidance?: number;
+}
+/** The `imageGeneration` tool, reachable as `oms.tools.imageGeneration`. */
+export declare class ImageGenerationNamespace extends Resource {
+    private readonly jobs;
+    /**
+     * `GET /image_generations/models` - the models THIS caller may use.
+     *
+     * The list is already filtered by session and by account flags, so it is
+     * safe to render straight into a picker: everything in it is something
+     * {@link create} would accept.
+     */
+    models(options?: RequestOptions): Promise<ImageModel[]>;
+    /**
+     * `POST /image_generations` - enqueues a run and returns straight away.
+     *
+     * Every optional field is omitted from the body when the caller did not set
+     * it, so the server applies the chosen model's own defaults rather than the
+     * SDK guessing at them.
+     *
+     * NOT retried by default: replaying this `POST` after a 502 starts a second
+     * run, and on a paid model bills for it. Pass `retry: {}` to opt back in.
+     *
+     * @throws {OmsApiError} 400 for an unknown model, a blank prompt, or
+     *   dimensions outside the model's limits; 403 for a model this caller may
+     *   not use; 429 once either daily quota is spent.
+     * @throws {OmsAuthError} 401 when anonymous and the captcha is missing or bad.
+     */
+    create(input: CreateImageGenerationInput, options?: RequestOptions): Promise<ImageGenerationCreated>;
+    /**
+     * `GET /image_generations/:id` - one poll.
+     *
+     * @throws {OmsApiError} 404 once the 24-hour retention sweep has taken it.
+     * @throws {OmsAuthError} 401 when the run belongs to someone else, which
+     *   includes an anonymous run being read from a different address.
+     */
+    get(id: Id, options?: RequestOptions): Promise<ImageGeneration>;
+    /**
+     * Creates a run and waits for it, through `oms.jobs.wait`.
+     *
+     * Resolves with a `"failed"` row rather than throwing when the work failed.
+     * Pass `waitTimeoutMs` (or a `signal`) to bound the wait; there is no default
+     * deadline.
+     *
+     * @throws {OmsTimeoutError} `code: "timeout"` when `waitTimeoutMs` elapses,
+     *   `code: "aborted"` when the signal fires. Neither cancels the run: pick it
+     *   up later with {@link get}.
+     */
+    run(input: CreateImageGenerationInput, options?: ToolRunOptions): Promise<ImageGeneration>;
+    /**
+     * Downloads the PNG of a finished run.
+     *
+     * @throws {OmsError} `conflict` when the run has not finished,
+     *   `invalid_request` when it failed, `not_found` when the artefact is gone.
+     */
+    download(id: Id, options?: RequestOptions): Promise<Blob>;
+    /**
+     * The signed URL of a finished run's image, from a row you already hold.
+     *
+     * It is a credential: anyone holding it can read the image.
+     *
+     * @throws {OmsError} explaining which of the three reasons there is no URL.
+     */
+    resultUrl(record: ImageGeneration): string;
+}

package/dist/types/resources/tools/index.d.ts

@@ -37,6 +37,7 @@ import { type JobsNamespace } from "../jobs";
 import { BackgroundRemovalNamespace } from "./backgroundRemoval";
 import { CaptionsNamespace } from "./captions";
 import { DownloaderNamespace } from "./downloader";
+import { ImageGenerationNamespace } from "./imageGeneration";
 import { JumpstyleNamespace } from "./jumpstyle";
 import { TranscriptionNamespace } from "./transcription";
 import { UpscaleNamespace } from "./upscale";
@@ -45,6 +46,7 @@ import { VocalSeparationNamespace } from "./vocalSeparation";
 export * from "./backgroundRemoval";
 export * from "./captions";
 export * from "./downloader";
+export * from "./imageGeneration";
 export * from "./jumpstyle";
 export * from "./transcription";
 export * from "./upscale";
@@ -247,6 +249,8 @@ export declare class ToolsNamespace extends Resource {
     readonly backgroundRemoval: BackgroundRemovalNamespace;
     /** Enlarges an image without the mush. */
     readonly upscale: UpscaleNamespace;
+    /** A prompt in, a PNG out. Runs on the server or at a paid provider. */
+    readonly imageGeneration: ImageGenerationNamespace;
     /** Speech to text, with SRT and VTT output. */
     readonly transcription: TranscriptionNamespace;
     /** Splits a track into vocals and instrumental. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omelhorsite/sdk",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "TypeScript SDK for the omelhorsite API. Isolate-safe: no node builtins, no environment access, no stdout.",
   "type": "module",
   "license": "UNLICENSED",