AI text API reference

import type * as ai from './contracts/index.js';
/** Stateless, server-only text generation. No automatic retries or application billing policy. */
export declare class OpenAIText {
    #private;
    /** Creates a client with explicit credentials and bounded, non-retrying requests. */
    constructor(options: ai.OpenAITextOptions);
    /**
     * Runs one bounded text task. Partial, refused and empty responses are not success.
     *
     * @param request - Trusted instructions and untrusted input for this task.
     * @returns Completed text with provider-reported usage.
     * @example
     * const result = await ai.generate({ instructions: 'Summarise this note.', input: note.body, maxOutputTokens: 400 });
     */
    generate(request: ai.TextRequest): Promise<ai.TextResult>;
}

/** Server-owned configuration for a stateless OpenAI text client. */
export interface OpenAITextOptions {
    /** Developer-supplied secret. Never expose this option to browser code. */
    apiKey: string;
    /** Explicit Responses-compatible model selected by the application. */
    model: string;
    /** Maximum time for one provider request; defaults to 30 seconds. */
    timeoutMs?: number;
    /** External HTTP transport override, primarily for deterministic provider tests. */
    fetch?: typeof globalThis.fetch;
}

/** One stateless text task. Applications own authorization and prompt policy. */
export interface TextRequest {
    /** Untrusted source text, separate from the application instruction. */
    input: string;
    /** Trusted application instruction, never derived from user-controlled roles. */
    instructions: string;
    /** Required upper bound on generated tokens, including reasoning tokens. */
    maxOutputTokens: number;
    /** Optional cancellation signal. Cancellation does not guarantee zero provider cost. */
    signal?: AbortSignal;
}

/** Completed provider text and measured usage, not a price or billing record. */
export interface TextResult {
    text: string;
    model: string;
    /** Provider response identifier, useful for support without recording the prompt. */
    id: string;
    /** Null when the provider did not return usage; never assume missing means free. */
    usage: {
        inputTokens: number;
        outputTokens: number;
        totalTokens: number;
    } | null;
}

/** Safe failure classification. Provider bodies and credentials are deliberately omitted. */
export declare class TextGenerationError extends Error {
    readonly code: 'configuration' | 'invalid_input' | 'cancelled' | 'timeout' | 'rate_limit' | 'provider' | 'incomplete';
    /** Creates a safe application-facing error without retaining provider payloads. */
    constructor(code: 'configuration' | 'invalid_input' | 'cancelled' | 'timeout' | 'rate_limit' | 'provider' | 'incomplete');
}