Managed Inference and Agents API /v1/images/generations

Last updated May 13, 2025

The /v1/images/generations endpoint generates images based on a descriptive text prompt. You can control the aspect ratio, image format, and even provide a seed for reproducibility. Optional parameters allow you to refine the output further, such as providing negative prompts to exclude specific elements.

Request Body Parameters

Use parameters to control details, such as the size and format of images you generate.

Required Parameters

Field Type Description Example
model string ID of the image generation model to use "stable-image-ultra"
prompt string text prompt describing the image to generate (max length of 10,000 characters) "A beautiful sunset over the mountains."

Optional Parameters

Field Type Description Default Example
aspect_ratio enum<string> controls the aspect ratio of the generated image
one of:"16:9", "1:1", "21:9", "2:3", "3:2", "4:5", "5:4", "9:16", or "9:21"		 "1:1" "16:9"
negative_prompt string keywords or phrases to avoid in the image (for example, "crowded" will help prevent a crowded scene)
max length:10,000 characters		 "" "crowded"
output_format enum<string> format of the output image
one of:"jpeg" or "png"		 "png" "jpeg"
size enum<string> size, in pixels, of the output image
one of: "1344x768", "1024x1024", "1536x640", "832x1216", "1216x832", "896x1088", "1088x896", "768x1344", "640x1536"		 "1024x1024" "640x1536"
seed number a starting value used as a base to generate the image from (if all parameters remain the same, images generated with the same seed will be identical, while images generated with different seeds will be similar, but not identical)
range: 0(random) to 4294967295		 0 123

Request Headers

In the following example, we assume your model resource has an alias of "DIFFUSION" (meaning you created the model resource with an --as DIFFUSION flag).

Header Type Description
Authorization string your AI add-on’s ‘DIFFUSION’ value (API bearer token)

All inference curl requests must include an Authorization header containing your Heroku Inference key for the specified model.

Response Format

When a request is successful, the API returns a JSON object with the following structure:

Field Type Description
created integer unix timestamp of when image was created
data array of objects list of generated images (always length of 1)

Data Object

Each object inside the data array includes:

Field Type Description
b64_json string (optional) generated image, encoded in base64
revised_prompt string included for compatibility with OpenAI-style responses
always: ""

Example Request

Let’s walk through an example /v1/images/generations curl request.

First, use this command to set your Heroku environment variables as local variables.

eval $(heroku config -a $APP_NAME --shell | grep '^DIFFUSION_' | sed 's/^/export /' | tee >(cat >&2))

Next, send the curl request:

curl $DIFFUSION_URL/v1/images/generations \
 -H "Authorization: Bearer $DIFFUSION_KEY" \
 -d @- <<EOF
{
  "model": "$DIFFUSION_MODEL_ID",
  "prompt": "A surreal landscape with glowing mushrooms under a night sky."
}
EOF

Here’s the same request, altered to parse the base64 and open the image on your computer:

curl $DIFFUSION_URL/v1/images/generations \
 -H "Authorization: Bearer $DIFFUSION_KEY" \
 -d @- <<EOF | jq -r '.data[0].b64_json' | base64 --decode > "x.png"
{
  "model": "$DIFFUSION_MODEL_ID",
  "prompt": "A surreal landscape with glowing mushrooms under a night sky."
}
EOF

open x.png

Example Response

{
  "created": 1745612037,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": ""
    }
  ]
}

Feedback

Log in to submit feedback.