# Deployments: Image

An image deployment answers `/v1/images/generations` and `/v1/images/edits`. It is priced for each image, or for tokens when your upstream bills tokens.

[Deployments](https://liquidinference.ai/docs/provider-models.md) has the fields that every kind shares, the listing statuses and the lifecycle. This page has what is special to this kind.

## Register a deployment

Copy the request, set your provider key and change the names. Every endpoint here takes the [provider key](https://liquidinference.ai/docs/provider.md) as a bearer token.

```bash
curl https://router.inference.ai.exchange/v1/provider/models \
  -H "Authorization: Bearer $LIQUID_PROVIDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "kind": "image_generation",
      "deployment_name": "flux-schnell",
      "creator": "blackforestlabs",
      "precision": "fp8",
      "region": "eu-west",
      "max_input_tokens": 4096,
      "input_modalities": [
        {
          "type": "text"
        },
        {
          "type": "image",
          "max_references": 4,
          "supports_mask": true,
          "formats": [
            "image/png"
          ]
        }
      ],
      "output_modalities": [
        {
          "type": "text"
        },
        {
          "type": "image",
          "formats": [
            "png"
          ],
          "sizes": [
            "1024x1024",
            "1536x1024",
            "1024x1536"
          ],
          "max_count": 4,
          "response_formats": [
            "b64_json",
            "url"
          ]
        }
      ]
    }'
```

```python
import os
import requests

response = requests.post(
    "https://router.inference.ai.exchange/v1/provider/models",
    headers={"Authorization": f"Bearer {os.environ['LIQUID_PROVIDER_KEY']}"},
    json={
        "kind": "image_generation",
        "deployment_name": "flux-schnell",
        "creator": "blackforestlabs",
        "precision": "fp8",
        "region": "eu-west",
        "max_input_tokens": 4096,
        "input_modalities": [
            {
                "type": "text"
            },
            {
                "type": "image",
                "max_references": 4,
                "supports_mask": True,
                "formats": [
                    "image/png"
                ]
            }
        ],
        "output_modalities": [
            {
                "type": "text"
            },
            {
                "type": "image",
                "formats": [
                    "png"
                ],
                "sizes": [
                    "1024x1024",
                    "1536x1024",
                    "1024x1536"
                ],
                "max_count": 4,
                "response_formats": [
                    "b64_json",
                    "url"
                ]
            }
        ]
    },
)
response.raise_for_status()
print(response.json()["status"])
```

```typescript
const response = await fetch('https://router.inference.ai.exchange/v1/provider/models', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LIQUID_PROVIDER_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    kind: 'image_generation',
    deployment_name: 'flux-schnell',
    creator: 'blackforestlabs',
    precision: 'fp8',
    region: 'eu-west',
    max_input_tokens: 4096,
    input_modalities: [
      {
        type: 'text',
      },
      {
        type: 'image',
        max_references: 4,
        supports_mask: true,
        formats: ['image/png'],
      },
    ],
    output_modalities: [
      {
        type: 'text',
      },
      {
        type: 'image',
        formats: ['png'],
        sizes: ['1024x1024', '1536x1024', '1024x1536'],
        max_count: 4,
        response_formats: ['b64_json', 'url'],
      },
    ],
  }),
})
if (!response.ok) throw new Error(await response.text())
console.log((await response.json()).status)
```

The answer is `201` with the registration. A new registration is `UNLISTED`. `kind` cannot change: a new kind returns `409 kind_changed`.

## What you declare

| Field                          | Where          | Meaning                                                                                                 |
| ------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------- |
| `formats`                      | `image` output | Formats it makes. Write `png` or `image/png`.                                                           |
| `sizes`                        | `image` output | Pixel sizes, such as `1024x1024`.                                                                       |
| `max_count`                    | `image` output | The most images in one response.                                                                        |
| `response_formats`             | `image` output | `url`, `b64_json` or both.                                                                              |
| `qualities`                    | `image` output | The quality names that it takes, such as `hd`.                                                          |
| `aspect_ratios`, `resolutions` | `image` output | Shapes and tiers, for an upstream that gives no pixel sizes. See [Shapes and tiers](#shapes-and-tiers). |
| `size_limits`                  | `image` output | Any size inside limits. See [Any size inside limits](#any-size-inside-limits).                          |
| `max_references`               | `image` input  | The most images that one request can reference.                                                         |
| `supports_mask`                | `image` input  | `true` when it reads the mask of an edit. See [Masks](#masks).                                          |
| `pricing_unit`                 | registration   | `tokens` when your upstream bills tokens. Then add `image_output_tokens_max`.                           |

A request for a format, size, count or quality that you did not list goes to another offer before the award.

## Shapes and tiers

Some upstreams document a tier, such as `2K`, and a shape, such as `16:9`, but not the pixel size. Do not guess the pixels. List the shapes and the tiers, and leave `sizes` empty.

```json
{
  "type": "image",
  "formats": ["png"],
  "aspect_ratios": ["1:1", "16:9", "9:16"],
  "resolutions": ["1K", "2K"],
  "max_count": 4
}
```

- A tier is `512`, `768`, `1K`, `1.5K`, `2K` or `4K`. A shape is `<width>:<height>`, with at most two decimals on each side.
- A buyer's `aspect_ratio` and `resolution` reach you only when you list the shape and the tier that the buyer states.
- If you list `sizes`, the exchange matches on the sizes and ignores the lists.
- The dispatch holds `aspect_ratio` and `resolution` of the `image` object when no offer lists a pixel size that has them. Send them to your upstream.
- To price a tier, quote a line with `{"variant": {"resolution": "2K"}}`. See [Quote a media model](https://liquidinference.ai/docs/provider-media-quote.md).

## Any size inside limits

Some upstreams take any size inside limits. gpt-image-2 takes sides that are multiples of 16, an edge of at most 3840 pixels, and 0.65 to 8.3 million pixels. Do not list every size. State the limits.

```json
{
  "type": "image",
  "size_limits": {
    "step": 16,
    "max_edge": 3840,
    "min_pixels": 655360,
    "max_pixels": 8294400,
    "max_ratio": "3:1"
  }
}
```

- `step` is the number that each side divides by. `min_edge` and `max_edge` limit the short and the long side. `min_pixels` and `max_pixels` limit the area. `max_ratio` is the long side over the short side.
- A request for a size inside the limits reaches you. A request for a shape and a tier gets a size inside the limits that has the shape and has about the area of the tier.
- Your agent writes the size for your upstream from `size_template`, such as `{width}x{height}` or `{width}*{height}`.

## Masks

A buyer can send one mask with an edit. The mask is a file in `mask`, or an entry of `input_references` with the role `mask`. It does not count toward `max_references`. Set `supports_mask` to `true` on the `image` input when your upstream reads a mask. A deployment that does not declare it never gets a request that has a mask, because it would edit the whole image and the buyer would still pay.

```json
"input_modalities": [
  { "type": "text" },
  { "type": "image", "max_references": 4, "supports_mask": true }
]
```

An agent profile names the request field of the mask with `mask_field`, and the agent then declares `supports_mask` for you. Only the edits endpoint reads a mask.

## Frame images and references

An image input also holds the limits for reference images: `max_references`, `max_bytes`, `formats` and `sources`. A deployment that declares none of them takes only text.

## Quote and serve

Quote one `output.image` line, and a `variant` for a size, a tier or a quality that costs more. See [Quote a media model](https://liquidinference.ai/docs/provider-media-quote.md#an-image-model). The route that your upstream needs, and the answer that it sends, are in [Sell images](https://liquidinference.ai/docs/provider-images.md).

```json
{ "billable": "output.image", "unit": "image", "usd": 0.04 }
```

## Charge

| Unit                             | `pricing` line                                    | Charge                                                                                                                                       |
| -------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Image                            | `output.image`, no token line                     | Rate times the images that the buyer asked for.                                                                                              |
| Tokens (`pricing_unit` `tokens`) | `input.text` and `output.text`, no `output.image` | The tokens that you meter, up to the cap: the prompt at the input rate plus `image_output_tokens_max` for each image at the generation rate. |
| Reference images                 | `input.image.reference`                           | Rate times the reference images that you metered, at most the number the exchange counted. Without the rate they are free.                   |

## Next

- Quote the deployment: [Quote over the session](https://liquidinference.ai/docs/provider-quoting.md).
- Get it on the public book: [Deployments](https://liquidinference.ai/docs/provider-models.md#from-registration-to-the-public-book).
