@ai-sdk/topaz 0.0.0 → 2.0.1

package/src/topaz-get-from-api.ts

@@ -0,0 +1,53 @@
+import {
+  fetchWithValidatedEndpoint,
+  fetchWithValidatedRedirects,
+  getFromApi,
+  isSameOrigin,
+  type FetchFunction,
+} from '@ai-sdk/provider-utils';
+
+/**
+ * Adapts URL validation to v6's getFromApi, which does not yet expose the
+ * validateUrl and credentialedOrigin options.
+ */
+export async function topazGetFromApi<T>({
+  validateUrl,
+  credentialedOrigin,
+  trustedOrigin,
+  ...options
+}: Parameters<typeof getFromApi<T>>[0] & {
+  validateUrl: boolean;
+  credentialedOrigin?: string;
+  trustedOrigin?: string;
+}) {
+  const validatedFetch: FetchFunction = (url, init) =>
+    fetchWithValidatedRedirects({
+      url: url.toString(),
+      headers: init?.headers,
+      abortSignal: init?.signal ?? undefined,
+      trustedOrigin,
+      fetch: (hopUrl, hopInit) =>
+        fetchWithValidatedEndpoint({
+          url: hopUrl.toString(),
+          init: {
+            ...hopInit,
+            headers:
+              credentialedOrigin != null &&
+              isSameOrigin(hopUrl.toString(), credentialedOrigin)
+                ? hopInit?.headers
+                : undefined,
+          },
+          trustedOrigin,
+          redirect: 'manual',
+          fetch: options.fetch,
+        }),
+    });
+
+  // v6 ignores this flag; validation is handled by the injected fetch above.
+  const requestOptions = {
+    ...options,
+    validateUrl: false,
+    fetch: validateUrl ? validatedFetch : options.fetch,
+  };
+  return getFromApi(requestOptions);
+}

package/src/topaz-image-model-options.ts

@@ -0,0 +1,107 @@
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+/**
+ * Provider options for Topaz generative image models (Wonder 3.5).
+ *
+ * The documented request schema fields are sent in snake_case
+ * (`output_width`, `output_format`, ...); model-specific settings are sent in
+ * camelCase, matching the Topaz model reference.
+ *
+ * @see https://developer.topazlabs.com/image-models/wonder/wonder-3.5-new
+ */
+export const topazImageModelOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /**
+       * How aggressively the model enhances the image. Defaults to `high`.
+       */
+      enhancementStrength: z.enum(['low', 'medium', 'high']).optional(),
+
+      /**
+       * Whether to add grain to the output. Defaults to `false`.
+       */
+      grain: z.boolean().optional(),
+
+      /**
+       * Grain intensity, 0.0 to 1.0. Defaults to 0.5.
+       */
+      grainDensity: z.number().min(0).max(1).optional(),
+
+      /**
+       * Grain model. Defaults to `silver`.
+       */
+      grainModel: z.enum(['silver', 'gaussian', 'grey']).optional(),
+
+      /**
+       * Grain particle size, 1 to 5. Defaults to 1.
+       */
+      grainSize: z.number().min(1).max(5).optional(),
+
+      /**
+       * Grain effect strength, 0.0 to 1.0. Defaults to 0.5.
+       */
+      grainStrength: z.number().min(0).max(1).optional(),
+
+      /**
+       * Width of the input image in pixels. Topaz infers this from the upload when
+       * omitted.
+       */
+      inputWidth: z.number().int().positive().optional(),
+
+      /**
+       * Height of the input image in pixels. Topaz infers this from the upload
+       * when omitted.
+       */
+      inputHeight: z.number().int().positive().optional(),
+
+      /**
+       * Width of the output image in pixels, 1 to 32000. Takes precedence over the
+       * width derived from the `size` call option.
+       */
+      outputWidth: z.number().int().min(1).max(32000).optional(),
+
+      /**
+       * Height of the output image in pixels, 1 to 32000. Takes precedence over
+       * the height derived from the `size` call option.
+       */
+      outputHeight: z.number().int().min(1).max(32000).optional(),
+
+      /**
+       * Output image format. Defaults to the Topaz API default.
+       */
+      outputFormat: z.enum(['jpeg', 'jpg', 'png', 'tiff', 'tif']).optional(),
+
+      /**
+       * Whether to crop the output to fill the requested dimensions. Defaults to
+       * `false`.
+       */
+      cropToFill: z.boolean().optional(),
+
+      /**
+       * URL to receive job-status webhooks.
+       */
+      webhookUrl: z.string().optional(),
+
+      /**
+       * How often to poll the Topaz status endpoint, in milliseconds. Defaults to
+       * 2000.
+       */
+      pollIntervalMillis: z.number().int().positive().optional(),
+
+      /**
+       * How long to wait for the job to finish before failing, in milliseconds.
+       * Defaults to 600000 (10 minutes).
+       */
+      pollTimeoutMillis: z.number().int().positive().optional(),
+    }),
+  ),
+);
+
+export type TopazImageModelOptions = InferSchema<
+  typeof topazImageModelOptionsSchema
+>;

package/src/topaz-image-model.ts

@@ -0,0 +1,449 @@
+import {
+  AISDKError,
+  InvalidArgumentError,
+  InvalidResponseDataError,
+  type ImageModelV3,
+  type ImageModelV3CallOptions,
+  type SharedV3Warning,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertBase64ToUint8Array,
+  createBinaryResponseHandler,
+  createJsonResponseHandler,
+  delay,
+  mediaTypeToExtension,
+  parseProviderOptions,
+  postFormDataToApi,
+  removeUndefinedEntries,
+  resolve,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import type { TopazConfig } from './topaz-config';
+import { topazFailedResponseHandler } from './topaz-error';
+import { topazGetFromApi } from './topaz-get-from-api';
+import {
+  topazImageModelOptionsSchema,
+  type TopazImageModelOptions,
+} from './topaz-image-model-options';
+import {
+  resolveTopazImageApiModelId,
+  type TopazImageModelId,
+} from './topaz-image-settings';
+
+const DEFAULT_POLL_INTERVAL_MILLIS = 2000;
+const DEFAULT_POLL_TIMEOUT_MILLIS = 600_000;
+
+/**
+ * Topaz enhances an image that the caller supplies, so `files` is required and
+ * exactly one image is processed per call.
+ */
+export class TopazImageModel implements ImageModelV3 {
+  readonly specificationVersion = 'v3';
+  readonly maxImagesPerCall = 1;
+  readonly supportsFileInputs = true;
+  readonly supportsMaskInputs = false;
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: TopazImageModelId,
+    private readonly config: TopazConfig,
+  ) {}
+
+  async doGenerate(
+    options: ImageModelV3CallOptions,
+  ): Promise<Awaited<ReturnType<ImageModelV3['doGenerate']>>> {
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const warnings: SharedV3Warning[] = [];
+
+    const topazOptions = await parseProviderOptions({
+      provider: 'topaz',
+      providerOptions: options.providerOptions,
+      schema: topazImageModelOptionsSchema,
+    });
+    const headers = combineHeaders(
+      await resolve(this.config.headers),
+      options.headers,
+    );
+
+    this.addUnsupportedWarnings(options, warnings);
+
+    const formData = await this.buildFormData(options, topazOptions, warnings);
+
+    const { value: submitResponse } = await postFormDataToApi({
+      url: `${this.config.baseURL}/image/v1/enhance-gen/async`,
+      headers,
+      formData,
+      successfulResponseHandler: createJsonResponseHandler(
+        topazImageSubmitResponseSchema,
+      ),
+      failedResponseHandler: topazFailedResponseHandler,
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    const processId = submitResponse.process_id;
+    if (processId == null) {
+      throw new InvalidResponseDataError({
+        data: submitResponse,
+        message: 'Topaz did not return a process_id for the enhance request.',
+      });
+    }
+
+    let status: TopazImageStatusResponse;
+    try {
+      status = await this.waitForCompletion({
+        processId,
+        headers,
+        abortSignal: options.abortSignal,
+        pollIntervalMillis:
+          topazOptions?.pollIntervalMillis ?? DEFAULT_POLL_INTERVAL_MILLIS,
+        pollTimeoutMillis:
+          topazOptions?.pollTimeoutMillis ?? DEFAULT_POLL_TIMEOUT_MILLIS,
+      });
+    } catch (error) {
+      // Topaz charges on completion, so a job nobody will download should not
+      // be left running after the caller aborts.
+      if (options.abortSignal?.aborted) {
+        await this.cancelQuietly(processId, headers);
+      }
+      throw error;
+    }
+
+    const { image, responseHeaders } = await this.download({
+      processId,
+      headers,
+      abortSignal: options.abortSignal,
+    });
+
+    return {
+      images: [image],
+      warnings,
+      response: {
+        timestamp: currentDate,
+        modelId: this.modelId,
+        headers: responseHeaders,
+      },
+      providerMetadata: {
+        topaz: {
+          images: [
+            {
+              processId,
+              // Topaz bills exactly the credits reported on the completed job.
+              ...(status.credits != null ? { credits: status.credits } : {}),
+              ...(status.output_width != null
+                ? { width: status.output_width }
+                : {}),
+              ...(status.output_height != null
+                ? { height: status.output_height }
+                : {}),
+              ...(status.output_format != null
+                ? { format: status.output_format }
+                : {}),
+            },
+          ],
+        },
+      },
+    };
+  }
+
+  private addUnsupportedWarnings(
+    options: ImageModelV3CallOptions,
+    warnings: SharedV3Warning[],
+  ): void {
+    if (options.prompt != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'prompt',
+        details:
+          'Topaz image models enhance an existing image and do not take a text prompt. ' +
+          'The prompt was ignored.',
+      });
+    }
+
+    if (options.aspectRatio != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'aspectRatio',
+        details:
+          'Topaz image models do not support aspectRatio. Use `size`, or the ' +
+          '`outputWidth` / `outputHeight` provider options, to set output dimensions.',
+      });
+    }
+
+    if (options.seed != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'seed',
+        details: 'Topaz image models do not support seed.',
+      });
+    }
+
+    if (options.mask != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'mask',
+        details:
+          'Topaz image models do not support masks. The mask was ignored.',
+      });
+    }
+
+    if (options.n > 1) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'n',
+        details:
+          'Topaz image models enhance one image per call. Only 1 image will be returned.',
+      });
+    }
+  }
+
+  private async buildFormData(
+    options: ImageModelV3CallOptions,
+    topazOptions: TopazImageModelOptions | undefined,
+    warnings: SharedV3Warning[],
+  ): Promise<FormData> {
+    const file = options.files?.[0];
+
+    if (file == null) {
+      throw new InvalidArgumentError({
+        argument: 'files',
+        message:
+          'Topaz image models enhance an existing image. Pass the input image via ' +
+          '`prompt.images`.',
+      });
+    }
+
+    if (options.files != null && options.files.length > 1) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'files',
+        details:
+          'Topaz image models enhance one image per call. Only the first file was used.',
+      });
+    }
+
+    const formData = new FormData();
+    formData.append('model', resolveTopazImageApiModelId(this.modelId));
+
+    if (file.type === 'url') {
+      // Topaz fetches the source itself when given a URL, so the bytes never
+      // need to pass through the SDK.
+      formData.append('source_url', file.url);
+    } else {
+      const bytes =
+        typeof file.data === 'string'
+          ? convertBase64ToUint8Array(file.data)
+          : file.data;
+      const extension = mediaTypeToExtension(file.mediaType) ?? 'png';
+
+      formData.append(
+        'image',
+        new File([bytes as BlobPart], `image.${extension}`, {
+          type: file.mediaType,
+        }),
+      );
+    }
+
+    const { width, height } = parseSize(options.size);
+
+    appendIfDefined(
+      formData,
+      'output_width',
+      topazOptions?.outputWidth ?? width,
+    );
+    appendIfDefined(
+      formData,
+      'output_height',
+      topazOptions?.outputHeight ?? height,
+    );
+    appendIfDefined(formData, 'output_format', topazOptions?.outputFormat);
+    appendIfDefined(formData, 'crop_to_fill', topazOptions?.cropToFill);
+    appendIfDefined(formData, 'webhook_url', topazOptions?.webhookUrl);
+
+    // Model-specific settings use camelCase, unlike the request schema fields
+    // above.
+    appendIfDefined(
+      formData,
+      'enhancementStrength',
+      topazOptions?.enhancementStrength,
+    );
+    appendIfDefined(formData, 'grain', topazOptions?.grain);
+    appendIfDefined(formData, 'grainDensity', topazOptions?.grainDensity);
+    appendIfDefined(formData, 'grainModel', topazOptions?.grainModel);
+    appendIfDefined(formData, 'grainSize', topazOptions?.grainSize);
+    appendIfDefined(formData, 'grainStrength', topazOptions?.grainStrength);
+    appendIfDefined(formData, 'inputWidth', topazOptions?.inputWidth);
+    appendIfDefined(formData, 'inputHeight', topazOptions?.inputHeight);
+
+    return formData;
+  }
+
+  private async waitForCompletion({
+    processId,
+    headers,
+    abortSignal,
+    pollIntervalMillis,
+    pollTimeoutMillis,
+  }: {
+    processId: string;
+    headers: Record<string, string | undefined> | undefined;
+    abortSignal: AbortSignal | undefined;
+    pollIntervalMillis: number;
+    pollTimeoutMillis: number;
+  }): Promise<TopazImageStatusResponse> {
+    const deadline = Date.now() + pollTimeoutMillis;
+
+    while (true) {
+      const { value: status } = await topazGetFromApi({
+        url: `${this.config.baseURL}/image/v1/status/${processId}`,
+        // Built from the configured baseURL, not from response data.
+        validateUrl: false,
+        headers,
+        successfulResponseHandler: createJsonResponseHandler(
+          topazImageStatusResponseSchema,
+        ),
+        failedResponseHandler: topazFailedResponseHandler,
+        abortSignal,
+        fetch: this.config.fetch,
+      });
+
+      if (status.status === 'Completed') {
+        return status;
+      }
+
+      if (status.status === 'Failed' || status.status === 'Cancelled') {
+        throw new AISDKError({
+          name: 'TOPAZ_IMAGE_ENHANCEMENT_FAILED',
+          message: `Topaz image enhancement ${status.status.toLowerCase()} for process ${processId}.`,
+        });
+      }
+
+      if (Date.now() + pollIntervalMillis > deadline) {
+        await this.cancelQuietly(processId, headers ?? {});
+        throw new AISDKError({
+          name: 'TOPAZ_IMAGE_ENHANCEMENT_TIMEOUT',
+          message:
+            `Topaz image enhancement did not finish within ${pollTimeoutMillis}ms ` +
+            `(process ${processId}, last status ${status.status ?? 'unknown'}). ` +
+            'Increase the `pollTimeoutMillis` provider option if the job needs longer.',
+        });
+      }
+
+      await delay(pollIntervalMillis, { abortSignal });
+    }
+  }
+
+  private async cancelQuietly(
+    processId: string,
+    headers: Record<string, string | undefined>,
+  ): Promise<void> {
+    const fetchImpl = this.config.fetch ?? globalThis.fetch;
+
+    try {
+      // Deliberately not tied to the caller's abort signal, which may be the
+      // reason polling stopped.
+      await fetchImpl(`${this.config.baseURL}/image/v1/cancel/${processId}`, {
+        method: 'DELETE',
+        headers: removeUndefinedEntries(headers),
+      });
+    } catch {
+      // Best effort: the original error is more useful to the caller.
+    }
+  }
+
+  private async download({
+    processId,
+    headers,
+    abortSignal,
+  }: {
+    processId: string;
+    headers: Record<string, string | undefined> | undefined;
+    abortSignal: AbortSignal | undefined;
+  }): Promise<{
+    image: Uint8Array;
+    responseHeaders: Record<string, string> | undefined;
+  }> {
+    const { value: downloadResponse } = await topazGetFromApi({
+      url: `${this.config.baseURL}/image/v1/download/${processId}`,
+      // Built from the configured baseURL, not from response data.
+      validateUrl: false,
+      headers,
+      successfulResponseHandler: createJsonResponseHandler(
+        topazImageDownloadResponseSchema,
+      ),
+      failedResponseHandler: topazFailedResponseHandler,
+      abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    const downloadUrl = downloadResponse.download_url;
+    if (downloadUrl == null) {
+      throw new InvalidResponseDataError({
+        data: downloadResponse,
+        message: `Topaz did not return a download URL for process ${processId}.`,
+      });
+    }
+
+    const { value: image, responseHeaders } = await topazGetFromApi({
+      url: downloadUrl,
+      // Comes from the Topaz response body and normally points at object
+      // storage, so it is validated and the API key is withheld off-origin.
+      validateUrl: true,
+      credentialedOrigin: this.config.baseURL,
+      trustedOrigin: this.config.baseURL,
+      headers,
+      successfulResponseHandler: createBinaryResponseHandler(),
+      failedResponseHandler: topazFailedResponseHandler,
+      abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    return { image, responseHeaders };
+  }
+}
+
+function parseSize(size: `${number}x${number}` | undefined): {
+  width: number | undefined;
+  height: number | undefined;
+} {
+  if (size == null) {
+    return { width: undefined, height: undefined };
+  }
+
+  const [width, height] = size.split('x').map(Number);
+  return { width, height };
+}
+
+function appendIfDefined(
+  formData: FormData,
+  key: string,
+  value: string | number | boolean | undefined,
+): void {
+  if (value !== undefined) {
+    formData.append(key, String(value));
+  }
+}
+
+const topazImageSubmitResponseSchema = z.object({
+  process_id: z.string().nullish(),
+});
+
+const topazImageStatusResponseSchema = z.object({
+  // Documented values are Pending, Processing, Completed, Cancelled and Failed.
+  // Unknown values keep polling rather than failing the parse.
+  status: z.string().nullish(),
+  credits: z.number().nullish(),
+  output_width: z.number().nullish(),
+  output_height: z.number().nullish(),
+  output_format: z.string().nullish(),
+});
+
+type TopazImageStatusResponse = z.infer<typeof topazImageStatusResponseSchema>;
+
+const topazImageDownloadResponseSchema = z.object({
+  download_url: z.string().nullish(),
+});

package/src/topaz-image-settings.ts

@@ -0,0 +1,22 @@
+/**
+ * Topaz image model ids.
+ *
+ * The AI SDK exposes a readable id that is mapped onto the name the Topaz API
+ * expects in the `model` form field (see `topazImageApiModelIds`). Passing a
+ * raw Topaz name such as `Wonder 3.5` also works - unknown ids are forwarded
+ * to the API unchanged.
+ */
+export type TopazImageModelId = 'wonder-3.5' | (string & {});
+
+/**
+ * Maps AI SDK image model ids onto Topaz API model names.
+ *
+ * @see https://developer.topazlabs.com/image-models/wonder/wonder-3.5-new
+ */
+export const topazImageApiModelIds: Record<string, string> = {
+  'wonder-3.5': 'Wonder 3.5',
+};
+
+export function resolveTopazImageApiModelId(modelId: string): string {
+  return topazImageApiModelIds[modelId] ?? modelId;
+}