ql-agent-sdk 1.0.1 → 1.1.0

package/dist/index.d.cts

@@ -4,6 +4,11 @@ interface JsonRequestOptions {
     signal?: AbortSignal;
     headers?: Record<string, string>;
 }
+interface FormRequestOptions {
+    form: FormData;
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
 /**
  * Internal transport used by the API namespaces. Keeps the API key inside a
  * closure (never exposed) and normalizes responses/errors for the caller.
@@ -11,6 +16,8 @@ interface JsonRequestOptions {
 interface Transport {
     /** Perform a JSON request and return the unwrapped `data` payload. */
     json<T>(method: string, path: string, opts?: JsonRequestOptions): Promise<T>;
+    /** Perform a multipart/form-data request and return the unwrapped `data` payload. */
+    form<T>(path: string, opts: FormRequestOptions): Promise<T>;
     /**
      * Perform a request expected to stream SSE. Returns the response body stream
      * after verifying a 2xx + text/event-stream; throws QLError otherwise.
@@ -270,6 +277,254 @@ interface WaitOptions {
     /** Called after each poll with the latest task snapshot. */
     onTick?: (task: Task) => void;
 }
+type ImageTier = "standard" | "professional" | "advanced";
+/** A single pricing entry for an image model. */
+interface ImagePricingEntry {
+    /** What is billed, e.g. "output_image" / "input_image". */
+    billable: string;
+    /** Billing unit: flat per image, or per output-image token. */
+    unit: "image" | "token";
+    costUsd: number;
+    /** Optional sub-variant (e.g. a resolution tier or quality variant). */
+    variant?: string;
+}
+/** A tiered image-generation model as returned by `images.listModels`. */
+interface ImageModelInfo {
+    id: string;
+    name: string;
+    tier: ImageTier;
+    description: string;
+    /** Short best-use-case label for UI copy. */
+    bestFor: string;
+    referenceImageSupport: boolean;
+    maxReferenceImages: number;
+    /** Empty array = the model does not accept a resolution parameter. */
+    supportedResolutions: string[];
+    supportedAspectRatios: string[];
+    /** Max value for the `n` (images per request) parameter. */
+    maxImages: number;
+    pricing: {
+        /** Human-readable summary, e.g. "$0.018 / image". */
+        summary: string;
+        entries: ImagePricingEntry[];
+    };
+    recommended: boolean;
+    /** Static registry flag (always reflects the shipped registry). */
+    enabled: boolean;
+    /** Runtime availability — live when `verified` is true. */
+    available: boolean;
+    /** Whether `available` reflects a live OpenRouter check. */
+    verified: boolean;
+}
+/** Result of `images.listModels`. */
+interface ImageModelsResult {
+    models: ImageModelInfo[];
+    availability: {
+        /** True when the availability values came from a fresh OpenRouter check. */
+        fresh: boolean;
+        verifiedAt: string | Date | null;
+    };
+}
+/** A reference image for generation. */
+interface ImageReferenceInput {
+    /** Base64 data URL, e.g. "data:image/png;base64,...". */
+    dataUrl: string;
+    /** Optional instruction on how this reference should influence the output. */
+    description?: string;
+}
+/** Input for `images.generate`. */
+interface ImageGenerateInput {
+    prompt: string;
+    /** Explicit OpenRouter model id (wins over `tier`). */
+    model?: string;
+    /** Tier to resolve a model from (used when `model` is omitted). */
+    tier?: ImageTier | string;
+    references?: ImageReferenceInput[];
+    resolution?: string;
+    aspect_ratio?: string;
+    n?: number;
+}
+/** A single generated image. */
+interface GeneratedImage {
+    /** Base64-encoded image bytes (no data-URL prefix). */
+    b64Json: string;
+    mediaType: string;
+}
+/** Token + cost usage for a generation, as reported by the provider. */
+interface ImageUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /** Actual cost in USD. */
+    cost: number;
+}
+/** Result of `images.generate`. */
+interface ImageGenerateResult {
+    images: GeneratedImage[];
+    usage: ImageUsage | null;
+    model: string;
+    tier: string;
+    latencyMs: number;
+}
+type VideoTier = "standard" | "professional" | "advanced";
+/** A single pricing entry for a video model. */
+interface VideoPricingEntry {
+    /** What is billed, e.g. "output_video" / "voiceover". */
+    billable: string;
+    /** Billing unit: per rendered second, or flat per request. */
+    unit: "second" | "request";
+    costUsd: number;
+}
+/** A tiered video-generation model as returned by `videos.listModels`. */
+interface VideoModelInfo {
+    id: string;
+    name: string;
+    tier: VideoTier;
+    description: string;
+    /** Short best-use-case label for UI copy. */
+    bestFor: string;
+    /** Execution engine (e.g. "motion-graphics"). */
+    engine: string;
+    supportsProductImages: boolean;
+    maxReferenceImages: number;
+    supportsReferenceVideos: boolean;
+    maxReferenceVideos: number;
+    supportedAspectRatios: string[];
+    supportedResolutions: string[];
+    /** Inclusive [min, max] duration in seconds. */
+    durationRange: [number, number];
+    voiceoverSupport: boolean;
+    pricing: {
+        summary: string;
+        entries: VideoPricingEntry[];
+    };
+    recommended: boolean;
+    enabled: boolean;
+    /** Runtime engine availability (render toolchain present). */
+    available: boolean;
+}
+/** Result of `videos.listModels`. */
+interface VideoModelsResult {
+    models: VideoModelInfo[];
+    engine: {
+        available: boolean;
+        detail: string;
+    };
+}
+/** Input for `videos.generate`. */
+interface VideoGenerateInput {
+    /** The creative brief / script for the video. */
+    prompt: string;
+    /** Explicit registry model id (wins over `tier`). */
+    model?: string;
+    /** Tier to resolve a model from (used when `model` is omitted). */
+    tier?: VideoTier | string;
+    /** Product/reference images — base64 data URLs or https URLs. Order defines IMG_0..N. */
+    images_list?: string[];
+    /** Reference (style) videos — https URLs only (upload local files via `files.upload`). */
+    video_files?: string[];
+    /** e.g. "16:9", "9:16", "1:1". Default "16:9". */
+    aspect_ratio?: string;
+    /** Duration in seconds (must be within the model's durationRange). */
+    duration?: number;
+    /** e.g. "720p" | "1080p". Default "720p". */
+    resolution?: string;
+    /** Bake an ElevenLabs voiceover into the render (requires `narration`). */
+    generate_audio?: boolean;
+    /** Voiceover text (used when `generate_audio` is true). Max 3000 chars. */
+    narration?: string;
+}
+/** Returned when a video job is created (HTTP 202). */
+interface VideoTaskCreated {
+    taskId: string;
+    status: "queued";
+}
+type VideoTaskStatus = "queued" | "rendering" | "completed" | "failed" | "cancelled" | (string & {});
+/** A video job snapshot, as returned by `videos.getTask`. */
+interface VideoTask {
+    taskId: string;
+    status: VideoTaskStatus;
+    progress?: {
+        current: number;
+        total: number;
+        message?: string;
+    };
+    /** Served media path (e.g. /generated/video-….mp4) once completed. */
+    outputUrl?: string;
+    mime?: string;
+    ext?: string;
+    /** Actual rendered duration in seconds. */
+    durationSec?: number;
+    error?: string;
+    model?: string;
+    tier?: string;
+    latencyMs?: number;
+    createdAt: string | Date;
+    completedAt: string | Date | null;
+}
+/** Options for polling / waiting on a video job. */
+interface VideoWaitOptions {
+    /** Base delay between polls in ms (default 2000). Grows with backoff up to `maxIntervalMs`. */
+    intervalMs?: number;
+    /** Upper bound for the backoff delay in ms (default 15000). */
+    maxIntervalMs?: number;
+    /** Stop waiting after this many ms and throw a timeout error. Omit to wait until terminal or abort. */
+    timeoutMs?: number;
+    /** Abort polling at any time. */
+    signal?: AbortSignal;
+    /** Called after each poll with the latest job snapshot. */
+    onTick?: (task: VideoTask) => void;
+}
+/** Input for `audio.textToSpeech`. */
+interface TtsInput {
+    /** Text to synthesize (max 3000 chars). */
+    text: string;
+    /** ElevenLabs voice id (list via `audio.voices`). Defaults to the platform voice. */
+    voiceId?: string;
+    /** Voice stability 0..1 (default 0.5). */
+    stability?: number;
+    /** Similarity boost 0..1 (default 0.75). */
+    similarityBoost?: number;
+}
+/** Result of `audio.textToSpeech`. */
+interface TtsResult {
+    /** Served audio path (e.g. /generated/tts-….mp3). */
+    url: string;
+    voiceId: string;
+    modelId: string;
+    bytes: number;
+    latencyMs: number;
+}
+/** A single ElevenLabs voice as returned by `audio.voices`. */
+interface VoiceInfo {
+    id: string;
+    name: string;
+}
+/** Result of `audio.voices`. */
+interface VoicesResult {
+    voices: VoiceInfo[];
+    /** "live" = fetched from the provider; "none" = no provider key configured. */
+    source: "live" | "none";
+    note?: string;
+}
+/** Result of `files.upload`. */
+interface UploadedFile {
+    /** Stable served path (e.g. /uploads/<workspace>/<file>) usable as a media input URL. */
+    url: string;
+    filename: string;
+    size: number;
+    contentType: string;
+}
+/** Options for `files.upload`. */
+interface FileUploadOptions {
+    /** Override the stored display name (extension is kept from the file). */
+    filename?: string;
+    /**
+     * Coarse progress callback. Fetch does not expose upload byte progress, so this
+     * reports 0 at start and 100 on completion.
+     */
+    onProgress?: (percent: number) => void;
+}
 
 declare function isTerminalTaskStatus(status: string): boolean;
 /**
@@ -288,15 +543,24 @@ declare class TaskHandle {
     get(signal?: AbortSignal): Promise<Task>;
     /** Alias of `get()` — perform one poll and return the latest snapshot. */
     poll(signal?: AbortSignal): Promise<Task>;
-    /**
-     * Poll until the task reaches a terminal status.
-     *
-     * - Uses exponential-ish backoff from `intervalMs` up to `maxIntervalMs`.
-     * - Throws a QLError with code "timeout" if `timeoutMs` elapses first.
-     * - Throws a QLError with code "aborted" if `signal` aborts.
-     */
+    /** Poll until the task reaches a terminal status (see pollUntilTerminal for semantics). */
     wait(opts?: WaitOptions): Promise<Task>;
 }
+/**
+ * A handle to a video job created via `videos.generate`.
+ * Polls the video-tasks endpoint until the job reaches a terminal status.
+ */
+declare class VideoTaskHandle {
+    private readonly transport;
+    readonly taskId: string;
+    constructor(transport: Transport, taskId: string);
+    /** Fetch the current job snapshot (single request). */
+    get(signal?: AbortSignal): Promise<VideoTask>;
+    /** Alias of `get()` — perform one poll and return the latest snapshot. */
+    poll(signal?: AbortSignal): Promise<VideoTask>;
+    /** Poll until the job reaches a terminal status (completed/failed/cancelled). */
+    wait(opts?: VideoWaitOptions): Promise<VideoTask>;
+}
 
 declare const DEFAULT_BASE_URL = "https://app.quantonlabs.com";
 interface QLClientOptions {
@@ -360,6 +624,46 @@ declare class TasksApi {
     /** Get a handle for polling / waiting on a task (poll(), wait()). */
     handle(taskId: string): TaskHandle;
 }
+/** Images namespace (tiered image generation). */
+declare class ImagesApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** GET /api/v1/images/models — list tiered image models + runtime availability. */
+    listModels(): Promise<ImageModelsResult>;
+    /** POST /api/v1/agents/:agentId/images — generate image(s) via a tiered model. */
+    generate(agentId: string, input: ImageGenerateInput): Promise<ImageGenerateResult>;
+}
+/** Videos namespace (tiered video generation: submit → poll). */
+declare class VideosApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** GET /api/v1/videos/models — list tiered video models + engine availability. */
+    listModels(): Promise<VideoModelsResult>;
+    /** POST /api/v1/agents/:agentId/videos — start a video job (returns the queued task, HTTP 202). */
+    generate(agentId: string, input: VideoGenerateInput): Promise<VideoTaskCreated>;
+    /** GET /api/v1/video-tasks/:taskId — fetch the current job snapshot. */
+    getTask(taskId: string, signal?: AbortSignal): Promise<VideoTask>;
+    /** DELETE /api/v1/video-tasks/:taskId — cancel a queued/rendering job (409 if already terminal). */
+    cancelTask(taskId: string): Promise<VideoTask>;
+    /** Get a handle for polling / waiting on a video job (poll(), wait()). */
+    handle(taskId: string): VideoTaskHandle;
+}
+/** Audio namespace (text-to-speech). */
+declare class AudioApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** GET /api/v1/audio/voices — list available TTS voices. */
+    voices(): Promise<VoicesResult>;
+    /** POST /api/v1/agents/:agentId/tts — synthesize speech (synchronous). */
+    textToSpeech(agentId: string, input: TtsInput): Promise<TtsResult>;
+}
+/** Files namespace (media uploads). */
+declare class FilesApi {
+    private readonly t;
+    constructor(t: Transport);
+    /** POST /api/v1/files — upload a media file (multipart field "file"). */
+    upload(file: Blob, opts?: FileUploadOptions): Promise<UploadedFile>;
+}
 /**
  * The public client. Example:
  *   const ql = new QLClient({ apiKey: process.env.QL_API_KEY });
@@ -370,6 +674,10 @@ declare class QLClient {
     readonly agents: AgentsApi;
     readonly workflows: WorkflowsApi;
     readonly tasks: TasksApi;
+    readonly images: ImagesApi;
+    readonly videos: VideosApi;
+    readonly audio: AudioApi;
+    readonly files: FilesApi;
     private readonly transport;
     private readonly base;
     constructor(opts: QLClientOptions);
@@ -413,4 +721,4 @@ declare class QLError extends Error {
     get isNetworkError(): boolean;
 }
 
-export { API_ERROR_CODES, type AgentDetail, type AgentListResult, type AgentSummary, AgentsApi, type ApiErrorCode, type CapParamKind, type CapabilitiesResult, type CapabilityInfo, type CapabilityParam, type CapabilityResult, type CapabilityTemplate, type ChatInput, type ChatMessage, type ChatResult, type ChatStreamEvent, DEFAULT_BASE_URL, type HistoryPage, type HistoryParams, type MessageItem, QLClient, type QLClientOptions, QLError, type QLErrorContext, type RunCapabilityInput, type RunCapabilityResult, type StreamOptions, type Task, type TaskCreateInput, type TaskCreated, TaskHandle, type TaskPriority, type TaskStatus, TasksApi, type WaitOptions, type WorkflowRun, type WorkflowRunInput, type WorkflowRunStart, type WorkflowRunStatus, WorkflowsApi, type Workspace, WorkspaceApi, isTerminalTaskStatus };
+export { API_ERROR_CODES, type AgentDetail, type AgentListResult, type AgentSummary, AgentsApi, type ApiErrorCode, AudioApi, type CapParamKind, type CapabilitiesResult, type CapabilityInfo, type CapabilityParam, type CapabilityResult, type CapabilityTemplate, type ChatInput, type ChatMessage, type ChatResult, type ChatStreamEvent, DEFAULT_BASE_URL, type FileUploadOptions, FilesApi, type GeneratedImage, type HistoryPage, type HistoryParams, type ImageGenerateInput, type ImageGenerateResult, type ImageModelInfo, type ImageModelsResult, type ImagePricingEntry, type ImageReferenceInput, type ImageTier, type ImageUsage, ImagesApi, type MessageItem, QLClient, type QLClientOptions, QLError, type QLErrorContext, type RunCapabilityInput, type RunCapabilityResult, type StreamOptions, type Task, type TaskCreateInput, type TaskCreated, TaskHandle, type TaskPriority, type TaskStatus, TasksApi, type TtsInput, type TtsResult, type UploadedFile, type VideoGenerateInput, type VideoModelInfo, type VideoModelsResult, type VideoPricingEntry, type VideoTask, type VideoTaskCreated, VideoTaskHandle, type VideoTaskStatus, type VideoTier, type VideoWaitOptions, VideosApi, type VoiceInfo, type VoicesResult, type WaitOptions, type WorkflowRun, type WorkflowRunInput, type WorkflowRunStart, type WorkflowRunStatus, WorkflowsApi, type Workspace, WorkspaceApi, isTerminalTaskStatus };