Flux Kontext API 接入文档

使用 VezAPI 密钥接入 Flux Kontext。下列操作共用同一个账号余额和鉴权方式。

服务地址： https://api.vezapi.com
请求头使用 Authorization: Bearer YOUR_VEZAPI_KEY。每次提交使用唯一的 Idempotency-Key，查询同一笔提交时才复用。

生成或编辑图像

POST/api/v1/jobs/createTask

模型标识： flux1-kontext

参数	类型	说明与限制
`callBackUrl` 可选	`string`	用于接收图像生成或编辑任务完成更新的URL地址。可选但推荐在生产环境中使用。 - 系统将在图像生成或编辑完成时向此URL发送POST请求，包含任务状态和结果 - 回调包含生成的图像URL和任务信息，支持文本生成图像和图像编辑两种操作模式 - 您的回调端点应能接受包含图像结果的JSON载荷的POST请求 - 详细的回调格式和实现指南，请参见 [图像生成/编辑回调]([see VezAPI documentation]) - 或者，您也可以使用[获取任务详情](/cn/market/common/get-task-detail)接口来轮询任务状态 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法
`input` 必填	`object`
`input.aspect_ratio` 可选	`string`	输出图像的长宽比。适用于文本到图像生成和图像编辑两种模式。对于文本到图像生成，输出图像将遵循指定的长宽比。对于图像编辑，如果提供了aspect_ratio参数，编辑后的图像将遵循该比例。如果未提供，图像将保持其原始长宽比。支持的长宽比： \| 比例 \| 格式类型 \| 常见用途 \| \|-------\|-------------\|-----------------\| \| 21:9 \| 超宽屏 \| 电影显示、全景视图 \| \| 16:9 \| 宽屏 \| 高清视频、桌面壁纸 \| \| 4:3 \| 标准 \| 传统显示器、演示文稿 \| \| 1:1 \| 正方形 \| 社交媒体帖子、头像 \| \| 3:4 \| 竖版 \| 杂志版面、人像照片 \| \| 9:16 \| 手机竖屏 \| 智能手机壁纸、故事 \| 需要特定比例时请显式传入。可选值：`"21:9", "16:9", "4:3", "1:1", "3:4", "9:16"`
`input.enable_translation` 可选	`boolean`	是否启用自动翻译功能。 - 由于 prompt 仅支持英文，当此参数为 true 时，系统会自动将非英文的提示词翻译成英文 - 如果您的提示词已经是英文，可设置为 false - 默认值：true
`input.input_image` 可选	`string`	编辑模式的输入图像 URL。编辑现有图像时需要。 - 必须是有效的图像 URL - 图像必须能被 API 服务器访问
`input.output_format` 可选	`string`	输出图像格式可选值：`"jpeg", "png"` 默认：`"jpeg"`
`input.prompt` 必填	`string`	描述所需图像或编辑的文本提示词。生成和编辑模式都需要。 - 应该详细且具体 - 对于图像编辑，描述所需的更改 - 对于图像生成，描述完整的场景 - 重要：仅支持英文
`input.prompt_upsampling` 可选	`boolean`	- 如果为 true，将对提示词进行增强处理 - 可能会增加处理时间默认：`false`
`input.safety_tolerance` 可选	`integer`	图像生成模式：输入和输出的审核级别。值范围从 0（最严格）到 6（更宽松）。图像编辑模式：输入和输出的审核级别。值范围从 0（最严格）到 2（平衡）。默认值：2 可选值：`0, 1, 2, 3, 4, 5, 6` 默认：`2`
`input.upload_cn` 可选	`boolean`	（可选）指定图片上传的服务器区域。设置为 true 时使用中国大陆服务器，false 时使用海外服务器。可根据您的地理位置选择最优的上传节点以获得更好的上传速度。
`input.watermark` 可选	`string`	要添加到生成图像的水印标识符。 - 可选 - 如果提供，将在输出图像上添加水印
`input.model` 可选	`string`	模型档位：flux-kontext-pro（默认）或 flux-kontext-max（质量更高、价格更高）。可选值：`"flux-kontext-pro", "flux-kontext-max"` 默认：`"flux-kontext-pro"`
`model` 必填	`string`	用于生成的模型版本。可选值：`"flux1-kontext"` 默认：`"flux1-kontext"`

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "callBackUrl": "https://example.com/input.png",
  "input": {
    "aspect_ratio": "16:9",
    "enable_translation": true,
    "output_format": "jpeg",
    "prompt": "A serene mountain landscape at sunset with a lake reflecting the orange sky",
    "prompt_upsampling": false
  },
  "model": "flux1-kontext"
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`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`
`msg` 可选	`string`	Error message when code != 200
`data` 可选	`object`
`data.taskId` 可选	`string`	Task ID, can be used with [Get Task Details](/market/common/get-task-detail) to query task status

HTTP 500

服务器错误

任务状态与回调

异步任务请保存返回的 taskId。调用 GET /api/v1/jobs/recordInfo?taskId=... 查询，或在创建时设置 callBackUrl。只有任务所属账号可以查询任务或基于任务创建派生资源。

超时可能表示请求已经受理。请在控制台查看原请求，不要自动新建任务。回调可能重试并重复到达，请使用 X-VezAPI-Event-Id 去重。

文件、日志与计费

生成媒体通常随上游保留 14 天，上传文件在 24 小时后失效。请在过期前保存所需文件。VezAPI 仅流式转发已登记资源，不提供永久作品库。请求日志保留两个自然月。

调用前预留积分，最终按实际优惠扣分 1:1 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算，会保留待结算记录，补足余额后再扣费；模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长，读取失败时不提交模型任务。