OpenAPI 参考

Modelink API · 图像

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

版本 1.0.0

创建 O3 文生图任务

POST

/queue/fal-ai/kling-image/o3/text-to-image

创建 Kling Image O3 文生图任务，根据文字提示生成图片。任务异步执行，创建成功后返回任务 ID，通过查询接口获取生成结果。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

BearerAuthBEARER

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

Bearer 格式：JWT

查询参数

Name
fal_webhook
Type
string<uri>
Description
推荐的 HTTPS 回调地址，需公网可访问。

请求体

请求体属性

promptstring, 必填
文生图提示词，去除首尾空白后不能为空。
resolutionenum
输出分辨率，兼容小写。
default: 1K
- 1K
- 2K
- 4K
- 1k
- 2k
- 4k
result_typeenum
文生图仅支持 single，生成独立图片；组图请使用图生图接口。
default: single
- single
num_imagesinteger
独立图片数量，仅 single 模式使用，默认 1。
default: 1; minimum: 1; maximum: 9
callback_urlstring<uri>
可选回调地址；推荐 Query 参数 fal_webhook。
aspect_ratioenum
输出画幅比例，默认 16:9。
default: 16:9
- 16:9
- 9:16
- 1:1
- 4:3
- 3:4
- 3:2
- 2:3
- 21:9

请求

POST/queue/fal-ai/kling-image/o3/text-to-image

curl 'https://api.qnaigc.com/queue/fal-ai/kling-image/o3/text-to-image?fal_webhook={fal_webhook}' \
  --request POST \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "一只橘猫坐在阳光下的窗台上",
  "resolution": "1K",
  "result_type": "single",
  "num_images": 1
}'

响应

object

任务已提交，尚未生成完成

响应体属性

statusenum, 必填
- IN_QUEUE
- IN_PROGRESS
- COMPLETED
- FAILED
request_idstring, 必填
必填。
response_urlstring, 必填
必填。
status_urlstring, 必填
必填。
cancel_urlstring, 必填
必填。
queue_positioninteger, 必填
必填。
logsobject[], 必填
- messagestring
  可选。
- levelstring
  可选。
- sourcestring
  可选。
- timestampstring
  可选。

响应

{
  "status": "IN_QUEUE",
  "request_id": "qimage-user-1791964800000000000",
  "response_url": "https://api.modelink.ai/queue/fal-ai/kling-image/requests/qimage-user-1791964800000000000",
  "status_url": "https://api.modelink.ai/queue/fal-ai/kling-image/requests/qimage-user-1791964800000000000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null
}

创建 O3 图生图 / 组图任务

POST

/queue/fal-ai/kling-image/o3/image-to-image

创建 Kling Image O3 图生图 / 组图任务，结合文字提示和参考图片生成独立图片或组图。任务异步执行，创建成功后返回任务 ID，通过查询接口获取生成结果。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

BearerAuthBEARER

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

Bearer 格式：JWT

查询参数

Name
fal_webhook
Type
string<uri>
Description
推荐的 HTTPS 回调地址，需公网可访问。

请求体

请求体属性

promptstring, 必填
提示词，去除首尾空白后不能为空；按 @Image1、@Image2 引用参考图。
resolutionenum
输出分辨率，兼容小写。
default: 1K
- 1K
- 2K
- 4K
- 1k
- 2k
- 4k
result_typeenum
single 为独立图片，series 为组图。
default: single
- single
- series
num_imagesinteger
独立图片数量，仅 single 模式使用，默认 1。
minimum: 1; maximum: 9
series_amountinteger
组图数量，仅 series 模式使用，默认 4。
minimum: 2; maximum: 9
callback_urlstring<uri>
可选回调地址；推荐 Query 参数 fal_webhook。
aspect_ratioenum
默认 auto，跟随参考图画幅；也可显式选择支持的比例。
default: auto
- auto
- 16:9
- 9:16
- 1:1
- 4:3
- 3:4
- 3:2
- 2:3
- 21:9
image_urlsstring[], 必填
参考图地址，不能为空或仅包含空白；示例使用公网可访问图片 URL。
oneOf[0]
- result_type"single"
  可选。
  const: single
- num_images
  可选。
  default: 1
oneOf[1]
- result_type"series", 必填
  必填。
  const: series
- series_amount
  可选。
  default: 4

请求

POST/queue/fal-ai/kling-image/o3/image-to-image

curl 'https://api.qnaigc.com/queue/fal-ai/kling-image/o3/image-to-image?fal_webhook={fal_webhook}' \
  --request POST \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "保留 @Image1 中的主体，将背景改为海边日落",
  "resolution": "1K",
  "result_type": "single",
  "num_images": 1,
  "image_urls": [
    "https://example.com/reference.png"
  ]
}'

响应

object

任务已提交，尚未生成完成

响应体属性

statusenum, 必填
- IN_QUEUE
- IN_PROGRESS
- COMPLETED
- FAILED
request_idstring, 必填
必填。
response_urlstring, 必填
必填。
status_urlstring, 必填
必填。
cancel_urlstring, 必填
必填。
queue_positioninteger, 必填
必填。
logsobject[], 必填
- messagestring
  可选。
- levelstring
  可选。
- sourcestring
  可选。
- timestampstring
  可选。

响应

{
  "status": "IN_QUEUE",
  "request_id": "qimage-user-1791964800000000000",
  "response_url": "https://api.modelink.ai/queue/fal-ai/kling-image/requests/qimage-user-1791964800000000000",
  "status_url": "https://api.modelink.ai/queue/fal-ai/kling-image/requests/qimage-user-1791964800000000000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null
}

查询图像生成任务

GET

/queue/fal-ai/kling-image/requests/{task_id}/status

O1 与 O3 文生图、图生图共用此查询路径。路径参数 task_id 的值为创建响应中的 request_id；建议直接使用返回的 status_url 与 response_url。进行中返回 HTTP 202；终态返回 HTTP 200。COMPLETED 不等于成功：失败/取消/过期任务也可能返回 COMPLETED，通过 detail 表示错误；成功图片位于 result.images。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

BearerAuthBEARER

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

Bearer 格式：JWT

路径参数

Name
task_id
Type
string, 必填
Description
任务 ID，由创建任务接口返回

请求体

暂无请求体

请求

GET/queue/fal-ai/kling-image/requests/{task_id}/status

curl https://api.qnaigc.com/queue/fal-ai/kling-image/requests/{task_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[], 必填
- 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

object

任务进行中

响应体属性

statusenum, 必填
- IN_QUEUE
- IN_PROGRESS
- COMPLETED
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": "IN_QUEUE",
  "request_id": "string",
  "response_url": "string",
  "status_url": "string",
  "cancel_url": "string",
  "queue_position": 42,
  "logs": [
    {
      "message": "string",
      "level": "string",
      "source": "string",
      "timestamp": "string"
    }
  ],
  "metrics": {
    "inference_time": 42
  }
}

获取结果

GET

/queue/fal-ai/kling-image/requests/{task_id}

O1 与 O3 文生图、图生图共用此查询路径。路径参数 task_id 的值为创建响应中的 request_id；建议直接使用返回的 status_url 与 response_url。成功返回顶层 images；未完成返回 HTTP 400，失败返回错误。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

BearerAuthBEARER

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

Bearer 格式：JWT

路径参数

Name
task_id
Type
string, 必填
Description
任务 ID，由创建任务接口返回

请求体

暂无请求体

请求

GET/queue/fal-ai/kling-image/requests/{task_id}

curl https://api.qnaigc.com/queue/fal-ai/kling-image/requests/{task_id} \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json'

响应

object

成功的图片结果

响应体属性

imagesobject[], 必填
- urlstring, 必填
  图片下载链接（Kodo 签名 URL，自签发之日起 7 天内有效，请及时下载并转存）。
- content_typestring
  图片 MIME 类型
- file_namestring
  文件名（可选）
- file_sizeinteger<int64>
  文件大小（字节，可选）
- widthinteger
  图片宽度（可选）
- heightinteger
  图片高度（可选）

object & object

任务尚未完成，或任务 ID / 请求参数无效。未完成时响应还包含任务状态与查询地址。

响应体属性

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

响应

{
  "images": [
    {
      "url": "string",
      "content_type": "image/png",
      "file_name": "string",
      "file_size": 42,
      "width": 42,
      "height": 42
    }
  ]
}