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 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 as a bearer token.

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"
          ]
        }
      ]
    }'
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"])
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.
size_limits image output Any size inside limits. See 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.
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.

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

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.

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

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.

"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. The route that your upstream needs, and the answer that it sends, are in Sell images.

{ "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