Image Generation API
POST https://api.umodelverse.ai/v1/images/generations
This document introduces the input and output parameters for calling the image generation model API, providing the field meanings for your reference.
Image Generation Model List
| Model | Free Quota (Images) |
|---|---|
| black-forest-labs/flux.1-dev | 10 |
| black-forest-labs/flux-kontext-pro | 5 |
| black-forest-labs/flux-kontext-pro/multi | 5 |
| black-forest-labs/flux-kontext-pro/text-to-image | 5 |
| stepfun-ai/step1x-edit | 5 |
| black-forest-labs/flux-kontext-max | 0 |
| black-forest-labs/flux-kontext-max/multi | 0 |
| black-forest-labs/flux-kontext-max/text-to-image | 0 |
Request Parameters
Request Body
Supported Parameter List
| Field Name | Type | Required | Default | Supported Models | Description |
|---|---|---|---|---|---|
| prompt | string | Cond. | - | All | Prompt for generating the image. |
| model | string | Required | - | All | Model name to use for this request. |
| n | int | Optional | 1 | black-forest-labs/flux.1-dev black-forest-labs/flux-kontext-pro/text-to-image black-forest-labs/flux-kontext-max/text-to-image | Number of images to generate. Range [1, 4] |
| image | string | Cond. | - | black-forest-labs/flux.1-dev (optional) black-forest-labs/flux-kontext-max (required) black-forest-labs/flux-kontext-pro (required) stepfun-ai/step1x-edit (required) | Supports image URLs or Base64 encoding (format: data:image/ |
| images | array(string) | Cond. | - | black-forest-labs/flux-kontext-max/multi black-forest-labs/flux-kontext-pro/multi | Reference image array, each item should be a public URL link or the base64 encoding of the image content. |
| response_format | string | Optional | url | black-forest-labs/flux.1-dev | Specifies the return format for the generated image. url: returns the image link; b64_json: returns the Base64 encoded string. |
| size | string | Optional | 1024x1024 | black-forest-labs/flux.1-dev | Pixel dimensions of the generated image, required to be between [256x256, 1536x1536]. |
| strength | float | Optional | 0.8 | black-forest-labs/flux.1-dev | Degree of reference for the conversion image, range [0.0, 1.0]. |
| aspect_ratio | string | Optional | 1:1 | black-forest-labs/flux-kontext-max/text-to-image black-forest-labs/flux-kontext-pro/text-to-image | Aspect ratio of the generated image. Supported dimensions: “21:9”, “16:9”, “4:3”, “3:2”, “1:1”, “2:3”, “3:4”, “9:16”, “9:21” |
| steps | int | Optional | 28 | black-forest-labs/flux.1-dev stepfun-ai/step1x-edit | Number of inference steps, higher values result in more refined outputs but longer run times. |
| seed | int | Optional | -1 | All | Random seed controlling the randomness of generated content. Range from [-1, 9999999999]. If not provided, it will be generated automatically. The same seed can reproduce the same content. |
| guidance_scale | float | Optional | 2.5 | All | Used to adjust the tightness between the model’s creativity and text guidance during image generation. Higher values make the generated image more faithful to the text prompt but may reduce diversity; lower values allow more creativity and variation. Range [1, 10]. |
| negative_prompt | string | Optional | - | stepfun-ai/step1x-edit | Negative prompts used to specify content that should not appear in the generated image. |
Response Parameters
| Field Name | Type | Description |
|---|---|---|
| created | integer | Unix timestamp (seconds) for the creation time of this request. |
| data | array | Information on the output image, including the image download URL or Base64. • If the format is specified as url, then the subfield is url; • If the format is specified as b64_json, then the subfield is b64_json. Note: Links will expire 7 days after creation, so be sure to save the image promptly. |
| error | Object | Error information object |
| error.code | string | Error code |
| error.message | string | Error message |
| error.param | string | Request id |
Examples
Request
curl --location 'https://api.umodelverse.ai/v1/images/generations' \
--header 'Authorization: Bearer <Your API Key>' \
--header 'Content-Type: application/json' \
--data '{
"model": "black-forest-labs/flux-kontext-pro/text-to-image",
"prompt": "Retro game style, man in old school suit, upper body, true detective, detailed character, nigh sky, crimson moon silhouette, american muscle car parked on dark street in background, complex background in style of Bill Sienkiewicz and Dave McKean and Carne Griffiths, extremely detailed, mysterious, grim, provocative, thrilling, dynamic, action-packed, fallout style, vintage, game theme, masterpiece, high contrast, stark. vivid colors, 16-bit, pixelated, textured, distressed"
}'Response
{
"created": 1750667997,
"data": [
{
"url": "https://api.umodelverse.ai/image/xxx",
"b64_json": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU..."
}
],
"usage": {
"input_tokens_details": {}
}
}{
"error": {
"message": "xxx",
"type": "",
"param": "b4a7b49c-203c-43c9-88ce-9e636e77ace8",
"code": "xxx"
}
}OpenAI SDK Compatibility
import os
from openai import OpenAI
client = OpenAI(
base_url=os.getenv("BASE_URL", "https://api.umodelverse.ai/v1"),
# Replace with your <API_KEY>
api_key=os.getenv("API_KEY", "<API_KEY>"),
)
#
propmt = "Retro game style, man in old school suit, upper body, true detective, detailed character, nigh sky, crimson moon silhouette, american muscle car parked on dark street in background, complex background in style of Bill Sienkiewicz and Dave McKean and Carne Griffiths, extremely detailed, mysterious, grim, provocative, thrilling, dynamic, action-packed, fallout style, vintage, game theme, masterpiece, high contrast, stark. vivid colors, 16-bit, pixelated, textured, distressed"
img = client.images.generate(
prompt=propmt,
model="black-forest-labs/flux-kontext-pro/text-to-image",
extra_body={
"aspect_ratio": "9:16", # Image size
},
)
# Get the first image data from the return
img_data = img.data[0]
print("Image download link:", img_data.url)