Image generation

To use an image generation model, you need to use the responses API. The API accepts text and image inputs, and returns generated images as base64-encoded data. The examples below use the FLUX.2-klein-4B model, but you can replace it with any supported model that’s listed as an “Image” type.

Requirements

An API key. The code below assumes you set it in an environment variable:
export MODULAR_API_KEY="your_api_key"
$env:MODULAR_API_KEY="your_api_key"
The openai Python package. You can install it with this command:
pip install openai
uv add openai
pixi add openai
npm install openai

Generate an image

To generate an image, set input to a text description of the image and set generation parameters in provider_options.image.

import base64
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    base_url="https://api.modular.com/v1",
    api_key=os.environ.get("MODULAR_API_KEY"),
)

response = client.responses.create(
    model="black-forest-labs/FLUX.2-klein-4B",
    input="A serene mountain landscape at sunset",
    extra_body={
        "provider_options": {
            "image": {
                "height": 512,
                "width": 512,
                "steps": 4,
            }
        }
    },
)

image_data = response.output[0].content[0].image_data
Path("landscape.png").write_bytes(base64.b64decode(image_data))

import { writeFile } from "node:fs/promises";
import process from "node:process";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.modular.com/v1",
  apiKey: process.env.MODULAR_API_KEY,
});

async function main() {
  const response = await client.responses.create({
    model: "black-forest-labs/FLUX.2-klein-4B",
    input: "A serene mountain landscape at sunset",
    provider_options: {
      image: {
        height: 512,
        width: 512,
        steps: 4,
      },
    },
  });

  const image_data = response.output[0].content[0].image_data;
  await writeFile("landscape.png", Buffer.from(image_data, "base64"));
}

main();

curl -X POST https://api.modular.com/v1/responses \
  -H "Authorization: Bearer $MODULAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "black-forest-labs/FLUX.2-klein-4B",
    "input": "A serene mountain landscape at sunset",
    "provider_options": {
      "image": {
        "height": 512,
        "width": 512,
        "steps": 4
      }
    }
  }' \
  | jq -r '.output[0].content[0].image_data' \
  | base64 -d > landscape.png

You should quickly see an image that looks like this:

Transform an image

To transform an image, set input to a user message containing:

An input_image block with an image URL or base64-encoded data URI.
An input_text block describing the transformation.

This example encodes the landscape.png file created above and transforms it into a watercolor painting:

import base64
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    base_url="https://api.modular.com/v1",
    api_key=os.environ.get("MODULAR_API_KEY"),
)

input_data = base64.b64encode(Path("landscape.png").read_bytes()).decode("utf-8")

response = client.responses.create(
    model="black-forest-labs/FLUX.2-klein-4B",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_image",
                    "image_url": f"data:image/png;base64,{input_data}",
                },
                {
                    "type": "input_text",
                    "text": "Transform this image into a watercolor painting.",
                },
            ],
        }
    ],
    extra_body={
        "provider_options": {
            "image": {
                "height": 512,
                "width": 512,
                "steps": 4,
            }
        }
    },
)

image_data = response.output[0].content[0].image_data
Path("watercolor.png").write_bytes(base64.b64decode(image_data))

import { readFile, writeFile } from "node:fs/promises";
import process from "node:process";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.modular.com/v1",
  apiKey: process.env.MODULAR_API_KEY,
});

async function main() {
  const inputImage = await readFile("landscape.png");
  const image_data = inputImage.toString("base64");

  const response = await client.responses.create({
    model: "black-forest-labs/FLUX.2-klein-4B",
    input: [
      {
        role: "user",
        content: [
          {
            type: "input_image",
            image_url: `data:image/png;base64,${image_data}`,
          },
          {
            type: "input_text",
            text: "Transform this image into a watercolor painting.",
          },
        ],
      },
    ],
    provider_options: {
      image: {
        height: 512,
        width: 512,
        steps: 4,
      },
    },
  });

  const output_image_data = response.output[0].content[0].image_data;
  await writeFile("watercolor.png", Buffer.from(output_image_data, "base64"));
}

main();

IMAGE_DATA=$(base64 < landscape.png | tr -d '\n')

curl -X POST https://api.modular.com/v1/responses \
  -H "Authorization: Bearer $MODULAR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF | jq -r '.output[0].content[0].image_data' | base64 -d > watercolor.png
{
  "model": "black-forest-labs/FLUX.2-klein-4B",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_image",
          "image_url": "data:image/png;base64,$IMAGE_DATA"
        },
        {
          "type": "input_text",
          "text": "Transform this image into a watercolor painting."
        }
      ]
    }
  ],
  "provider_options": {
    "image": {
      "height": 512,
      "width": 512,
      "steps": 4
    }
  }
}
EOF

You should see the image transformed like this:

Get started

Inference

Administration

Integrations

Requirements

Generate an image

Transform an image

​Requirements

​Generate an image

​Transform an image

Requirements

Generate an image

Transform an image