Generate or Edit Image

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /jobs/createTask

Full URL: https://ai.modelfold.online/v1/jobs/createTask

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

WARNING

This is the new version of the API documentation; for the old version of the API, please see https://ai.modelfold.online/docs/en/flux-kontext-api/generate-or-edit-image.

Create a new image generation or editing task using the Flux Kontext AI model.

Usage Modes

1. Text-to-Image Generation

   • Provide prompt and aspect_ratio
   • Model will generate a new image based on the text description

2. Image Editing

   • Provide prompt and input_image
   • You can optionally provide an aspect_ratio.
     • If supplied, the output will be cropped or padded to match this ratio.
     • If omitted, the original image's ratio will be preserved.
   • Model will edit the input image according to the prompt

Important Notes

• Generated images will expire after 14 days
• Prompts only support English
• Use input.model to choose flux-kontext-pro or flux-kontext-max:
  • flux-kontext-pro: Standard model for most use cases
  • flux-kontext-max: Enhanced model for complex scenes

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
model	string	Yes	Model version to use for generation. Default："flux1-kontext"。 Allowed values：flux1-kontext。 示例：flux1-kontext。
callBackUrl	string	No	The URL to receive image generation or editing task completion updates. Optional but recommended for production use. - System will POST task status and results to this URL when image generation or editing completes - Callback includes generated image URLs and task information for both text-to-image and image editing operations - Your callback endpoint should accept POST requests with JSON payload containing image results - For detailed callback format and implementation guide, see Image Generation/Editing Callbacks - Alternatively, use Get Task Details to poll task status - To ensure callback security, see Webhook Verification Guide for signature verification implementation 示例：https://your-domain.com/api/callback。
input	object	Yes	—
input.prompt	string	Yes	Text prompt describing the desired image or edit. Required for both generation and editing modes. - Should be detailed and specific - For image editing, describe the desired changes - For image generation, describe the complete scene - IMPORTANT: Only English language is supported 示例：A serene mountain landscape at sunset with a lake reflecting the orange sky。
input.model	string	No	Model tier: flux-kontext-pro (default) or flux-kontext-max (higher quality, higher price). Default："flux-kontext-pro"。 Allowed values：flux-kontext-pro / flux-kontext-max。 示例：flux-kontext-pro。
input.enable_translation	boolean	No	Whether to enable automatic translation feature. - Since prompt only supports English, when this parameter is true, the system will automatically translate non-English prompts to English - If your prompt is already in English, you can set this to false - Default value: true 示例：true。
input.upload_cn	boolean	No	(Optional) Specifies the server region for image upload. Set to true to use servers in China, false to use non-China servers. Choose based on your geographical location for optimal upload speeds. 示例：false。
input.input_image	string	No	URL of the input image for editing mode. Required when editing an existing image. - Must be a valid image URL - Image must be accessible to the API server 示例：https://example.com/input-image.jpg。
input.aspect_ratio	string	No	Output image aspect ratio. You Applicable in both text-to-image generation and image editing modes. For text-to-image generation , the output image will follow the specified aspect ratio. For image editing , if aspect_ratio is provided, the edited image will follow that ratio. If not provided, the image will retain its original aspect ratio. Supported Aspect Ratios:
input.output_format	string	No	Output image format. Default："jpeg"。 Allowed values：jpeg / png。 示例：jpeg。
input.prompt_upsampling	boolean	No	- If true, performs upsampling on the prompt - May increase processing time Default：false。 示例：false。
input.safety_tolerance	integer	No	For Image Generation Mode: Moderation level for inputs and outputs. Value ranges from 0 (most strict) to 6 (more permissive). For Image Editing Mode: Moderation level for inputs and outputs. Value ranges from 0 (most strict) to 2 (balanced). Default: 2 Default：2。 Allowed values：0 / 1 / 2 / 3 / 4 / 5 / 6。 示例：2。
input.watermark	string	No	Watermark identifier to add to the generated image. - Optional - If provided, a watermark will be added to the output image 示例：your-watermark-id。

Request Example

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "flux1-kontext",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "A serene mountain landscape at sunset with a lake reflecting the orange sky",
    "enable_translation": true,
    "aspect_ratio": "16:9",
    "output_format": "jpeg",
    "prompt_upsampling": false
  }
}'

{
  "model": "flux1-kontext",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "A serene mountain landscape at sunset with a lake reflecting the orange sky",
    "enable_translation": true,
    "aspect_ratio": "16:9",
    "output_format": "jpeg",
    "prompt_upsampling": false
  }
}

Response

200 — Request successful

参数	类型	必填	说明
code	integer	否	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：200 / 401 / 402 / 404 / 422 / 429 / 455 / 500 / 501 / 505。 示例：200。
msg	string	否	Error message when code != 200 示例：success。
data	object	否	—
data.taskId	string	否	Task ID, can be used with Get Task Details to query task status 示例：task12345。

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task12345"
  }
}

500 — Server error.

参数	类型	必填	说明
code	integer	是	Response status code - 200: Success - Request has been processed successfully - 401: Unauthorized - Authentication credentials are missing or invalid - 402: Insufficient Credits - Account does not have enough credits to perform the operation - 404: Not Found - The requested resource or endpoint does not exist - 408: Timeout - No result has been returned for over 10 minutes. - 422: Validation Error - The request parameters failed validation checks - 429: Rate Limited - Request limit has been exceeded for this resource - 455: Service Unavailable - System is currently undergoing maintenance - 500: Server Error - An unexpected error occurred while processing the request - 501: Generation Failed - Content generation task failed - 505: Feature Disabled - The requested feature is currently disabled
msg	string	是	Response message, error description when failed
data	object	是	—

{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}

Callback

onImageGenerated

Callback URL: {$request.body#/callBackUrl} (the callBackUrl in the request body).

When the image generation task is completed, the system will send the result to your provided callback URL via POST request

Callback body parameters

参数	类型	必填	说明
code	integer	否	Status code - 200: Success - Image generation completed successfully - 400: Failed - Your prompt was flagged by Website as violating content policies. - 500: Failed - Internal Error, Please try again later. - 501: Failed - Image generation task failed Allowed values：200 / 400 / 500 / 501。 示例：200。
msg	string	否	Status message 示例：Image generated successfully.。
data	object	否	—
data.taskId	string	否	Task ID 示例：task12345。
data.info	object	否	—
data.info.resultImageUrl	string	否	Generated image URL on our server 示例：https://example.com/result.jpg。

{
  "code": 200,
  "msg": "Image generated successfully.",
  "data": {
    "taskId": "task12345",
    "info": {
      "resultImageUrl": "https://example.com/result.jpg"
    }
  }
}