black-forest-labs/flux-kontext-max API

本文介绍 black-forest-labs/flux-kontext-max 模型调用 API 的输入输出参数，供您使用接口时查阅字段含义。

1. 接口信息

1.1 接口类型

OPENAI 兼容接口

1.2 请求地址

POST https://api.modelverse.cn/v1/images/generations

1.3 认证方式

采用 API Key 认证，请求头格式如下：

Authorization: Bearer $MODELVERSE_API_KEY

2. 请求参数

2.1 请求体参数

字段名	类型	是否必须	默认值	描述
prompt	string	条件必填	-	生成图片的提示词（根据接口调用场景，满足条件时必须填写）
model	string	必须	-	本次请求使用的模型名称，此处固定为 black-forest-labs/flux-kontext-max
image	string	必须	-	输入图片的 base64 编码数据或 HTTP 图片链接（如 http://xxx）
n	int	可选	1	生成图片的数量，取值范围为 1~4
strength	float	可选	0.8	转换参考图像的程度，取值范围为 0~1
seed	int	可选	-1	随机数种子，用于控制模型生成内容的随机性；若需生成内容保持一致，可使用相同的 seed 值
steps	int	可选	20	模型推理次数，取值范围为 1~50
guidance_scale	float	可选	2.5	模型输出结果与 prompt 的一致程度（即生成图像的自由度）；值越大，模型自由度越小，与提示词的相关性越强，取值范围为 [1, 10]
negative_prompt	string	可选	-	负面提示词，用于指定不希望在生成图像中出现的内容
response_format	string	可选	"url"	指定返回生成图像的格式，默认为 url，可选值为 url、b64_json

3. 响应参数

字段名	类型	描述
created	integer	本次请求创建时间的 Unix 时间戳（单位：秒）
data	array	注意：URL 格式的图片链接将在生成后 7 天内失效，请务必及时保存图像。输出图像的信息，包含图像下载的 URL 或 Base64 编码，具体子字段如下：• 当 response_format 为 url 时，子字段为 url；• 当 response_format 为 b64_json 时，子字段为 b64_json。
error	Object	错误信息对象（仅请求失败时返回）
error.code	string	错误码（仅请求失败时返回）
error.message	string	错误提示信息（仅请求失败时返回）
error.param	string	请求 ID（仅请求失败时返回）

4. 调用示例

4.1 同步请求 - cURL 示例

curl --location 'https://api.modelverse.cn/v1/images/generations' \
--header "Authorization: Bearer $MODELVERSE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "black-forest-labs/flux-kontext-max",
    "prompt": "Convert to quick pencil sketch",
    "image": "data:image/png;base64,{image_base64_string}"
}'

4.2 同步请求 - Python OpenAI SDK 示例

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.getenv("BASE_URL", "https://api.modelverse.cn/v1"),
    api_key=os.getenv("API_KEY", "$MODELVERSE_API_KEY")
)

response = client.images.generate(
    model="black-forest-labs/flux-kontext-max",
    prompt="Convert to quick pencil sketch",
    extra_body={
        "image": "data:image/png;base64,{image_base64_string}"
    }
)

print(response.data[0].url)

5. 响应示例

5.1 正常响应

{
  "created": 1750667997,
  "data": [
    {
      "url": "https://xxxxx/xxxx.png",
      "b64_json": "data:image/png;base64,{image_base64_string}"
    }
  ],
  "usage": {
    "input_tokens_details": {}
  }
}

5.2 异常响应

{
  "error": {
    "message": "error_message",
    "type": "error_type",
    "param": "request_id",
    "code": "error_code"
  }
}

（注：文档部分内容可能由 AI 生成）