OpenAPI 参考
Modelink API · 图像
Modelink 图像 API，提供 OpenAI 格式、火山格式的同步生图，以及基于 Fal 格式的异步任务能力。Fal 格式接口使用 Authorization: Key {api_key}；其他接口使用 Bearer 鉴权。
版本 1.0.0
提交文生图任务
提交 google/gemini-nano-banana-2.1 文生图异步任务。模型由路径选择，请求体无需 model 字段。支持 1K/2K/4K（不支持 0.5K）及极端画幅比例；默认 aspect_ratio=auto、resolution=1K、output_format=png、thinking_level=medium。每次仅返回 1 张最终图，不返回思考过程临时图。seed、enable_web_search、limit_generations、sync_mode 仅兼容接收，未实现相应行为；即使 sync_mode=true 也返回异步任务。
文生图和编辑共用查询端点：/queue/google/nano-banana-2.1/requests/{request_id}/status 和 /queue/google/nano-banana-2.1/requests/{request_id}（不带 /edit）。可使用提交响应中的 status_url/response_url 查询；回调支持 callback_url 或 fal_webhook，详见 FAL 格式 Webhook。
认证方式
Fal 格式接口鉴权方式：Authorization: Key {api_key}。
查询参数
- Name
- fal_webhook
- Type
- string<uri>
- Description
可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。
请求体
请求体属性
- promptstring, 必填
必填且不能仅含空白，最多 50000 字节（UTF-8）。maxLength 按字符计数，仅表达必要上限；包含中文等多字节字符时，请同时按 UTF-8 编码后的字节数检查，超限返回参数错误。
- aspect_ratioenum
画面纵横比，支持 4:1、1:4、8:1 和 1:8 等极端比例。
default: auto
auto21:916:93:24:35:41:14:53:42:39:164:11:48:11:8
- resolutionenum
输出分辨率，不支持 0.5K；接受小写 k 并归一化为大写 K。
default: 1K
1K2K4K1k2k4k
- output_formatenum
输出图片格式。
default: png
jpegpngwebp
- thinking_levelenum
模型思考强度；默认 medium，映射为上游 reasoning_effort。
default: medium
minimalmediumhigh
- safety_toleranceenum
内容审核宽松度，1 最严格，6 最宽松。
123456
- system_promptstring
引导模型风格的系统提示词。
- num_imagesenum
仅支持单张最终图，省略或传 0 均按 1 处理；负数或大于 1 返回参数错误。
default: 1
01
- callback_urlstring<uri>
可选回调地址；也可使用查询参数 fal_webhook。地址要求和回调结构见 FAL 格式 Webhook。
请求
curl 'https://api.qnaigc.com/queue/google/nano-banana-2.1?fal_webhook={fal_webhook}' \
--request POST \
--header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"prompt": "一只橘猫坐在窗边，柔和的晨光，写实摄影",
"aspect_ratio": "auto",
"resolution": "1K",
"output_format": "png",
"thinking_level": "medium"
}'响应
任务已入队
响应体属性
- statusenum, 必填
IN_QUEUEIN_PROGRESSCOMPLETEDFAILED
- request_idstring, 必填必填。
- response_urlstring, 必填必填。
- status_urlstring, 必填必填。
- cancel_urlstring, 必填必填。
- queue_positioninteger, 必填必填。
- logsobject[], 必填
- messagestring可选。
- levelstring可选。
- sourcestring可选。
- timestampstring可选。
响应
{
"status": "IN_QUEUE",
"request_id": "qimage-example-123",
"response_url": "https://api.qnaigc.com/queue/google/nano-banana-2.1/requests/qimage-example-123",
"status_url": "https://api.qnaigc.com/queue/google/nano-banana-2.1/requests/qimage-example-123/status",
"cancel_url": "",
"queue_position": 0,
"logs": null
}提交图片编辑任务
提交 google/gemini-nano-banana-2.1 图片编辑异步任务。image_urls 必填，支持 1～14 张参考图，不支持 mask；video_url、audio_url、pdf_url 仅兼容接收，不作为模型输入。支持 1K/2K/4K（不支持 0.5K）及极端画幅比例；默认 aspect_ratio=auto、resolution=1K、output_format=png、thinking_level=medium。每次仅返回 1 张最终图，不返回思考过程临时图。seed、enable_web_search、limit_generations、sync_mode 仅兼容接收，未实现相应行为；即使 sync_mode=true 也返回异步任务。
文生图和编辑共用查询端点：/queue/google/nano-banana-2.1/requests/{request_id}/status 和 /queue/google/nano-banana-2.1/requests/{request_id}（不带 /edit）。可使用提交响应中的 status_url/response_url 查询；回调支持 callback_url 或 fal_webhook，详见 FAL 格式 Webhook。
认证方式
Fal 格式接口鉴权方式：Authorization: Key {api_key}。
查询参数
- Name
- fal_webhook
- Type
- string<uri>
- Description
可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。
请求体
请求体属性
- promptstring, 必填
必填且不能仅含空白，最多 50000 字节（UTF-8）。maxLength 按字符计数，仅表达必要上限；包含中文等多字节字符时，请同时按 UTF-8 编码后的字节数检查，超限返回参数错误。
- image_urlsstring<uri>[], 必填
参考图 URL 列表，不支持 mask。
- aspect_ratioenum
画面纵横比，支持 4:1、1:4、8:1 和 1:8 等极端比例。
default: auto
auto21:916:93:24:35:41:14:53:42:39:164:11:48:11:8
- resolutionenum
输出分辨率，不支持 0.5K；接受小写 k 并归一化为大写 K。
default: 1K
1K2K4K1k2k4k
- output_formatenum
输出图片格式。
default: png
jpegpngwebp
- thinking_levelenum
模型思考强度；默认 medium，映射为上游 reasoning_effort。
default: medium
minimalmediumhigh
- safety_toleranceenum
内容审核宽松度，1 最严格，6 最宽松。
123456
- system_promptstring
引导模型风格的系统提示词。
- num_imagesenum
仅支持单张最终图，省略或传 0 均按 1 处理；负数或大于 1 返回参数错误。
default: 1
01
- callback_urlstring<uri>
可选回调地址；也可使用查询参数 fal_webhook。地址要求和回调结构见 FAL 格式 Webhook。
请求
curl 'https://api.qnaigc.com/queue/google/nano-banana-2.1/edit?fal_webhook={fal_webhook}' \
--request POST \
--header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"prompt": "将画面转换为水彩插画风格，保留主体轮廓",
"aspect_ratio": "auto",
"resolution": "1K",
"output_format": "png",
"thinking_level": "medium",
"image_urls": [
"https://example.com/input.png"
]
}'响应
任务已入队
响应体属性
- statusenum, 必填
IN_QUEUEIN_PROGRESSCOMPLETEDFAILED
- request_idstring, 必填必填。
- response_urlstring, 必填必填。
- status_urlstring, 必填必填。
- cancel_urlstring, 必填必填。
- queue_positioninteger, 必填必填。
- logsobject[], 必填
- messagestring可选。
- levelstring可选。
- sourcestring可选。
- timestampstring可选。
响应
{
"status": "IN_QUEUE",
"request_id": "qimage-example-123",
"response_url": "https://api.qnaigc.com/queue/google/nano-banana-2.1/requests/qimage-example-123",
"status_url": "https://api.qnaigc.com/queue/google/nano-banana-2.1/requests/qimage-example-123/status",
"cancel_url": "",
"queue_position": 0,
"logs": null
}查询任务状态
文生图和图片编辑共用此查询端点（不带 /edit）。查询文生图或图片编辑任务状态。进行中返回 HTTP 202 和 IN_QUEUE 或 IN_PROGRESS；完成或失败返回 HTTP 200 和 COMPLETED，失败详情通过 detail 提供。
认证方式
Fal 格式接口鉴权方式：Authorization: Key {api_key}。
路径参数
- Name
- request_id
- Type
- string, 必填
- Description
提交任务时返回的
request_id。
请求体
暂无请求体
请求
curl https://api.qnaigc.com/queue/google/nano-banana-2.1/requests/{request_id}/status \
--header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
--header 'Accept: application/json'响应
任务已完成或失败
响应体属性
- statusenum, 必填
IN_QUEUEIN_PROGRESSCOMPLETED
- request_idstring, 必填必填。
- response_urlstring, 必填必填。
- status_urlstring, 必填必填。
- cancel_urlstring, 必填必填。
- queue_positioninteger, 必填必填。
- logsobject[], 必填
- messagestring可选。
- levelstring可选。
- sourcestring可选。
- timestampstring可选。
- metricsobject
任务完成时返回的执行指标。
- inference_timenumber<double>
从任务创建到完成的耗时，单位为秒。
- detailobject
任务失败或结果尚未就绪时返回的错误详情。
- locstring[], 必填
错误位置。
- msgstring, 必填
人类可读的错误描述。
- typestring, 必填
机器可读的错误分类标识符。
- urlstring, 必填
错误类型文档链接。
- ctx
附加结构化上下文（可选）。
- input
导致错误的输入（可选）。
- resultobject
任务成功完成时返回的图片结果。异步生图用量仅位于 result.usage；状态响应顶层不重复返回 usage。
- imagesobject[], 必填
- urlstring, 必填
图片下载链接（Kodo 签名 URL，自签发之日起 7 天内有效，请及时下载并转存）。
- content_typestring
图片 MIME 类型
- file_namestring
文件名（可选）
- file_sizeinteger<int64>
文件大小（字节，可选）
- widthinteger
图片宽度（可选）
- heightinteger
图片高度（可选）
- usageobject
异步生图任务的 Token 用量。仅在任务成功完成且存在用量记录时返回；历史任务可能不含此字段。明细字段已包含在对应的输入或输出总量中，详见 Usage 字段与计费对账。
- total_tokensinteger, 必填
总 Token 数，等于 input_tokens 与 output_tokens 之和。
minimum: 0
- input_tokensinteger, 必填
输入 Token 数。
minimum: 0
- output_tokensinteger, 必填
输出 Token 数。
minimum: 0
- input_tokens_detailsobject
输入 Token 明细。仅在上游提供对应数据时返回。
- text_tokensinteger
文本输入 Token 数。
minimum: 0
- image_tokensinteger
图片输入 Token 数。
minimum: 0
- output_tokens_detailsobject
输出 Token 明细。仅在上游提供对应数据时返回。
- image_tokensinteger
图片输出 Token 数。
minimum: 0
- reasoning_tokensinteger
推理 Token 数。部分 Gemini 模型可能返回。
minimum: 0
- text_tokensinteger
文本输出 Token 数。
minimum: 0
响应
{
"status": "COMPLETED",
"request_id": "qimage-example-123",
"response_url": "https://api.qnaigc.com/queue/google/nano-banana-2.1/requests/qimage-example-123",
"status_url": "https://api.qnaigc.com/queue/google/nano-banana-2.1/requests/qimage-example-123/status",
"cancel_url": "",
"queue_position": 0,
"logs": null,
"metrics": {
"inference_time": 38
},
"result": {
"images": [
{
"url": "https://aitoken-image.qnaigc.com/gemini-image/example/qimage-example-123/0.png?e=1780000000&token=example",
"content_type": "image/png"
}
],
"usage": {
"total_tokens": 1320,
"input_tokens": 15,
"output_tokens": 1305,
"input_tokens_details": {
"text_tokens": 15,
"image_tokens": 0
},
"output_tokens_details": {
"image_tokens": 1290,
"reasoning_tokens": 12,
"text_tokens": 3
}
}
}
}获取任务结果
文生图和图片编辑共用此查询端点（不带 /edit）。获取文生图或图片编辑任务结果。任务进行中返回 HTTP 400 状态响应；参数错误返回 Fal 错误响应；任务失败返回对应错误码和 Fal 错误详情；成功返回 Fal 格式图片列表。成功时 images 数组仅包含 1 张最终图，usage 保留完整 Token 用量（含思考 Token）。
认证方式
Fal 格式接口鉴权方式：Authorization: Key {api_key}。
路径参数
- Name
- request_id
- Type
- string, 必填
- Description
提交任务时返回的
request_id。
请求体
暂无请求体
请求
curl https://api.qnaigc.com/queue/google/nano-banana-2.1/requests/{request_id} \
--header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
--header 'Accept: application/json'响应
任务失败，返回对应 HTTP 错误码和 Fal 错误详情
响应体属性
- detailobject, 必填
- locstring[], 必填
错误位置。
- msgstring, 必填
人类可读的错误描述。
- typestring, 必填
机器可读的错误分类标识符。
- urlstring, 必填
错误类型文档链接。
- ctx
附加结构化上下文（可选）。
- input
导致错误的输入（可选）。
响应
{
"detail": {
"loc": [
"string"
],
"msg": "string",
"type": "string",
"url": "string",
"ctx": "string",
"input": "string"
}
}'%3e%3cpath%20d='M44.867217,0.0054376148%20C130.715579,1.00591567%20200,70.9091172%20200,156.994562%20L199.986321,155.127494%20C199.384888,180.009127%20179.026368,199.994562%20154,199.994562%20L46,199.994562%20C20.5949015,199.994562%200,179.399661%200,153.994562%20L0,45.9945624%20C0,21.0975659%2019.7793434,0.820282524%2044.4815926,0.0191499894%20Z'%20fill='%2300D492'%3e%3c/path%3e%3cpath%20d='M123.867217,0.0054376148%20C209.715579,1.00591567%20279,70.9091172%20279,156.994562%20L278.986321,155.127494%20C278.384888,180.009127%20258.026368,199.994562%20233,199.994562%20L125,199.994562%20C99.5949015,199.994562%2079,179.399661%2079,153.994562%20L79,45.9945624%20C79,21.0975659%2098.7793434,0.820282524%20123.481593,0.0191499894%20Z'%20id='clarify-right'%20fill-opacity='0.6'%20fill='%2300F6C9'%20transform='translate(179,%20100)%20rotate(-90)%20translate(-179,%20-100)'%3e%3c/path%3e%3cpath%20d='M199.979267,154.416906%20L199.984438,155.157125%20L199.962366,155.872459%20C198.977251,180.406837%20178.776104,199.994562%20154,199.994562%20L124.372438,199.994125%20L124.249053,199.994081%20C99.6939678,199.603921%2079.8122712,179.973634%2079.01915,155.518407%20L79.0054376,155.132783%20C79.5830823,105.566626%20103.129768,61.5221348%20139.498462,33.1463428%20C175.69419,61.3871018%20199.186123,105.143863%20199.979267,154.416906%20Z'%20id='形状结合'%20fill='%2300F692'%3e%3c/path%3e%3c/g%3e%3c/g%3e%3c/svg%3e)