# Images

`met.images` generates, edits and animates images from your code, through the **same key** as the rest of the API. You don't need to sign up with or contract an external provider: Meteor runs the model, hosts the result and **debits Energy** from your workspace for each operation.

> Requires a **live** key (`met_live_…`) with the `integrations:execute` scope. A test key returns `403`. Your workspace also needs an **active image integration** in the MCP marketplace; without one, generation fails.

Like every operation with side effects, it runs server-side:

```ts
import { Met } from '@meteor.ia/sdk';

const met = new Met(process.env.MET_KEY!, { workspaceId: 42 });
```

## Generate an image

```ts
const img = await met.images.generate({
  prompt: 'Mockup of a white mug with a minimalist logo, neutral background',
  aspect_ratio: '1:1',
});

console.log(img.url);            // public URL hosted by Meteor
console.log(img.format);         // 'png' | 'jpeg' | 'webp' | …
console.log(img.size_bytes);     // file size
console.log(img.model);          // model used
console.log(img.energy_debited); // Energy debited for this operation
```

The result is a **public URL hosted by Meteor**, not the raw bytes. Store it or pass it straight to wherever you need it:

```ts
const mockup = await met.images.generate({ prompt: 'Artisan coffee packaging, studio lighting' });
await met.contacts.update(310, { image: mockup.url });
```

`model` and `aspect_ratio` are optional. If you omit `model`, the active integration's **default model** is used. `aspect_ratio` accepts values like `'1:1'`, `'16:9'`, `'9:16'` or `'3:4'`.

## Edit an image

Transform an existing image by passing it in base64:

```ts
const edited = await met.images.edit({
  prompt: 'Change the background to a blue gradient',
  image_base64: '...',   // the source image, in base64
});

console.log(edited.url);
```

It returns the same shape as `generate` (`url`, `format`, `model`, `energy_debited`).

## Animate (video)

Generate a clip from a prompt, optionally animating a starting image:

```ts
const clip = await met.images.video({
  prompt: 'The mug turns slowly on the table',
  image_base64: '...',    // optional first frame (base64)
  duration_seconds: 4,
});

console.log(clip.url);              // URL of the hosted video
console.log(clip.duration_seconds); // actual length of the clip
console.log(clip.energy_debited);
```

`image_base64`, `duration_seconds` and `model` are optional.

## Cost

Every `generate`, `edit` and `video` **debits Energy** from your workspace and is attributed to the key. The amount comes back in `energy_debited`, and API usage is reported separately from the chat in your dashboard. If you're missing errors or pagination, see [Errors and idempotency](errors-and-idempotency.html).