feat(provider): add image model options type definitions#12473
feat(provider): add image model options type definitions#12473saakshigupta2002 wants to merge 3 commits intovercel:mainfrom
Conversation
Add TypeScript interfaces for image model provider options across four providers to improve type safety and developer experience: - OpenAIImageModelOptions: quality, style, background, output_format, output_compression, input_fidelity, partial_images, user - AmazonBedrockImageModelOptions: quality, cfgScale, negativeText, style, taskType, maskPrompt, outPaintingMode, similarityStrength - FireworksImageModelOptions: guidance_scale, num_inference_steps, negative_prompt, strength, scheduler, safety_checker - DeepinfraImageModelOptions: guidance_scale, num_inference_steps, negative_prompt, strength, scheduler, image_format, response_format All interfaces are exported from their respective package entry points and include comprehensive JSDoc documentation. Fixes vercel#12437, vercel#12435, vercel#12439, vercel#12460
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
| * | ||
| * @see https://deepinfra.com/models/text-to-image | ||
| */ | ||
| export interface DeepinfraImageModelOptions { |
There was a problem hiding this comment.
DeepinfraImageModelOptions uses inconsistent casing (Deepinfra with lowercase 'i') while all other exported types in the package use DeepInfra (capital 'I').
| * Determines how the image should be extended. | ||
| * | ||
| * - `DEFAULT`: Standard outpainting | ||
| * - `PRECISE`: More precise adherence to original image style | ||
| * - `CREATIVE`: More creative freedom in extended areas | ||
| */ | ||
| outPaintingMode?: 'DEFAULT' | 'PRECISE' | 'CREATIVE'; |
There was a problem hiding this comment.
The outPaintingMode type union includes 'CREATIVE' which is not a valid AWS Bedrock API value, misleading users into using an unsupported option that will cause API errors.
There was a problem hiding this comment.
this is indeed the case, looking at the "Outpainting request" docs in https://docs.aws.amazon.com/nova/latest/userguide/image-gen-req-resp-structure.html. Needs to be fixed in the schema.
felixarntz
left a comment
felixarntz
left a comment
There was a problem hiding this comment.
@saakshigupta2002 Thank you for opening a PR for these issues!
Note that introducing the types alone is not sufficient, they also need to be used in their respective provider packages, and in the examples in examples/ai-functions that use those providers.
I left some more notes below; because of this being more work and requiring careful review of each provider's specific image generation parameters and how they're passed, I would suggest you open individual pull requests for each issue. This way we can work through each provider one by one - it'll simplify things and also mean we don't have to hold up all providers in case one of them is more complex to get right.
| * | ||
| * @see https://docs.aws.amazon.com/nova/latest/userguide/image-gen-req-resp-structure.html | ||
| */ | ||
| export interface AmazonBedrockImageModelOptions { |
There was a problem hiding this comment.
In addition to declaring the type for each provider, we also need to parse the given providerOptions for an image generation call against it, via the parseProviderOptions helper.
The recommended approach used elsewhere for this is to define this as a Zod schema instead and infer the type. Take a look at for example packages/xai/src/xai-image-options.ts and packages/xai/src/xai-image-model.ts.
This feedback applies to all providers in the PR.
| * Determines how the image should be extended. | ||
| * | ||
| * - `DEFAULT`: Standard outpainting | ||
| * - `PRECISE`: More precise adherence to original image style | ||
| * - `CREATIVE`: More creative freedom in extended areas | ||
| */ | ||
| outPaintingMode?: 'DEFAULT' | 'PRECISE' | 'CREATIVE'; |
There was a problem hiding this comment.
this is indeed the case, looking at the "Outpainting request" docs in https://docs.aws.amazon.com/nova/latest/userguide/image-gen-req-resp-structure.html. Needs to be fixed in the schema.
|
Thank you for the detailed review @felixarntz! You're absolutely right — I'll rework this with Zod schemas and |
Thanks for the review! I've reworked my previous approach based on your feedback - which split into separate PRs as per provider, added Zod schemas with
|
2 participants
Summary
This PR adds TypeScript type definition interfaces for image model provider options across four providers: OpenAI, Amazon Bedrock, Fireworks, and Deepinfra. These interfaces provide type safety and IDE autocomplete support when using the
providerOptionsparameter for image generation, significantly improving the developer experience.Currently, the image model provider options are passed as untyped objects via
providerOptions.<provider>, which means developers get no compile-time validation or IDE assistance when configuring provider-specific image generation parameters. This PR addresses that gap by defining and exporting typed interfaces for each provider.Changes
OpenAI Provider (
@ai-sdk/openai)Added
OpenAIImageModelOptionsinterface with properties:quality,style,background,output_format,output_compression,input_fidelity,partial_images,userExport: Added to
packages/openai/src/index.tsAmazon Bedrock Provider (
@ai-sdk/amazon-bedrock)Added
AmazonBedrockImageModelOptionsinterface with properties:quality,cfgScale,negativeText,style,taskType,maskPrompt,outPaintingMode,similarityStrengthExport: Added to
packages/amazon-bedrock/src/index.tsFireworks Provider (
@ai-sdk/fireworks)Added
FireworksImageModelOptionsinterface with properties:guidance_scale,num_inference_steps,negative_prompt,strength,scheduler,safety_checkerExport: Added to
packages/fireworks/src/index.tsDeepinfra Provider (
@ai-sdk/deepinfra)Added
DeepinfraImageModelOptionsinterface with properties:guidance_scale,num_inference_steps,negative_prompt,strength,scheduler,image_format,response_formatExport: Added to
packages/deepinfra/src/index.tsDesign Decisions
Interface properties derived from actual usage: Each interface's properties were identified by analyzing the existing
providerOptions.<provider>access patterns in each provider's image model implementation, ensuring full coverage of supported options.Comprehensive JSDoc documentation: All properties include detailed JSDoc comments with descriptions, valid value ranges, default values, and usage examples to maximize IDE tooltip usefulness.
Consistent naming conventions: Interface names follow the established SDK pattern:
{Provider}{Feature}Options(e.g.,OpenAIImageModelOptions, matchingOpenAILanguageModelChatOptions).All properties optional: Every property is optional to maintain backward compatibility — existing code that passes partial or no provider options continues to work without changes.
Verification
pnpm turbo buildpasses successfully for all four packages and their dependencies (9 tasks, 0 failures)pnpm turbo lintpasses successfully for all four packages (9 tasks, 0 failures)Related Issues
Closes #12437
Closes #12435
Closes #12439
Closes #12460