Skip to main content
POST
/
v1
/
images
/
generations
Image Generation
curl --request POST \
  --url https://us.inference.heroku.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "stable-image-ultra",
  "prompt": "A serene mountain landscape at sunset with vibrant colors",
  "aspect_ratio": "16:9",
  "output_format": "png"
}
'
{
  "created": 123,
  "data": [
    {
      "b64_json": "<string>",
      "revised_prompt": "<string>"
    }
  ]
}
The /v1/images/generations endpoint generates images based on a descriptive text prompt. You can control the aspect ratio, image format, size, and provide negative prompts to refine the output.
OpenAI Compatible: This endpoint is compatible with the OpenAI Images API. You can use the OpenAI SDK by pointing it to our base URL.
View our available image models to see which models support which features.

​
Base URL

https://us.inference.heroku.com

​
Authentication

All requests must include an Authorization header with your Heroku Inference API key: 
Authorization: Bearer YOUR_DIFFUSION_KEY
You can get your API key from your Heroku app’s DIFFUSION_KEY config variable (assuming you created the model resource with an --as DIFFUSION flag).

​
Request Parameters

​
model

string · required ID of the image generation model to use. Example: "stable-image-ultra"

​
prompt

string · required Text prompt describing the image to generate.
  • Max length: 10,000 characters
Example: "A beautiful sunset over the mountains with vibrant orange and purple colors"

​
aspect_ratio

enum · optional · default: "1:1" Controls the aspect ratio of the generated image. Options: 16:9, 1:1, 21:9, 2:3, 3:2, 4:5, 5:4, 9:16, 9:21

​
size

enum · optional · default: "1024x1024" Size, in pixels, of the output image. Options: 1344x768, 1024x1024, 1536x640, 832x1216, 1216x832, 896x1088, 1088x896, 768x1344, 640x1536

​
negative_prompt

string · optional Keywords or phrases to avoid in the image. This helps prevent unwanted elements in the generated image.
  • Max length: 10,000 characters
Example: "crowded, blurry, low quality"

​
output_format

enum · optional · default: "png" Format of the output image. Options: jpeg, png

​
seed

number · optional · default: 0 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
Example: 123 for reproducible results

​
allow_ignored_params

boolean · optional · default: false Ignore unsupported parameters in request instead of throwing an error.

​
Response

​
created

integer Unix timestamp of when the image was created.

​
data

array List of generated images (always length of 1).
Each object in the data array includes:b64_json (string): Generated image, encoded in base64revised_prompt (string): Included for compatibility with OpenAI-style responses, always empty string ""

​
Examples

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

curl $DIFFUSION_URL/v1/images/generations \
  -H "Authorization: Bearer $DIFFUSION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stable-image-ultra",
    "prompt": "A serene mountain landscape at sunset with vibrant colors",
    "aspect_ratio": "16:9",
    "output_format": "png",
    "size": "1344x768"
  }'

​
Response Example

{
  "created": 1746546789,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
      "revised_prompt": ""
    }
  ]
}

​
Best Practices

​
Writing Effective Prompts

  • Be specific and descriptive about what you want to see
  • Include details about style, lighting, composition, and mood
  • Mention colors, textures, and atmosphere

​
Using Negative Prompts

  • Use negative prompts to exclude unwanted elements
  • Common negative prompts: “blurry”, “low quality”, “distorted”, “watermark”

​
Reproducibility

  • Use the same seed value to generate consistent results
  • Useful for iterating on a design or creating variations

Chat Completions

Generate text with AI

Embeddings

Generate text embeddings

AI Studio

Visual interface for image generation

Authorizations

​
Authorization
string
header
required

Bearer token using your INFERENCE_KEY

Body

application/json
​
model
string
required
Example:

"stable-image-ultra"

​
prompt
string
required
Maximum string length: 10000
​
aspect_ratio
enum<string>
default:1:1
Available options:
16:9,
1:1,
21:9,
2:3,
3:2,
4:5,
5:4,
9:16,
9:21
​
negative_prompt
string
​
output_format
enum<string>
default:png
Available options:
jpeg,
png
​
size
enum<string>
default:1024x1024
Available options:
1344x768,
1024x1024,
1536x640,
832x1216,
1216x832,
896x1088,
1088x896,
768x1344,
640x1536
​
seed
integer
default:0
Required range: 0 <= x <= 4294967295

Response

200 - application/json

Successful response

​
created
integer
​
data
object[]