Managed Inference and Agent API /v1/images/generations
Last updated December 18, 2024
This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.
Table of Contents
The Heroku Managed Inference and Agent add-on is currently in pilot. The products offered as part of the pilot aren’t intended for production use and are considered as a Beta Service and are subject to the Beta Services terms at https://www.salesforce.com/company/legal/agreements.jsp.
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> | specifies the format of the output image (jpeg or png) |
“png” | “jpeg” |
| size | enum<string> | specifies the 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.
For example, all /v1/images/generations curl requests should follow this pattern:
# 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))
# Sample curl request for image generation:
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