@magichourhq/ai-sdk-provider 0.3.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Magic Hour provider for the AI SDK
2
2
 
3
- Generate images and videos with [Magic Hour](https://magichour.ai) from the [AI SDK](https://ai-sdk.dev).
3
+ Generate and edit images, and generate videos, with [Magic Hour](https://magichour.ai) from the [AI SDK](https://ai-sdk.dev).
4
4
 
5
5
  ## Install
6
6
 
@@ -32,6 +32,15 @@ const { video } = await generateVideo({
32
32
 
33
33
  For text-to-video, pass a string prompt. An input image can be bytes, base64 or an HTTPS URL.
34
34
 
35
+ To edit images, pass them with the prompt. Up to 10 PNG, JPEG or WebP images:
36
+
37
+ ```ts
38
+ const { image: edited } = await generateImage({
39
+ model: magichour.image("flux-2-klein"),
40
+ prompt: { text: "Make the mug matte blue", images: [image.uint8Array] },
41
+ });
42
+ ```
43
+
35
44
  To configure the provider in code, use `createMagicHour`:
36
45
 
37
46
  ```ts
@@ -50,16 +59,18 @@ const magichour = createMagicHour({ apiKey: process.env.MY_KEY, timeoutMs: 300_0
50
59
 
51
60
  ## Models and options
52
61
 
62
+ Every model in the [Magic Hour API](https://docs.magichour.ai/api-reference/models) works, for example `flux-2-klein`, `nano-banana-2.1` or `gpt-image-2` for images, and `ltx-2.5`, `kling-4.0` or `veo3.1` for video. Model IDs are typed from the API spec, so new models arrive with new releases. Each model has its own resolutions, durations, aspect ratios and plan tiers. The API checks them and rejects a request it can't run before charging anything.
63
+
53
64
  | | Image | Video |
54
65
  | --- | --- | --- |
55
- | Models | `default`, `flux-2-klein`, `z-image-turbo`, `qwen-image-2.1` | `default`, `ltx-2.5`, `minimax-h3`, `wan-2.2` |
56
- | Resolution | `640px` (default), `1k`, `2k` | `360p`, `480p` (default), `720p`, `1080p`, `4k` |
57
- | Aspect ratio | `1:1`, `16:9`, `9:16` | `1:1`, `16:9` (default), `9:16` |
66
+ | Resolution | `640px`, `1k`, `2k`, `4k` | `360p`, `480p`, `720p`, `1080p`, `4k` |
67
+ | Aspect ratio | `1:1`, `16:9`, `9:16`; editing also takes `auto`, `4:3`, `3:2`, `4:5` and `2:3` | `1:1`, `16:9` (default), `9:16` |
58
68
 
59
- - Set the resolution with `providerOptions: { magichour: { resolution } }`, or with the AI SDK's `size` for images (640, 1024 or 2048 on the longest edge) and `resolution` for videos (360, 480, 720, 1080 or 2160 on the shortest edge).
60
- - Video `duration` is 1 to 60 seconds, 5 by default. `generateAudio` is passed through.
69
+ - Without a resolution, the API picks the model's default. Set one with `providerOptions: { magichour: { resolution } }`, or with the AI SDK's `size` for images (640, 1024 or 2048 on the longest edge) and `resolution` for videos (360, 480, 720, 1080 or 2160 on the shortest edge).
70
+ - Video `duration` is 5 seconds by default. Some models only take certain durations; Kling 2.6, for example, takes 5 or 10. `generateAudio` is passed through.
61
71
  - Image-to-video keeps the input image's shape, so it takes no aspect ratio.
62
- - Seeds, FPS, image editing and frame or reference inputs aren't supported. They throw before anything is sent.
72
+ - Editing uses Magic Hour's AI Image Editor, with any model the editor offers. Without an aspect ratio, the editor uses `auto`. Each model accepts a different number of input images.
73
+ - Seeds, FPS, masks and video frame or reference inputs aren't supported. They throw before anything is sent.
63
74
  - `default` follows Magic Hour's current recommendation, so its output and cost can change. Choose a model to keep them fixed. See [pricing](https://docs.magichour.ai/pricing).
64
75
 
65
76
  ## Credits and failures
package/dist/index.d.ts CHANGED
@@ -1,13 +1,14 @@
1
1
  import { type ImageModelV4, type Experimental_VideoModelV4 as VideoModelV4, type ProviderV4 } from "@ai-sdk/provider";
2
- import { type ClientSettings } from "@magichourhq/browser-client";
2
+ import { type ClientSettings, type CreateBody } from "@magichourhq/browser-client";
3
3
  export { MagicHourError } from "@magichourhq/browser-client";
4
4
  export type MagicHourSettings = Omit<ClientSettings, "apiKey"> & {
5
5
  apiKey?: string;
6
6
  };
7
- declare const imageModels: readonly ["default", "flux-2-klein", "z-image-turbo", "qwen-image-2.1"];
8
- declare const videoModels: readonly ["default", "ltx-2.5", "minimax-h3", "wan-2.2"];
9
- export type MagicHourImageModelId = (typeof imageModels)[number];
10
- export type MagicHourVideoModelId = (typeof videoModels)[number];
7
+ type GenerateImageModel = NonNullable<CreateBody<"ai-image-generator">["model"]>;
8
+ type EditImageModel = NonNullable<CreateBody<"ai-image-editor">["model"]>;
9
+ type VideoModel = NonNullable<CreateBody<"text-to-video">["model"]>;
10
+ export type MagicHourImageModelId = GenerateImageModel | EditImageModel;
11
+ export type MagicHourVideoModelId = VideoModel | NonNullable<CreateBody<"image-to-video">["model"]>;
11
12
  export interface MagicHourProvider extends Omit<ProviderV4, "imageModel"> {
12
13
  image(modelId?: MagicHourImageModelId): ImageModelV4;
13
14
  imageModel(modelId?: string): ImageModelV4;
package/dist/index.js CHANGED
@@ -1,10 +1,9 @@
1
1
  import { NoSuchModelError, } from "@ai-sdk/provider";
2
2
  import { MagicHourClient, MagicHourError, httpsURL, } from "@magichourhq/browser-client";
3
3
  export { MagicHourError } from "@magichourhq/browser-client";
4
- const imageModels = ["default", "flux-2-klein", "z-image-turbo", "qwen-image-2.1"];
5
- const videoModels = ["default", "ltx-2.5", "minimax-h3", "wan-2.2"];
4
+ const editAspectRatios = ["auto", "1:1", "16:9", "9:16", "4:3", "3:2", "4:5", "2:3"];
6
5
  const aspectRatios = ["1:1", "16:9", "9:16"];
7
- const imageResolutions = ["640px", "1k", "2k"];
6
+ const imageResolutions = ["640px", "1k", "2k", "4k"];
8
7
  const videoResolutions = ["360p", "480p", "720p", "1080p", "4k"];
9
8
  function isOneOf(values, value) {
10
9
  return values.includes(value);
@@ -50,11 +49,28 @@ function dimensions(value) {
50
49
  throw new Error("Dimensions must look like 1024x1024.");
51
50
  return [Number(match[1]), Number(match[2])];
52
51
  }
52
+ /** Checks an input image without uploading it, so a bad file never follows a good upload. */
53
+ function inputImage(file) {
54
+ if (file.type === "url")
55
+ return { url: httpsURL(file.url) };
56
+ const extension = { "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp" }[file.mediaType];
57
+ if (!extension)
58
+ throw new Error("Input images must be PNG, JPEG, or WebP.");
59
+ const bytes = typeof file.data === "string" ? base64Bytes(file.data) : file.data;
60
+ if (!hasSignature(bytes, extension))
61
+ throw new Error(`The input image data isn't a ${extension.toUpperCase()} file.`);
62
+ return { bytes, extension };
63
+ }
64
+ async function filePath(transport, input, signal) {
65
+ if ("url" in input)
66
+ return input.url;
67
+ return transport.uploadImage(input.bytes, input.extension, signal);
68
+ }
53
69
  function imageResolution(size, option) {
54
70
  if (option !== undefined && !isOneOf(imageResolutions, option))
55
- throw new Error("Image resolution must be 640px, 1k, or 2k.");
71
+ throw new Error("Image resolution must be 640px, 1k, 2k, or 4k.");
56
72
  if (!size)
57
- return option ?? "640px";
73
+ return option;
58
74
  if (option !== undefined)
59
75
  throw new Error("Use either size or providerOptions.magichour.resolution.");
60
76
  // Magic Hour exposes longest-edge tiers, rather than arbitrary pixel sizes.
@@ -79,6 +95,20 @@ function ratioFromSize(size) {
79
95
  }
80
96
  throw new Error("Dimensions must have a 1:1, 16:9, or 9:16 aspect ratio.");
81
97
  }
98
+ /**
99
+ * Names the operation and model in an API rejection. One model setting reaches several endpoints,
100
+ * so the API's own message ("model must be one of …") doesn't say which one refused it.
101
+ */
102
+ async function submit(action, modelId, create) {
103
+ try {
104
+ return await create();
105
+ }
106
+ catch (error) {
107
+ if (error instanceof MagicHourError && error.status < 500 && !error.projectId)
108
+ throw new MagicHourError(`Magic Hour can't ${action} with ${modelId}: ${error.message}`, undefined, error.status, undefined, error.code);
109
+ throw error;
110
+ }
111
+ }
82
112
  export function createMagicHour(settings = {}) {
83
113
  // Resolve credentials lazily so merely importing or registering the provider needs no key.
84
114
  const client = () => new MagicHourClient({
@@ -86,22 +116,25 @@ export function createMagicHour(settings = {}) {
86
116
  apiKey: settings.apiKey ?? process.env.MAGIC_HOUR_API_KEY ?? "",
87
117
  });
88
118
  function image(modelId = "default") {
89
- if (!isOneOf(imageModels, modelId))
90
- throw new NoSuchModelError({ modelId, modelType: "imageModel" });
91
119
  return {
92
120
  specificationVersion: "v4",
93
121
  provider: "magichour.image",
94
122
  modelId,
95
123
  maxImagesPerCall: 1,
96
- supportsFileInputs: false,
124
+ // The API rejects input images for a model that can't edit, before charging anything.
125
+ supportsFileInputs: true,
97
126
  supportsMaskInputs: false,
98
127
  async doGenerate(options) {
99
- if (!options.prompt?.trim())
128
+ const prompt = options.prompt;
129
+ if (!prompt?.trim())
100
130
  throw new Error("An image prompt is required.");
101
131
  if (options.n !== 1)
102
132
  throw new Error("One image per request is supported.");
103
- if (options.files?.length || options.mask)
104
- throw new Error("This provider supports image generation, not image editing.");
133
+ if (options.mask)
134
+ throw new Error("Masks are not supported.");
135
+ const files = options.files ?? [];
136
+ if (files.length > 10)
137
+ throw new Error("Image editing accepts up to 10 input images.");
105
138
  if (options.seed !== undefined)
106
139
  throw new Error("Magic Hour does not expose a seed parameter.");
107
140
  const extras = extra(options, ["resolution"]);
@@ -109,17 +142,42 @@ export function createMagicHour(settings = {}) {
109
142
  const sizeRatio = ratioFromSize(options.size);
110
143
  if (sizeRatio && options.aspectRatio && sizeRatio !== options.aspectRatio)
111
144
  throw new Error("size and aspectRatio disagree.");
112
- const aspectRatio = ratio(options.aspectRatio ?? sizeRatio);
145
+ const requestedRatio = options.aspectRatio ?? sizeRatio;
146
+ if (files.length && requestedRatio && !isOneOf(editAspectRatios, requestedRatio))
147
+ throw new Error(`Supported aspect ratios for editing: ${editAspectRatios.join(", ")}.`);
148
+ const inputs = files.map(inputImage);
113
149
  const transport = client();
114
150
  const signal = transport.signal(options.abortSignal);
115
- const timestamp = new Date();
116
- const id = await transport.create("ai-image-generator", {
117
- model: modelId,
118
- image_count: 1,
119
- resolution,
120
- ...(aspectRatio ? { aspect_ratio: aspectRatio } : {}),
121
- style: { prompt: options.prompt },
122
- }, signal, options.headers);
151
+ let id;
152
+ let timestamp;
153
+ if (inputs.length) {
154
+ const paths = [];
155
+ for (const input of inputs)
156
+ paths.push(await filePath(transport, input, signal));
157
+ timestamp = new Date();
158
+ id = await submit("edit images", modelId, () => transport.create("ai-image-editor", {
159
+ model: modelId,
160
+ image_count: 1,
161
+ ...(resolution ? { resolution } : {}),
162
+ // Without one, the editor uses `auto`.
163
+ ...(requestedRatio
164
+ ? { aspect_ratio: requestedRatio }
165
+ : {}),
166
+ style: { prompt },
167
+ assets: { image_file_paths: paths },
168
+ }, signal, options.headers));
169
+ }
170
+ else {
171
+ const aspectRatio = ratio(requestedRatio);
172
+ timestamp = new Date();
173
+ id = await submit("generate images", modelId, () => transport.create("ai-image-generator", {
174
+ model: modelId,
175
+ image_count: 1,
176
+ ...(resolution ? { resolution } : {}),
177
+ ...(aspectRatio ? { aspect_ratio: aspectRatio } : {}),
178
+ style: { prompt },
179
+ }, signal, options.headers));
180
+ }
123
181
  const project = await transport.wait(id, "image", signal, options.headers);
124
182
  try {
125
183
  const images = await Promise.all(project.downloads.slice(0, 1).map((d) => transport.download(d.url, signal)));
@@ -141,8 +199,6 @@ export function createMagicHour(settings = {}) {
141
199
  };
142
200
  }
143
201
  function video(modelId = "default") {
144
- if (!videoModels.includes(modelId))
145
- throw new NoSuchModelError({ modelId, modelType: "videoModel" });
146
202
  return {
147
203
  specificationVersion: "v4",
148
204
  provider: "magichour.video",
@@ -162,7 +218,7 @@ export function createMagicHour(settings = {}) {
162
218
  throw new Error("Invalid Magic Hour video resolution.");
163
219
  if (options.resolution && extras.resolution !== undefined)
164
220
  throw new Error("Use either resolution or providerOptions.magichour.resolution.");
165
- let resolution = extras.resolution ?? "480p";
221
+ let resolution = extras.resolution;
166
222
  const dimensionsRatio = ratioFromSize(options.resolution);
167
223
  if (options.resolution) {
168
224
  const shortEdge = Math.min(...dimensions(options.resolution));
@@ -195,38 +251,27 @@ export function createMagicHour(settings = {}) {
195
251
  // Validate all options before uploading input or submitting a paid generation.
196
252
  const transport = client();
197
253
  const signal = transport.signal(options.abortSignal);
198
- let imagePath;
199
- if (options.image?.type === "url")
200
- imagePath = httpsURL(options.image.url);
201
- else if (options.image?.type === "file") {
202
- const extension = { "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp" }[options.image.mediaType];
203
- if (!extension)
204
- throw new Error("Image-to-video accepts PNG, JPEG, or WebP.");
205
- const bytes = typeof options.image.data === "string"
206
- ? base64Bytes(options.image.data)
207
- : options.image.data;
208
- if (!hasSignature(bytes, extension))
209
- throw new Error(`The input image data isn't a ${extension.toUpperCase()} file.`);
210
- imagePath = await transport.uploadImage(bytes, extension, signal);
211
- }
254
+ const imagePath = options.image
255
+ ? await filePath(transport, inputImage(options.image), signal)
256
+ : undefined;
212
257
  const timestamp = new Date();
213
258
  const shared = {
214
259
  model: modelId,
215
260
  end_seconds: duration,
216
- resolution,
261
+ ...(resolution ? { resolution } : {}),
217
262
  ...(options.generateAudio !== undefined ? { audio: options.generateAudio } : {}),
218
263
  };
219
264
  const id = imagePath
220
- ? await transport.create("image-to-video", {
265
+ ? await submit("animate images", modelId, () => transport.create("image-to-video", {
221
266
  ...shared,
222
267
  ...(options.prompt ? { style: { prompt: options.prompt } } : {}),
223
268
  assets: { image_file_path: imagePath },
224
- }, signal, options.headers)
225
- : await transport.create("text-to-video", {
269
+ }, signal, options.headers))
270
+ : await submit("generate videos", modelId, () => transport.create("text-to-video", {
226
271
  ...shared,
227
272
  style: { prompt: options.prompt ?? "" },
228
273
  aspect_ratio: aspectRatio ?? "16:9",
229
- }, signal, options.headers);
274
+ }, signal, options.headers));
230
275
  const project = await transport.wait(id, "video", signal, options.headers);
231
276
  try {
232
277
  const data = await transport.download(project.downloads[0].url, signal);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@magichourhq/ai-sdk-provider",
3
- "version": "0.3.1",
3
+ "version": "0.4.0",
4
4
  "packageManager": "yarn@4.18.0",
5
5
  "description": "Magic Hour image and video provider for the AI SDK",
6
6
  "keywords": [
@@ -42,7 +42,7 @@
42
42
  },
43
43
  "dependencies": {
44
44
  "@ai-sdk/provider": "^4.0.31",
45
- "@magichourhq/browser-client": "^0.3.2"
45
+ "@magichourhq/browser-client": "^0.3.5"
46
46
  },
47
47
  "devDependencies": {
48
48
  "@types/node": "^24.0.0",