FLUX 3 Image

接口提示

flux_3_image 支持文生图、单图编辑和多图参考, 每次固定生成一张 PNG 图片

flux_3_image 推荐通过异步创建与查询获取结果, 尤其是 4k 或多图参考任务

n 不控制输出数量, 每个任务仍只生成一张图片

认证

authorization `string` 必需

所有 API 均使用 Bearer Token 鉴权

获取 API Key：

访问 API Key 管理页面获取 API Key

用法：

将以下 Header 添加到请求中：

Authorization: Bearer YOUR_API_KEY

参数

使用 POST /model/v1/generation 创建任务. 请求体包含 model 和 input, 图片参数放在 input[0].params 中

右侧提供文生图、单图编辑和多图参考示例. 参考图示例 URL 为占位地址, 需要替换为服务端可访问的真实图片地址

model `string` 必需

请求使用的模型 ID

值: flux_3_image

input `array` 必需

输入列表, 仅包含一个对象

params object 必需

图片生成或编辑参数

prompt string 必需

画面描述或对参考图的修改指令, 支持中文和英文. 参考图按传入顺序称为 Image 1、Image 2 等, 可在提示词中引用. 需要指定布局时, 可在提示词中包含布局 JSON

images string | string[]

参考图. 文生图时省略, 单图编辑时传一张, 多图参考时按提示词中的顺序传入. 每张支持服务端可访问的 HTTP(S) URL、纯 Base64 或 data:image/...;base64,.... URL 在处理期间需保持有效

范围: 传入时为 1–10 张

image string | string[]

images 的兼容字段, 推荐使用 images, 不要同时传入两个字段

resolution string

分辨率档位, 同时用于选择计价档位. 实际图片宽高随比例和内容变化, 档位不表示固定宽高. 参数会去除首尾空格并转为小写

默认值: 1k

可选值: 768sq, 1k, 1.5k, 2k, 4k

aspect_ratio string

图片宽高比. auto 在无参考图时根据提示词决定比例, 有参考图时沿用第一张参考图的比例

默认值: auto

可选值: 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2, 9:21, auto

size string

兼容尺寸参数, 按下表派生分辨率档位和宽高比, 也接受 * 或 × 分隔符. 显式 resolution 和 aspect_ratio 分别优先于派生值. 推荐直接设置这两个参数

response_format string

图片生成结果的处理格式. 两种选项最终均通过统一响应中的 output[].content[].url 交付平台图片地址, 不向客户返回 b64_json 字段

默认值: b64_json

可选值: b64_json, url

grounding boolean

是否允许联网检索网页和图片以理解提示词, 可用于真实人物、地点或品牌相关内容. 设置为 false 可关闭

默认值: true

safety_tolerance integer

内容审核宽松度, 数值越大越宽松

默认值: 2

范围: 0–4

size 兼容映射

size	派生 resolution	派生 aspect_ratio
`1024x1024`	`1k`	`1:1`
`1792x1024`	`1.5k`	`16:9`
`2048x2048`	`2k`	`1:1`

其他 size 仅在同时提供有效的显式 resolution 和 aspect_ratio 时接受, 否则创建请求返回 HTTP 400. 不根据任意尺寸面积推测分辨率档位

例如 size=2048x2048、resolution=1k、aspect_ratio=4:3 同时传入时, 按 1k 档和 4:3 比例执行及计价

轮询

由于结果生成需要时间，您需要在创建任务后轮询任务状态

初始响应只返回任务 ID 和初始状态等信息，最终生成结果需通过使用该任务 ID 轮询任务状态接口获取

轮询请求与响应示例见右侧

创建接口为 POST /model/v1/generation, 查询接口为 GET /model/v1/generation/task/{task_id}. 将创建响应的 id 填入查询路径

创建响应即使返回 status: "completed", 也仅代表创建请求完成, 不代表图片生成或扣费完成. 应继续查询同一任务

建议每隔 5 秒查询一次. 查询状态为 in_progress 时继续等待, 为 completed 且存在图片结果时读取 output[].content[], 为 failed 时停止查询并检查 error. 若返回 in_queue, 继续等待

同步调用

POST /model/v1/generation/sync 使用相同请求体, 等待任务完成后返回图片结果. 以下为文生图示例：

curl --location 'https://cloud.vtrix.ai/model/v1/generation/sync' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "model": "flux_3_image",
  "input": [
    {
      "params": {
        "prompt": "A pink ceramic cup on a white table, studio photograph",
        "resolution": "768sq",
        "aspect_ratio": "1:1"
      }
    }
  ]
}'

生成时间随分辨率、参考图和服务负载变化. 同步等待期间连接可能中断, 后台任务仍可能继续生成并在成功后扣费. 已取得任务 ID 时应查询原任务; 未取得时先核对任务记录或联系支持, 避免直接重新提交造成第二笔生成费用. 长耗时任务推荐使用异步创建与查询

响应格式

右侧展示创建、处理中和成功查询示例. 任务 ID、图片 URL 和改写提示词为示意值; 金额为一次测试示例, 不代表固定报价

id `string`

平台任务 ID, 用于查询该任务

created_at `integer`

任务创建时间, Unix 毫秒时间戳

status `string`

任务查询状态, 常见值为 in_queue、in_progress、completed、failed. 创建响应中的同名字段不用于判断最终生成结果

model `string`

本次请求使用的模型 ID

output `array`

成功查询返回一张图片, 路径为 output[].content[]

content array

图片内容列表

type string

值: image

url string

平台图片下载地址. 地址可能包含签名参数, 请保留完整 URL 并及时下载保存, 不应假定永久有效

size integer

图片文件大小, 单位为字节, 不是图片宽高

revised_prompt string

可选, 生成过程中改写后的提示词

usage `object`

成功查询返回的用量与计价信息. 金额以 USD 表示

字段	类型	说明
`quantity`	number	计费数量, 固定为 `1` 张
`image_count`	integer	输出图片数量, 为 `1`
`extra_info.num_images`	integer	图片数量, 为 `1`
`unit_price`	string	命中分辨率档位的计价单价
`cost`	string	本次任务的计价金额, 不应直接当作最终实扣
`payable_amount`	string 或 null	从平台账单读取的应付金额
`charged_amount`	string 或 null	从平台账单读取的实际扣费金额
`user_discount`	number	兼容字段, 不用于自行重算最终折扣; `0` 不代表免费
`input_tokens` / `output_tokens` / `total_tokens`	number 或 null	按图片计费, 示例中为 `null`

payable_amount、charged_amount 在账单暂不可用时可能为 null, 不代表免费或未扣费, 可稍后查询并核对平台账单

error `object`

失败时的错误信息, 优先读取 error.message. 如返回 error.code, 可一并用于排查. 不依赖示例错误文本进行程序判断

失败查询结构示例：

{
  "id": "task_id",
  "created_at": 1792207683000,
  "status": "failed",
  "model": "flux_3_image",
  "error": {
    "message": "Image generation failed"
  }
}

错误处理

场景	处理方式
非法 `resolution` 或无法映射的 `size`	创建请求返回 HTTP 400, 检查参数后再提交
非法比例、审核参数或无法访问的参考图	可能创建任务后失败, 轮询原任务并读取 `error`
图片生成或结果存储失败	任务为 `failed`, 不收取成功生成费用
同步连接中断或超时	不据此判定任务失败, 先核对原任务状态和账单

计费说明

按请求选定的 resolution 档位计价, 每次成功输出按 1 张计量. 未指定 resolution 且未使用 size 映射时, 默认使用 1k

768sq、1k、1.5k、2k、4k 为计价档位, 不根据实际图片宽高重新选档. 参考图数量和 n 不增加该任务的计费数量. 文生图、单图编辑和多图参考使用相同的分辨率档位规则

失败任务不收取成功生成费用. 客户端同步连接中断不等于任务失败, 后台成功完成的任务仍可能计费

具体售价、汇率与账户折扣以平台配置为准, 参见计费说明. 最终实扣以平台账单为准, 不通过 cost 或 user_discount 自行推算

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "flux_3_image", "input": [ { "params": { "prompt": "A red ceramic teapot on a wooden table, studio photograph", "resolution": "768sq", "aspect_ratio": "1:1" } } ] }'

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "flux_3_image", "input": [ { "params": { "prompt": "Change the teapot glaze in Image 1 to cobalt blue, keep the composition", "images": [ "https://example.com/input-image.png" ], "resolution": "2k", "aspect_ratio": "1:1" } } ] }'

curl --location 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "flux_3_image", "input": [ { "params": { "prompt": "Use the subject from Image 1 and the composition from Image 2, watercolor style", "images": [ "https://example.com/subject.png", "https://example.com/composition.png" ], "resolution": "1k", "aspect_ratio": "16:9" } } ] }'

{ "id": "task_id", "created_at": 1792207683000, "status": "completed", "model": "flux_3_image", "output": [ { "content": [ { "revised_prompt": "A studio photograph of a red ceramic teapot on a wooden table.", "size": 842507, "type": "image", "url": "https://example.com/generated-image.png" } ] } ], "usage": { "charged_amount": "0.041", "cost": "0.041", "extra_info": { "num_images": 1 }, "image_count": 1, "input_tokens": null, "output_tokens": null, "payable_amount": "0.041", "quantity": 1, "total_tokens": null, "unit_price": "0.041", "user_discount": 0 } }

接口提示

认证

authorization `string` 必需

参数

model `string` 必需

input `array` 必需

params `object` 必需

prompt `string` 必需

images `string | string[]`

image `string | string[]`

resolution `string`

aspect_ratio `string`

size `string`

response_format `string`

grounding `boolean`

safety_tolerance `integer`

size 兼容映射

轮询

同步调用

响应格式

id `string`

created_at `integer`

status `string`

model `string`

output `array`

content `array`

type `string`

url `string`

size `integer`

revised_prompt `string`

usage `object`

error `object`

错误处理

计费说明

接口提示

认证

authorization string 必需

参数

model string 必需

input array 必需

params object 必需

prompt string 必需

images string | string[]

image string | string[]

resolution string

aspect_ratio string

size string

response_format string

grounding boolean

safety_tolerance integer

size 兼容映射

轮询

同步调用

响应格式

id string

created_at integer

status string

model string

output array

content array

type string

url string

size integer

revised_prompt string

usage object

error object

错误处理

计费说明

authorization `string` 必需

model `string` 必需

input `array` 必需

params `object` 必需

prompt `string` 必需

images `string | string[]`

image `string | string[]`

resolution `string`

aspect_ratio `string`

size `string`

response_format `string`

grounding `boolean`

safety_tolerance `integer`

id `string`

created_at `integer`

status `string`

model `string`

output `array`

content `array`

type `string`

url `string`

size `integer`

revised_prompt `string`

usage `object`

error `object`