OpenAPI 参考

Modelink API · 图像

Modelink 图像生成 API，提供基于 OpenAI 格式的同步生成与基于 Fal 格式的异步任务能力。Fal 格式接口使用 Authorization: Key {api_key}；其他接口使用 Bearer 鉴权。

版本 1.0.0

提交文生图任务

POST

/queue/google/nano-banana-2-lite

提交 gemini-3.1-flash-lite-image 文生图异步任务。鉴权通过后创建任务并立即返回 IN_QUEUE 状态与 request_id，实际生图在后台异步执行。可通过 query 参数 fal_webhook 配置回调。

认证方式

FalApiKeyAuthAPI 密钥

Fal 格式接口鉴权方式：Authorization: Key {api_key}。

header 参数：Authorization

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

查询参数

Name
fal_webhook
Type
string<uri>
Description
可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

promptstring, 必填
文本提示词（必填，最大长度 50000）
aspect_ratioenum
画面纵横比，默认 auto。支持 4:1、1:4、8:1、1:8 等极端比例；设为 auto 时由模型根据提示词自行决定。
default: auto
- auto
- 21:9
- 16:9
- 3:2
- 4:3
- 5:4
- 1:1
- 4:5
- 3:4
- 2:3
- 9:16
- 4:1
- 1:4
- 8:1
- 1:8
num_imagesinteger
生成图片数量，默认为 1。
default: 1; minimum: 1; maximum: 1
output_formatenum
输出图片格式，默认 png
default: png
- jpeg
- png
- webp
thinking_levelenum
模型思考强度。可选 minimal 或 high，省略则不启用思考。
- minimal
- high
safety_toleranceenum
内容审核宽松度，1 最严格，6 最宽松，默认 4。
default: 4
- 1
- 2
- 3
- 4
- 5
- 6
system_promptstring
系统提示词。

请求

POST/queue/google/nano-banana-2-lite

curl 'https://api.qnaigc.com/queue/google/nano-banana-2-lite?fal_webhook={fal_webhook}' \
  --request POST \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "a cute red panda sitting on a tree branch, watercolor style",
  "aspect_ratio": "1:1",
  "output_format": "png"
}'

响应

object

任务已入队

响应体属性

statusenum, 必填
- IN_QUEUE
- IN_PROGRESS
- COMPLETED
- FAILED
request_idstring, 必填
必填。
response_urlstring
可选。
status_urlstring
可选。
cancel_urlstring
可选。
queue_positioninteger
可选。
logsobject | null
可选。

响应

{
  "status": "IN_QUEUE",
  "request_id": "string",
  "response_url": "string",
  "status_url": "string",
  "cancel_url": "string",
  "queue_position": 42,
  "logs": {}
}

提交图片编辑任务

POST

/queue/google/nano-banana-2-lite/edit

提交 gemini-3.1-flash-lite-image 图片编辑异步任务。需提供参考图 image_urls（必填）。文生图与编辑任务共用同一组状态/结果查询端点。

认证方式

FalApiKeyAuthAPI 密钥

Fal 格式接口鉴权方式：Authorization: Key {api_key}。

header 参数：Authorization

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

查询参数

Name
fal_webhook
Type
string<uri>
Description
可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

promptstring, 必填
编辑提示词（必填，最大长度 50000）
aspect_ratioenum
画面纵横比，默认 auto。支持 4:1、1:4、8:1、1:8 等极端比例。
default: auto
- auto
- 21:9
- 16:9
- 3:2
- 4:3
- 5:4
- 1:1
- 4:5
- 3:4
- 2:3
- 9:16
- 4:1
- 1:4
- 8:1
- 1:8
num_imagesinteger
生成图片数量，默认为 1。
default: 1; minimum: 1; maximum: 1
output_formatenum
输出图片格式，默认 png
default: png
- jpeg
- png
- webp
image_urlsstring<uri>[], 必填
参考图 URL 列表（必填）。用于图生图或图片编辑。
thinking_levelenum
模型思考强度。可选 minimal 或 high，省略则不启用思考。
- minimal
- high
safety_toleranceenum
内容审核宽松度，1 最严格，6 最宽松，默认 4。
default: 4
- 1
- 2
- 3
- 4
- 5
- 6
system_promptstring
系统提示词。

请求

POST/queue/google/nano-banana-2-lite/edit

curl 'https://api.qnaigc.com/queue/google/nano-banana-2-lite/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": "change the background to a sunset beach",
  "image_urls": [
    "https://example.com/input.png"
  ],
  "aspect_ratio": "auto",
  "output_format": "png"
}'

响应

object

任务已入队

响应体属性

statusenum, 必填
- IN_QUEUE
- IN_PROGRESS
- COMPLETED
- FAILED
request_idstring, 必填
必填。
response_urlstring
可选。
status_urlstring
可选。
cancel_urlstring
可选。
queue_positioninteger
可选。
logsobject | null
可选。

响应

{
  "status": "IN_QUEUE",
  "request_id": "string",
  "response_url": "string",
  "status_url": "string",
  "cancel_url": "string",
  "queue_position": 42,
  "logs": {}
}

查询任务状态

GET

/queue/google/nano-banana-2-lite/requests/{request_id}/status

查询文生图/编辑任务的状态（共用此端点，request_id 全局唯一）。进行中返回 HTTP 202，完成/失败返回 HTTP 200。

认证方式

FalApiKeyAuthAPI 密钥

Fal 格式接口鉴权方式：Authorization: Key {api_key}。

header 参数：Authorization

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

Name
request_id
Type
string, 必填
Description
任务 ID（提交接口返回的 request_id，格式 qimage-{uid}-{timestamp}）

请求体

暂无请求体

请求

GET/queue/google/nano-banana-2-lite/requests/{request_id}/status

curl https://api.qnaigc.com/queue/google/nano-banana-2-lite/requests/{request_id}/status \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json'

响应

object

任务已完成或失败

响应体属性

statusenum, 必填
- IN_QUEUE
- IN_PROGRESS
- COMPLETED
request_idstring, 必填
必填。
response_urlstring
可选。
status_urlstring
可选。
cancel_urlstring
可选。
queue_positioninteger
可选。
logsobject | null
可选。
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

object

任务进行中（IN_QUEUE / IN_PROGRESS）

响应体属性

statusenum, 必填
- IN_QUEUE
- IN_PROGRESS
- COMPLETED
request_idstring, 必填
必填。
response_urlstring
可选。
status_urlstring
可选。
cancel_urlstring
可选。
queue_positioninteger
可选。
logsobject | null
可选。
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": "IN_QUEUE",
  "request_id": "string",
  "response_url": "string",
  "status_url": "string",
  "cancel_url": "string",
  "queue_position": 42,
  "logs": {},
  "detail": {
    "loc": [
      "string"
    ],
    "msg": "string",
    "type": "string",
    "url": "string",
    "ctx": "string",
    "input": "string"
  }
}

获取任务结果

GET

/queue/google/nano-banana-2-lite/requests/{request_id}

获取文生图/编辑任务的结果（共用此端点）。任务进行中返回 HTTP 400；任务失败返回对应错误码 + fal 错误详情；任务成功返回图片结果。

认证方式

FalApiKeyAuthAPI 密钥

Fal 格式接口鉴权方式：Authorization: Key {api_key}。

header 参数：Authorization

BearerAuthBEARER

在 Authorization 请求头中传入 API Key 或访问令牌，格式：Bearer {token}。

Bearer 格式：JWT

路径参数

Name
request_id
Type
string, 必填
Description
任务 ID

请求体

暂无请求体

请求

GET/queue/google/nano-banana-2-lite/requests/{request_id}

curl https://api.qnaigc.com/queue/google/nano-banana-2-lite/requests/{request_id} \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json'

响应

object

任务失败，返回对应 HTTP 错误码和 Fal 错误详情

响应体属性

detailobject, 必填
- locstring[], 必填
  错误位置。
- msgstring, 必填
  人类可读的错误描述。
- typestring, 必填
  机器可读的错误分类标识符。
- urlstring, 必填
  错误类型文档链接。
- ctx
  附加结构化上下文（可选）。
- input
  导致错误的输入（可选）。

object | object

任务仍在进行中，或请求参数错误

响应体属性

oneOf[0]object
任务状态响应（fal queue 协议）
- statusenum, 必填
  - IN_QUEUE
  - IN_PROGRESS
  - COMPLETED
- request_idstring, 必填
  必填。
- response_urlstring
  可选。
- status_urlstring
  可选。
- cancel_urlstring
  可选。
- queue_positioninteger
  可选。
- logsobject | null
  可选。
- 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
oneOf[1]object
错误响应体（fal queue 协议）。
- detailobject, 必填
  - locstring[], 必填
    错误位置。
  - msgstring, 必填
    人类可读的错误描述。
  - typestring, 必填
    机器可读的错误分类标识符。
  - urlstring, 必填
    错误类型文档链接。
  - ctx
    附加结构化上下文（可选）。
  - input
    导致错误的输入（可选）。

响应

{
  "detail": {
    "loc": [
      "string"
    ],
    "msg": "string",
    "type": "string",
    "url": "string",
    "ctx": "string",
    "input": "string"
  }
}