Modelink

OpenAPI 参考

Modelink API · 图像

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

版本 1.0.0

文生图

POST
/v1/images/generations

使用 GPT Image 2 或 GPT Image 2.5 根据文本提示词生成图片。GPT Image 系列走 openai-images 协议，可用模型 ID 为 openai/gpt-image-2、openai/gpt-image-2.5-flare 和 openai/gpt-image-2.5-sunburst。GPT Image 2.5 额外支持 xhigh/max 质量档，以及 background、output_compression 等输出控制字段；同步接口会将这些字段原样透传到上游。

认证方式

BearerAuthBEARER

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

Bearer 格式：JWT

请求体

请求体属性

  • modelstring, 必填

    模型名称。GPT Image 2 使用 openai/gpt-image-2；GPT Image 2.5 使用 openai/gpt-image-2.5-flare 或 openai/gpt-image-2.5-sunburst。

  • promptstring, 必填

    图片生成提示词，必填，最长 32000 个字符，约相当于 5000～8000 个英文单词或 2 万个中文字符。

  • qualityenum

    输出质量。GPT Image 2 支持 low、medium、high、auto；GPT Image 2.5 额外支持 xhigh、max。默认 auto。同步接口不拦截质量枚举，会原样透传到 openai-images 渠道。

    default: auto

  • sizestring

    输出图像尺寸。默认 auto；常用值包括 1024x1024（方图）、1536x1024（横图）、1024x1536（竖图）、2048x2048（2K 方图）、2048x1152（2K 横图）、3840x2160（4K 横图）和 2160x3840（4K 竖图）。也支持自定义宽x高，要求宽高均为 16 的倍数、最大边不超过 3840、长短边之比不超过 3:1，且总像素数为 655360～8294400。

  • backgroundenum

    输出背景。可选 auto、transparent、opaque；不传则由上游处理。平台仅透传，不回填默认值。

  • output_formatenum

    输出图片格式。不传时由上游使用默认格式 png。

    default: png

  • output_compressioninteger

    输出压缩率，范围 0～100。仅当 output_format 为 jpeg 或 webp 时可用；默认的 png 不支持该字段。

    minimum: 0; maximum: 100

请求

POST/v1/images/generations
curl https://api.qnaigc.com/v1/images/generations \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "openai/gpt-image-2",
  "prompt": "可爱的少女，动漫",
  "quality": "high"
}'

响应

object
响应.

响应体属性

  • createdinteger, 必填

    Unix 时间戳（秒）

  • dataobject[], 必填
    • b64_jsonstring, 必填

      图片的 base64 数据（当前实现固定返回该字段）

  • backgroundstring

    可选，背景类型

  • output_formatenum

    可选，输出格式；当前实现默认会给 png

  • sizestring

    可选，图像尺寸

  • qualitystring

    可选，图像质量

  • usageobject

    本次图片请求的用量。模型可能按 Token、请求次数或图片张数计费，以模型广场实际展示的计费项为准；详见 Usage 字段与计费对账。

    additionalProperties: false

    • total_tokensinteger

      总 Token 数，通常等于 input_tokens 与 output_tokens 之和。

    • input_tokensinteger

      输入 Token 总量。

    • output_tokensinteger

      输出 Token 总量。

    • ti_quantityinteger

      文生图实际生成张数。

    • ii_quantityinteger

      单图生图实际生成张数。

    • mi2i_quantityinteger

      多图生图实际生成张数。

    • req_countinteger

      成功同步请求的计次，通常为 1；该字段不是生成图片张数。

    • input_tokens_detailsobject

      输入 Token 的分类明细，已包含在 input_tokens 中。

      additionalProperties: false

    • output_tokens_detailsobject

      输出 Token 的分类明细，已包含在 output_tokens 中。

      additionalProperties: false

响应

application/json
{
  "created": 42,
  "data": [
    {
      "b64_json": "string"
    }
  ],
  "background": "string",
  "output_format": "png",
  "size": "string",
  "quality": "string",
  "usage": {
    "total_tokens": 42,
    "input_tokens": 42,
    "output_tokens": 42,
    "ti_quantity": 42,
    "ii_quantity": 42,
    "mi2i_quantity": 42,
    "req_count": 42,
    "input_tokens_details": {
      "text_tokens": 42,
      "image_tokens": 42
    }
  }
}

图生图

POST
/v1/images/edits

使用 GPT Image 2 或 GPT Image 2.5 编辑图片。GPT Image 系列走 openai-images 协议，可用模型 ID 为 openai/gpt-image-2、openai/gpt-image-2.5-flare 和 openai/gpt-image-2.5-sunburst。GPT Image 2.5 额外支持 xhigh/max 质量档，以及 background、output_compression 等输出控制字段；同步接口会将这些字段原样透传到上游。

输入图片

  • image 可传单张图片，也可传图片数组；images 是兼容字段，支持同样的输入格式。
  • 每张图片可以是公网可访问的图片 URL、data:image/<格式>;base64,<数据> 形式的 base64 data URI，或纯 base64 字符串。
  • 数组元素可使用 OpenAI JSON 格式 {"image_url": "<图片 URL>"}，也兼容 {"url": "<图片 URL>"}。单次请求最多提供 16 张图片。
  • 使用 application/json 时，通过 URL 提供的单张图片大小上限为 40MB。
  • 支持的图片格式：png、jpeg、webp、gif。

输出尺寸

size 支持 auto 或 宽x高。常用尺寸包括 1024x1024、1536x1024、1024x1536、2048x2048、2048x1152、3840x2160、2160x3840。自定义尺寸需要同时满足：宽高均为 16 的倍数、最大边不超过 3840、长短边之比不超过 3:1、总像素数为 655,360～8,294,400。

认证方式

BearerAuthBEARER

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

Bearer 格式：JWT

请求体

请求体属性

  • modelstring, 必填

    模型名称。GPT Image 2 使用 openai/gpt-image-2；GPT Image 2.5 使用 openai/gpt-image-2.5-flare 或 openai/gpt-image-2.5-sunburst。

  • promptstring, 必填

    图片编辑提示词，必填，最长 32000 个字符。

  • imagestring[]

    输入图片，与 images 二选一且必须提供其中一个。可传单个字符串或图片数组；字符串支持公网 URL、base64 data URI 或纯 base64。数组最多 16 项，元素可使用 {image_url: string} 对象，也兼容 {url: string}。通过 URL 提供的单张图片大小上限为 40MB。

    • image_urlstring

      OpenAI JSON 格式的图片地址。支持公网 URL、base64 data URI 或纯 base64 字符串。

    • urlstring

      兼容字段。支持公网 URL、base64 data URI 或纯 base64 字符串。

    • anyOf[0]string
      可选。
    • anyOf[1]
      可选。
    • anyOf[2]
      可选。
  • imagesstring[]

    image 的兼容字段，与 image 二选一且必须提供其中一个。输入格式与 image 相同。

    • image_urlstring

      OpenAI JSON 格式的图片地址。支持公网 URL、base64 data URI 或纯 base64 字符串。

    • urlstring

      兼容字段。支持公网 URL、base64 data URI 或纯 base64 字符串。

    • anyOf[0]string
      可选。
    • anyOf[1]
      可选。
    • anyOf[2]
      可选。
  • maskstring

    可选遮罩图片。支持公网 URL、base64 data URI 或纯 base64；建议使用带透明通道且与输入图片尺寸一致的 PNG，透明区域表示需要编辑的部分。通过 URL 提供时大小上限为 40MB。

  • ninteger

    生成图片数量。必须为正整数；不传时由上游使用默认值 1。

    default: 1; minimum: 1

  • sizestring

    输出图像尺寸。支持 auto 或宽x高；常用值为 1024x1024、1536x1024、1024x1536、2048x2048、2048x1152、3840x2160、2160x3840。自定义尺寸要求宽高均为 16 的倍数、最大边不超过 3840、长短边之比不超过 3:1、总像素数为 655360～8294400。

    default: auto

  • qualityenum

    输出质量。GPT Image 2 支持 low、medium、high、auto；GPT Image 2.5 额外支持 xhigh、max。不传时由模型使用默认质量。同步接口不拦截质量枚举，会原样透传到 openai-images 渠道。

  • output_formatenum

    输出图片格式。不传时由上游使用默认格式 png。

    default: png

  • backgroundenum

    输出背景。可选 auto、transparent、opaque；不传则由上游处理。平台仅透传，不回填默认值。

  • output_compressioninteger

    输出压缩率，范围 0～100。仅当 output_format 为 jpeg 或 webp 时可用；默认的 png 不支持该字段。

    minimum: 0; maximum: 100

请求

POST/v1/images/edits
curl https://api.qnaigc.com/v1/images/edits \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "openai/gpt-image-2",
  "prompt": "图片中增加一个人",
  "image": [
    "https://aitoken-public.qnaigc.com/example/generate-video/running-man.jpg"
  ],
  "n": 1,
  "size": "1024x1024",
  "quality": "low",
  "output_format": "png"
}'

响应

object
响应.

响应体属性

  • createdinteger, 必填

    Unix 时间戳（秒）

  • dataobject[], 必填
    • b64_jsonstring, 必填

      图片的 base64 数据（当前实现固定返回该字段）

  • backgroundstring

    可选，背景类型

  • output_formatenum

    可选，输出格式；当前实现默认会给 png

  • sizestring

    可选，图像尺寸

  • qualitystring

    可选，图像质量

  • usageobject

    本次图片请求的用量。模型可能按 Token、请求次数或图片张数计费，以模型广场实际展示的计费项为准；详见 Usage 字段与计费对账。

    additionalProperties: false

    • total_tokensinteger

      总 Token 数，通常等于 input_tokens 与 output_tokens 之和。

    • input_tokensinteger

      输入 Token 总量。

    • output_tokensinteger

      输出 Token 总量。

    • ti_quantityinteger

      文生图实际生成张数。

    • ii_quantityinteger

      单图生图实际生成张数。

    • mi2i_quantityinteger

      多图生图实际生成张数。

    • req_countinteger

      成功同步请求的计次，通常为 1；该字段不是生成图片张数。

    • input_tokens_detailsobject

      输入 Token 的分类明细，已包含在 input_tokens 中。

      additionalProperties: false

    • output_tokens_detailsobject

      输出 Token 的分类明细，已包含在 output_tokens 中。

      additionalProperties: false

响应

application/json
{
  "created": 42,
  "data": [
    {
      "b64_json": "string"
    }
  ],
  "background": "string",
  "output_format": "png",
  "size": "string",
  "quality": "string",
  "usage": {
    "total_tokens": 42,
    "input_tokens": 42,
    "output_tokens": 42,
    "ti_quantity": 42,
    "ii_quantity": 42,
    "mi2i_quantity": 42,
    "req_count": 42,
    "input_tokens_details": {
      "text_tokens": 42,
      "image_tokens": 42
    }
  }
}

创建图像生成任务

POST
/queue/fal-ai/kling-image/o1

创建可灵 OmniImage 图像生成任务。支持文本提示词、参考图片的多模态输入方式。任务为异步执行，创建成功后返回任务 ID，需通过查询接口获取生成结果。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

  • promptstring, 必填

    文本提示词，使用 <<<image_1>>> 引用参考图，最大 2500 字符

  • image_urlsstring<uri>[]

    参考图 URL 列表，在 prompt 中用 <<<image_1>>> 引用（1-indexed），最多 10 张

  • resolutionenum

    分辨率：1K 或 2K，默认 1K（兼容小写 1k/2k）

  • num_imagesinteger

    生成数量 1-9，默认 1

    minimum: 1; maximum: 9

  • aspect_ratioenum

    纵横比，默认 auto

请求

POST/queue/fal-ai/kling-image/o1
curl 'https://api.qnaigc.com/queue/fal-ai/kling-image/o1?fal_webhook={fal_webhook}' \
  --request POST \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "一只可爱的橘猫在阳光下打盹",
  "num_images": 2,
  "resolution": "2K",
  "aspect_ratio": "16:9"
}'

响应

object

服务器内部错误

响应体属性

  • statusstring, 必填
    必填。
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。

响应

application/json
{
  "status": "IN_QUEUE",
  "request_id": "qimage-root-1770199726278452760",
  "response_url": "https://api.qnaigc.com/queue/fal-ai/kling-image/requests/qimage-root-1770199726278452760",
  "status_url": "https://api.qnaigc.com/queue/fal-ai/kling-image/requests/qimage-root-1770199726278452760/status",
  "cancel_url": ""
}

创建 O3 文生图任务

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

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

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    推荐的 HTTPS 回调地址，需公网可访问。

请求体

请求体属性

  • promptstring, 必填

    文生图提示词，去除首尾空白后不能为空。

  • resolutionenum

    输出分辨率，兼容小写。

    default: 1K

  • result_typeenum

    文生图仅支持 single，生成独立图片；组图请使用图生图接口。

    default: single

  • num_imagesinteger

    独立图片数量，仅 single 模式使用，默认 1。

    default: 1; minimum: 1; maximum: 9

  • callback_urlstring<uri>

    可选回调地址；推荐 Query 参数 fal_webhook。

  • aspect_ratioenum

    输出画幅比例，默认 16:9。

    default: 16: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, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "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

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    推荐的 HTTPS 回调地址，需公网可访问。

请求体

请求体属性

  • promptstring, 必填

    提示词，去除首尾空白后不能为空；按 @Image1、@Image2 引用参考图。

  • resolutionenum

    输出分辨率，兼容小写。

    default: 1K

  • result_typeenum

    single 为独立图片，series 为组图。

    default: single

  • 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

  • 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, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "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

路径参数

  • 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, 必填
  • 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[], 必填
    • usageobject

      异步生图任务的 Token 用量。仅在任务成功完成且存在用量记录时返回；历史任务可能不含此字段。明细字段已包含在对应的输入或输出总量中，详见 Usage 字段与计费对账。

响应

application/json
{
  "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

路径参数

  • 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

      图片高度（可选）

响应

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

提交文生图任务

POST
/queue/openai/gpt-image-2

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

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

  • promptstring, 必填

    图片生成提示词，必填，最长 32000 个字符。

  • image_sizeenum | object

    图像尺寸。支持预设名（实际尺寸见下方）、auto 或 {width,height} 对象。

    default: landscape_4_3

    • oneOf[0]enum

      图像尺寸预设名；各枚举值对应的实际请求尺寸见下方说明。

    • oneOf[1]object

      显式指定宽高的图像尺寸（对齐 fal ImageSize 对象）。宽高需为正整数；fal 约束：建议为 16 的倍数、最大边 3840、长宽比 ≤ 3:1、总像素 655360~8294400。

  • qualityenum

    输出质量。默认 high；auto 表示由模型根据提示词自动选择。gpt-image-2 不支持 xhigh、max，这两档仅 GPT Image 2.5 可用。

    default: high

  • num_imagesinteger

    生成图片数量。默认 1，范围 1～4。

    default: 1; minimum: 1; maximum: 4

  • output_formatenum

    输出图片格式。默认 png。

    default: png

  • backgroundenum

    输出背景。可选 auto、transparent、opaque；不传则由上游处理。平台仅透传，不回填默认值。

  • output_compressioninteger

    输出压缩率，范围 0～100。仅当 output_format 为 jpeg 或 webp 时可用；默认的 png 不支持该字段。

    minimum: 0; maximum: 100

请求

POST/queue/openai/gpt-image-2
curl 'https://api.qnaigc.com/queue/openai/gpt-image-2?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 coding on a laptop, studio lighting",
  "image_size": "landscape_4_3",
  "quality": "high",
  "num_images": 1,
  "output_format": "png"
}'

响应

object

任务已入队

响应体属性

  • statusenum, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "status": "IN_QUEUE",
  "request_id": "qimage-root-1782369141807001000",
  "response_url": "https://api.qnaigc.com/queue/openai/gpt-image-2/requests/qimage-root-1782369141807001000",
  "status_url": "https://api.qnaigc.com/queue/openai/gpt-image-2/requests/qimage-root-1782369141807001000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null
}

提交图片编辑任务

POST
/queue/openai/gpt-image-2/edit

提交 gpt-image-2 图片编辑异步任务。需提供参考图 image_urls（必填），可选 mask_url 指定编辑区域。返回的状态/结果查询 URL 走 base 路径 openai/gpt-image-2/requests/{request_id}（不带 /edit）。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

  • promptstring, 必填

    图片编辑提示词，必填，最长 32000 个字符。

  • image_urlsstring[], 必填

    编辑所使用的参考图片 URL 列表，必填。平台当前最多接受 10 张。

  • mask_urlstring<uri>

    可选的遮罩图片 URL，用于指示需要编辑的区域。

  • image_sizeenum | object

    输出图像尺寸。默认 auto，由模型根据输入图片和提示词选择；也可传预设名（实际尺寸见下方）或 {width,height} 对象。

    default: auto

    • oneOf[0]enum

      图像尺寸预设名；各枚举值对应的实际请求尺寸见下方说明。

    • oneOf[1]object

      显式指定宽高的图像尺寸（对齐 fal ImageSize 对象）。宽高需为正整数；fal 约束：建议为 16 的倍数、最大边 3840、长宽比 ≤ 3:1、总像素 655360~8294400。

  • qualityenum

    输出质量。默认 high；auto 表示由模型根据提示词自动选择。gpt-image-2 不支持 xhigh、max，这两档仅 GPT Image 2.5 可用。

    default: high

  • num_imagesinteger

    生成图片数量。默认 1，范围 1～4。

    default: 1; minimum: 1; maximum: 4

  • output_formatenum

    输出图片格式。默认 png。

    default: png

  • backgroundenum

    输出背景。可选 auto、transparent、opaque；不传则由上游处理。平台仅透传，不回填默认值。

  • output_compressioninteger

    输出压缩率，范围 0～100。仅当 output_format 为 jpeg 或 webp 时可用；默认的 png 不支持该字段。

    minimum: 0; maximum: 100

请求

POST/queue/openai/gpt-image-2/edit
curl 'https://api.qnaigc.com/queue/openai/gpt-image-2/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": "add a wizard hat on the red panda",
  "image_urls": [
    "https://example.com/input.png"
  ],
  "image_size": "auto",
  "quality": "high",
  "num_images": 1,
  "output_format": "png"
}'

响应

object

任务已入队

响应体属性

  • statusenum, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "status": "IN_QUEUE",
  "request_id": "qimage-root-1782369141807001000",
  "response_url": "https://api.qnaigc.com/queue/openai/gpt-image-2/requests/qimage-root-1782369141807001000",
  "status_url": "https://api.qnaigc.com/queue/openai/gpt-image-2/requests/qimage-root-1782369141807001000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null
}

查询任务状态

GET
/queue/openai/gpt-image-2/requests/{request_id}/status

查询文生图/编辑任务的状态（共用此端点，request_id 全局唯一）。进行中返回 HTTP 202；完成或失败返回 HTTP 200。失败任务仍返回 status: COMPLETED，具体错误通过 detail 提供。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

路径参数

  • Name
    request_id
    Type
    string, 必填
    Description

    任务 ID（提交接口返回的 request_id，格式 qimage-{uid}-{timestamp}）

请求体

暂无请求体

请求

GET/queue/openai/gpt-image-2/requests/{request_id}/status
curl https://api.qnaigc.com/queue/openai/gpt-image-2/requests/{request_id}/status \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json'

响应

object

任务已完成或失败。失败任务的 status 仍为 COMPLETED，错误详情位于 detail。

响应体属性

  • statusenum, 必填
  • 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[], 必填
    • usageobject

      异步生图任务的 Token 用量。仅在任务成功完成且存在用量记录时返回；历史任务可能不含此字段。明细字段已包含在对应的输入或输出总量中，详见 Usage 字段与计费对账。

响应

application/json
{
  "status": "COMPLETED",
  "request_id": "qimage-root-1782369141807001000",
  "response_url": "https://api.qnaigc.com/queue/openai/gpt-image-2/requests/qimage-root-1782369141807001000",
  "status_url": "https://api.qnaigc.com/queue/openai/gpt-image-2/requests/qimage-root-1782369141807001000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null,
  "metrics": {
    "inference_time": 38
  },
  "result": {
    "images": [
      {
        "url": "https://aitoken-image.qnaigc.com/gpt-image/root/qimage-root-1782369141807001000/0.png?e=1780000000&token=example",
        "content_type": "image/png"
      }
    ],
    "usage": {
      "total_tokens": 4356,
      "input_tokens": 2,
      "output_tokens": 4354,
      "input_tokens_details": {
        "text_tokens": 2,
        "image_tokens": 0
      },
      "output_tokens_details": {
        "image_tokens": 4354,
        "text_tokens": 0
      }
    }
  }
}

获取任务结果

GET
/queue/openai/gpt-image-2/requests/{request_id}

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

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

路径参数

  • Name
    request_id
    Type
    string, 必填
    Description

    任务 ID

请求体

暂无请求体

请求

GET/queue/openai/gpt-image-2/requests/{request_id}
curl https://api.qnaigc.com/queue/openai/gpt-image-2/requests/{request_id} \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json'

响应

object

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

响应体属性

  • detailobject, 必填
    • locstring[], 必填

      错误位置。

    • msgstring, 必填

      人类可读的错误描述。

    • typestring, 必填

      机器可读的错误分类标识符。

    • urlstring, 必填

      错误类型文档链接。

    • ctx

      附加结构化上下文（可选）。

    • input

      导致错误的输入（可选）。

响应

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

提交文生图任务

POST
/queue/openai/gpt-image-2.5/flare/text-to-image

提交 GPT Image 2.5 Flare 文生图异步任务。市场模型 ID 为 openai/gpt-image-2.5-flare。文生图必须 POST 到带 /text-to-image 的完整路径，不要按 gpt-image-2 那样 POST 到不带该后缀的路径。鉴权通过后创建任务并立即返回 IN_QUEUE 状态与 request_id。所有 GPT Image 2.5 变体和任务类型统一通过 /queue/openai/gpt-image-2.5/requests/{request_id}/status 查询状态，通过 /queue/openai/gpt-image-2.5/requests/{request_id} 获取结果。可通过 query 参数 fal_webhook 配置回调。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

  • promptstring, 必填

    图片生成提示词，必填，最长 32000 个字符。

  • image_sizeenum | object

    图像尺寸。支持预设名（实际尺寸见下方）、auto 或 {width,height} 对象。

    default: landscape_4_3

    • oneOf[0]enum

      图像尺寸预设名；各枚举值对应的实际请求尺寸见下方说明。

    • oneOf[1]object

      显式指定宽高的图像尺寸（对齐 fal ImageSize 对象）。宽高需为正整数；fal 约束：建议为 16 的倍数、最大边 3840、长宽比 ≤ 3:1、总像素 655360~8294400。

  • qualityenum

    输出质量。默认 high；auto 表示由模型根据提示词自动选择。GPT Image 2.5 额外支持 xhigh、max，更高档会增加细节、耗时和 Token 用量。

    default: high

  • num_imagesinteger

    生成图片数量。默认 1，范围 1～4。

    default: 1; minimum: 1; maximum: 4

  • output_formatenum

    输出图片格式。默认 png。

    default: png

  • backgroundenum

    输出背景。可选 auto、transparent、opaque；不传则由上游处理。平台仅透传，不回填默认值。

  • output_compressioninteger

    输出压缩率，范围 0～100。仅当 output_format 为 jpeg 或 webp 时可用；默认的 png 不支持该字段。

    minimum: 0; maximum: 100

请求

POST/queue/openai/gpt-image-2.5/flare/text-to-image
curl 'https://api.qnaigc.com/queue/openai/gpt-image-2.5/flare/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": "a cute red panda coding on a laptop, studio lighting",
  "image_size": "landscape_4_3",
  "quality": "xhigh",
  "background": "transparent",
  "num_images": 1,
  "output_format": "webp",
  "output_compression": 80
}'

响应

object

任务已入队

响应体属性

  • statusenum, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "status": "IN_QUEUE",
  "request_id": "qimage-root-1782369141807001000",
  "response_url": "https://api.qnaigc.com/queue/openai/gpt-image-2.5/requests/qimage-root-1782369141807001000",
  "status_url": "https://api.qnaigc.com/queue/openai/gpt-image-2.5/requests/qimage-root-1782369141807001000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null
}

提交图片编辑任务

POST
/queue/openai/gpt-image-2.5/flare/edit

提交 GPT Image 2.5 Flare 图片编辑异步任务。需提供参考图 image_urls（必填，最多 16 张），可选 mask_url 指定编辑区域。所有 GPT Image 2.5 变体和任务类型统一通过 /queue/openai/gpt-image-2.5/requests/{request_id}/status 查询状态，通过 /queue/openai/gpt-image-2.5/requests/{request_id} 获取结果。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

  • promptstring, 必填

    图片编辑提示词，必填，最长 32000 个字符。

  • image_urlsstring[], 必填

    编辑所使用的参考图片 URL 列表，必填。GPT Image 2.5 最多接受 16 张。

  • mask_urlstring<uri>

    可选的遮罩图片 URL，用于指示需要编辑的区域。

  • image_sizeenum | object

    输出图像尺寸。默认 auto，由模型根据输入图片和提示词选择；也可传预设名（实际尺寸见下方）或 {width,height} 对象。

    default: auto

    • oneOf[0]enum

      图像尺寸预设名；各枚举值对应的实际请求尺寸见下方说明。

    • oneOf[1]object

      显式指定宽高的图像尺寸（对齐 fal ImageSize 对象）。宽高需为正整数；fal 约束：建议为 16 的倍数、最大边 3840、长宽比 ≤ 3:1、总像素 655360~8294400。

  • qualityenum

    输出质量。默认 high；auto 表示由模型根据提示词自动选择。GPT Image 2.5 额外支持 xhigh、max，更高档会增加细节、耗时和 Token 用量。

    default: high

  • num_imagesinteger

    生成图片数量。默认 1，范围 1～4。

    default: 1; minimum: 1; maximum: 4

  • output_formatenum

    输出图片格式。默认 png。

    default: png

  • backgroundenum

    输出背景。可选 auto、transparent、opaque；不传则由上游处理。平台仅透传，不回填默认值。

  • output_compressioninteger

    输出压缩率，范围 0～100。仅当 output_format 为 jpeg 或 webp 时可用；默认的 png 不支持该字段。

    minimum: 0; maximum: 100

请求

POST/queue/openai/gpt-image-2.5/flare/edit
curl 'https://api.qnaigc.com/queue/openai/gpt-image-2.5/flare/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": "add a wizard hat on the red panda",
  "image_urls": [
    "https://example.com/input.png"
  ],
  "image_size": "auto",
  "quality": "max",
  "background": "opaque",
  "num_images": 1,
  "output_format": "png"
}'

响应

object

任务已入队

响应体属性

  • statusenum, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "status": "IN_QUEUE",
  "request_id": "qimage-root-1782369141807001000",
  "response_url": "https://api.qnaigc.com/queue/openai/gpt-image-2.5/requests/qimage-root-1782369141807001000",
  "status_url": "https://api.qnaigc.com/queue/openai/gpt-image-2.5/requests/qimage-root-1782369141807001000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null
}

提交文生图任务

POST
/queue/openai/gpt-image-2.5/sunburst/text-to-image

提交 GPT Image 2.5 Sunburst 文生图异步任务。市场模型 ID 为 openai/gpt-image-2.5-sunburst。文生图必须 POST 到带 /text-to-image 的完整路径，不要按 gpt-image-2 那样 POST 到不带该后缀的路径。鉴权通过后创建任务并立即返回 IN_QUEUE 状态与 request_id。所有 GPT Image 2.5 变体和任务类型统一通过 /queue/openai/gpt-image-2.5/requests/{request_id}/status 查询状态，通过 /queue/openai/gpt-image-2.5/requests/{request_id} 获取结果。可通过 query 参数 fal_webhook 配置回调。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

  • promptstring, 必填

    图片生成提示词，必填，最长 32000 个字符。

  • image_sizeenum | object

    图像尺寸。支持预设名（实际尺寸见下方）、auto 或 {width,height} 对象。

    default: landscape_4_3

    • oneOf[0]enum

      图像尺寸预设名；各枚举值对应的实际请求尺寸见下方说明。

    • oneOf[1]object

      显式指定宽高的图像尺寸（对齐 fal ImageSize 对象）。宽高需为正整数；fal 约束：建议为 16 的倍数、最大边 3840、长宽比 ≤ 3:1、总像素 655360~8294400。

  • qualityenum

    输出质量。默认 high；auto 表示由模型根据提示词自动选择。GPT Image 2.5 额外支持 xhigh、max，更高档会增加细节、耗时和 Token 用量。

    default: high

  • num_imagesinteger

    生成图片数量。默认 1，范围 1～4。

    default: 1; minimum: 1; maximum: 4

  • output_formatenum

    输出图片格式。默认 png。

    default: png

  • backgroundenum

    输出背景。可选 auto、transparent、opaque；不传则由上游处理。平台仅透传，不回填默认值。

  • output_compressioninteger

    输出压缩率，范围 0～100。仅当 output_format 为 jpeg 或 webp 时可用；默认的 png 不支持该字段。

    minimum: 0; maximum: 100

请求

POST/queue/openai/gpt-image-2.5/sunburst/text-to-image
curl 'https://api.qnaigc.com/queue/openai/gpt-image-2.5/sunburst/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": "a cute red panda coding on a laptop, studio lighting",
  "image_size": "landscape_4_3",
  "quality": "max",
  "background": "transparent",
  "num_images": 1,
  "output_format": "webp",
  "output_compression": 80
}'

响应

object

任务已入队

响应体属性

  • statusenum, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "status": "IN_QUEUE",
  "request_id": "qimage-root-1782369141807001000",
  "response_url": "https://api.qnaigc.com/queue/openai/gpt-image-2.5/requests/qimage-root-1782369141807001000",
  "status_url": "https://api.qnaigc.com/queue/openai/gpt-image-2.5/requests/qimage-root-1782369141807001000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null
}

提交图片编辑任务

POST
/queue/openai/gpt-image-2.5/sunburst/edit

提交 GPT Image 2.5 Sunburst 图片编辑异步任务。需提供参考图 image_urls（必填，最多 16 张），可选 mask_url 指定编辑区域。所有 GPT Image 2.5 变体和任务类型统一通过 /queue/openai/gpt-image-2.5/requests/{request_id}/status 查询状态，通过 /queue/openai/gpt-image-2.5/requests/{request_id} 获取结果。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

  • promptstring, 必填

    图片编辑提示词，必填，最长 32000 个字符。

  • image_urlsstring[], 必填

    编辑所使用的参考图片 URL 列表，必填。GPT Image 2.5 最多接受 16 张。

  • mask_urlstring<uri>

    可选的遮罩图片 URL，用于指示需要编辑的区域。

  • image_sizeenum | object

    输出图像尺寸。默认 auto，由模型根据输入图片和提示词选择；也可传预设名（实际尺寸见下方）或 {width,height} 对象。

    default: auto

    • oneOf[0]enum

      图像尺寸预设名；各枚举值对应的实际请求尺寸见下方说明。

    • oneOf[1]object

      显式指定宽高的图像尺寸（对齐 fal ImageSize 对象）。宽高需为正整数；fal 约束：建议为 16 的倍数、最大边 3840、长宽比 ≤ 3:1、总像素 655360~8294400。

  • qualityenum

    输出质量。默认 high；auto 表示由模型根据提示词自动选择。GPT Image 2.5 额外支持 xhigh、max，更高档会增加细节、耗时和 Token 用量。

    default: high

  • num_imagesinteger

    生成图片数量。默认 1，范围 1～4。

    default: 1; minimum: 1; maximum: 4

  • output_formatenum

    输出图片格式。默认 png。

    default: png

  • backgroundenum

    输出背景。可选 auto、transparent、opaque；不传则由上游处理。平台仅透传，不回填默认值。

  • output_compressioninteger

    输出压缩率，范围 0～100。仅当 output_format 为 jpeg 或 webp 时可用；默认的 png 不支持该字段。

    minimum: 0; maximum: 100

请求

POST/queue/openai/gpt-image-2.5/sunburst/edit
curl 'https://api.qnaigc.com/queue/openai/gpt-image-2.5/sunburst/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": "add a wizard hat on the red panda",
  "image_urls": [
    "https://example.com/input.png"
  ],
  "image_size": "auto",
  "quality": "xhigh",
  "background": "opaque",
  "num_images": 1,
  "output_format": "png"
}'

响应

object

任务已入队

响应体属性

  • statusenum, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "status": "IN_QUEUE",
  "request_id": "qimage-root-1782369141807001000",
  "response_url": "https://api.qnaigc.com/queue/openai/gpt-image-2.5/requests/qimage-root-1782369141807001000",
  "status_url": "https://api.qnaigc.com/queue/openai/gpt-image-2.5/requests/qimage-root-1782369141807001000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null
}

提交文生图任务

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

查询参数

  • 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

  • num_imagesinteger

    生成图片数量，默认为 1。

    default: 1; minimum: 1; maximum: 1

  • output_formatenum

    输出图片格式，默认 png

    default: png

  • thinking_levelenum

    模型思考强度。可选 minimal 或 high，省略则不启用思考。

  • safety_toleranceenum

    内容审核宽松度，1 最严格，6 最宽松，默认 4。

    default: 4

  • 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, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "status": "IN_QUEUE",
  "request_id": "qimage-root-1782369141807001000",
  "response_url": "https://api.qnaigc.com/queue/google/nano-banana-2-lite/requests/qimage-root-1782369141807001000",
  "status_url": "https://api.qnaigc.com/queue/google/nano-banana-2-lite/requests/qimage-root-1782369141807001000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null
}

查询任务状态

GET
/queue/openai/gpt-image-2.5/requests/{request_id}/status

查询 GPT Image 2.5 Flare 或 Sunburst 的文生图、图片编辑任务状态。所有变体和任务类型共用此查询接口。进行中返回 HTTP 202；完成或失败返回 HTTP 200。失败任务仍返回 status: COMPLETED，具体错误通过 detail 提供。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

路径参数

  • Name
    request_id
    Type
    string, 必填
    Description

    任务 ID（提交接口返回的 request_id，格式 qimage-{uid}-{timestamp}）

请求体

暂无请求体

请求

GET/queue/openai/gpt-image-2.5/requests/{request_id}/status
curl https://api.qnaigc.com/queue/openai/gpt-image-2.5/requests/{request_id}/status \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json'

响应

object

任务已完成或失败。失败任务的 status 仍为 COMPLETED，错误详情位于 detail。

响应体属性

  • statusenum, 必填
  • 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[], 必填
    • usageobject

      异步生图任务的 Token 用量。仅在任务成功完成且存在用量记录时返回；历史任务可能不含此字段。明细字段已包含在对应的输入或输出总量中，详见 Usage 字段与计费对账。

响应

application/json
{
  "status": "COMPLETED",
  "request_id": "qimage-root-1782369141807001000",
  "response_url": "https://api.qnaigc.com/queue/openai/gpt-image-2.5/requests/qimage-root-1782369141807001000",
  "status_url": "https://api.qnaigc.com/queue/openai/gpt-image-2.5/requests/qimage-root-1782369141807001000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null,
  "metrics": {
    "inference_time": 38
  },
  "result": {
    "images": [
      {
        "url": "https://aitoken-image.qnaigc.com/gpt-image/root/qimage-root-1782369141807001000/0.png?e=1780000000&token=example",
        "content_type": "image/png"
      }
    ],
    "usage": {
      "total_tokens": 4356,
      "input_tokens": 2,
      "output_tokens": 4354,
      "input_tokens_details": {
        "text_tokens": 2,
        "image_tokens": 0
      },
      "output_tokens_details": {
        "image_tokens": 4354,
        "text_tokens": 0
      }
    }
  }
}

获取任务结果

GET
/queue/openai/gpt-image-2.5/requests/{request_id}

获取 GPT Image 2.5 Flare 或 Sunburst 的文生图、图片编辑任务结果。所有变体和任务类型共用此查询接口。任务进行中返回 HTTP 400；任务失败返回对应错误码和 Fal 错误详情；任务成功返回图片结果。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

路径参数

  • Name
    request_id
    Type
    string, 必填
    Description

    任务 ID

请求体

暂无请求体

请求

GET/queue/openai/gpt-image-2.5/requests/{request_id}
curl https://api.qnaigc.com/queue/openai/gpt-image-2.5/requests/{request_id} \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json'

响应

object

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

响应体属性

  • detailobject, 必填
    • locstring[], 必填

      错误位置。

    • msgstring, 必填

      人类可读的错误描述。

    • typestring, 必填

      机器可读的错误分类标识符。

    • urlstring, 必填

      错误类型文档链接。

    • ctx

      附加结构化上下文（可选）。

    • input

      导致错误的输入（可选）。

响应

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

提交图片编辑任务

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

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

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • 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

  • num_imagesinteger

    生成图片数量，默认为 1。

    default: 1; minimum: 1; maximum: 1

  • output_formatenum

    输出图片格式，默认 png

    default: png

  • image_urlsstring<uri>[], 必填

    参考图 URL 列表（必填）。用于图生图或图片编辑。

  • thinking_levelenum

    模型思考强度。可选 minimal 或 high，省略则不启用思考。

  • safety_toleranceenum

    内容审核宽松度，1 最严格，6 最宽松，默认 4。

    default: 4

  • 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, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "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"
    }
  ]
}

查询任务状态

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

路径参数

  • 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, 必填
  • 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[], 必填
    • usageobject

      异步生图任务的 Token 用量。仅在任务成功完成且存在用量记录时返回；历史任务可能不含此字段。明细字段已包含在对应的输入或输出总量中，详见 Usage 字段与计费对账。

响应

application/json
{
  "status": "COMPLETED",
  "request_id": "qimage-root-1782369141807001000",
  "response_url": "https://api.qnaigc.com/queue/google/nano-banana-2-lite/requests/qimage-root-1782369141807001000",
  "status_url": "https://api.qnaigc.com/queue/google/nano-banana-2-lite/requests/qimage-root-1782369141807001000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null,
  "metrics": {
    "inference_time": 38
  },
  "result": {
    "images": [
      {
        "url": "https://aitoken-image.qnaigc.com/gemini-image/root/qimage-root-1782369141807001000/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
      }
    }
  }
}

获取任务结果

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

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

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

路径参数

  • 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

      导致错误的输入（可选）。

响应

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

提交文生图任务

POST
/queue/fal-ai/gemini-3-pro-image-preview

提交 gemini-3.0-pro-image-preview 文生图异步任务，立即返回 IN_QUEUE、request_id 与查询 URL。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

  • promptstring, 必填

    文本提示词，最大长度 50000。

  • aspect_ratioenum

    画面纵横比；auto 表示由模型决定。

    default: 1:1

  • resolutionenum

    输出分辨率；4K 通常按 2 倍费率计费。

    default: 1K

  • output_formatenum

    输出图片格式。

    default: png

  • safety_toleranceenum

    内容审核宽松度，1 最严格，6 最宽松。

  • system_promptstring

    引导模型风格的系统提示词。

请求

POST/queue/fal-ai/gemini-3-pro-image-preview
curl 'https://api.qnaigc.com/queue/fal-ai/gemini-3-pro-image-preview?fal_webhook={fal_webhook}' \
  --request POST \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "make a photo of the man driving the car down the california coastline",
  "aspect_ratio": "16:9",
  "resolution": "2K",
  "output_format": "png"
}'

响应

object

任务已入队

响应体属性

  • statusenum, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "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"
    }
  ]
}

提交图片编辑任务

POST
/queue/fal-ai/gemini-3-pro-image-preview/edit

提交 gemini-3.0-pro-image-preview 图片编辑异步任务。image_urls 必填，文生图与编辑任务共用状态和结果查询路径。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

  • promptstring, 必填

    编辑提示词，最大长度 50000。

  • image_urlsstring<uri>[], 必填

    参考图 URL 列表，不支持 mask。

  • aspect_ratioenum

    画面纵横比。

    default: auto

  • resolutionenum

    输出分辨率。

    default: 1K

  • output_formatenum

    输出图片格式。

    default: png

  • safety_toleranceenum

    内容审核宽松度，1 最严格，6 最宽松。

  • system_promptstring

    引导模型风格的系统提示词。

请求

POST/queue/fal-ai/gemini-3-pro-image-preview/edit
curl 'https://api.qnaigc.com/queue/fal-ai/gemini-3-pro-image-preview/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": "make a photo of the man driving the car down the california coastline",
  "image_urls": [
    "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input.png"
  ],
  "resolution": "2K"
}'

响应

object

任务已入队

响应体属性

  • statusenum, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "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"
    }
  ]
}

查询任务状态

GET
/queue/fal-ai/gemini-3-pro-image-preview/requests/{request_id}/status

查询文生图或图片编辑任务状态。进行中返回 HTTP 202 和 IN_QUEUE 或 IN_PROGRESS；完成或失败返回 HTTP 200 和 COMPLETED，失败详情通过 detail 提供。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

路径参数

  • Name
    request_id
    Type
    string, 必填
    Description

    提交任务时返回的 request_id。

请求体

暂无请求体

请求

GET/queue/fal-ai/gemini-3-pro-image-preview/requests/{request_id}/status
curl https://api.qnaigc.com/queue/fal-ai/gemini-3-pro-image-preview/requests/{request_id}/status \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json'

响应

object

任务已完成或失败

响应体属性

  • statusenum, 必填
  • 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[], 必填
    • usageobject

      异步生图任务的 Token 用量。仅在任务成功完成且存在用量记录时返回；历史任务可能不含此字段。明细字段已包含在对应的输入或输出总量中，详见 Usage 字段与计费对账。

响应

application/json
{
  "status": "COMPLETED",
  "request_id": "qimage-root-1782369141807001000",
  "response_url": "https://api.qnaigc.com/queue/fal-ai/gemini-3-pro-image-preview/requests/qimage-root-1782369141807001000",
  "status_url": "https://api.qnaigc.com/queue/fal-ai/gemini-3-pro-image-preview/requests/qimage-root-1782369141807001000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null,
  "metrics": {
    "inference_time": 38
  },
  "result": {
    "images": [
      {
        "url": "https://aitoken-image.qnaigc.com/gemini-image/root/qimage-root-1782369141807001000/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
      }
    }
  }
}

获取任务结果

GET
/queue/fal-ai/gemini-3-pro-image-preview/requests/{request_id}

获取文生图或图片编辑任务结果。任务进行中返回 HTTP 400 状态响应；参数错误返回 Fal 错误响应；任务失败返回对应错误码和 Fal 错误详情；成功返回 Fal 格式图片列表。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

路径参数

  • Name
    request_id
    Type
    string, 必填
    Description

    提交任务时返回的 request_id。

请求体

暂无请求体

请求

GET/queue/fal-ai/gemini-3-pro-image-preview/requests/{request_id}
curl https://api.qnaigc.com/queue/fal-ai/gemini-3-pro-image-preview/requests/{request_id} \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json'

响应

object

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

响应体属性

  • detailobject, 必填
    • locstring[], 必填

      错误位置。

    • msgstring, 必填

      人类可读的错误描述。

    • typestring, 必填

      机器可读的错误分类标识符。

    • urlstring, 必填

      错误类型文档链接。

    • ctx

      附加结构化上下文（可选）。

    • input

      导致错误的输入（可选）。

响应

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

提交文生图任务

POST
/queue/fal-ai/gemini-3.1-flash-image-preview

提交 gemini-3.1-flash-image-preview 文生图异步任务。支持 0.5K 分辨率、极端画幅比例和 thinking_level。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

  • promptstring, 必填

    文本提示词，最大长度 50000。

  • aspect_ratioenum

    画面纵横比，支持 4:1、1:4、8:1 和 1:8 等极端比例。

    default: auto

  • resolutionenum

    输出分辨率。

    default: 1K

  • output_formatenum

    输出图片格式。

    default: png

  • thinking_levelenum

    模型思考强度。

  • safety_toleranceenum

    内容审核宽松度，1 最严格，6 最宽松。

  • system_promptstring

    引导模型风格的系统提示词。

请求

POST/queue/fal-ai/gemini-3.1-flash-image-preview
curl 'https://api.qnaigc.com/queue/fal-ai/gemini-3.1-flash-image-preview?fal_webhook={fal_webhook}' \
  --request POST \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "make a photo of the man driving the car down the california coastline",
  "aspect_ratio": "auto",
  "resolution": "1K",
  "thinking_level": "minimal"
}'

响应

object

任务已入队

响应体属性

  • statusenum, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "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"
    }
  ]
}

提交图片编辑任务

POST
/queue/fal-ai/gemini-3.1-flash-image-preview/edit

提交 gemini-3.1-flash-image-preview 图片编辑异步任务。image_urls 为参考图片 URL 列表，不支持 mask。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

查询参数

  • Name
    fal_webhook
    Type
    string<uri>
    Description

    可选。任务状态变化时接收 FAL 格式回调的 HTTPS 地址。详见 FAL 格式 Webhook。

请求体

请求体属性

  • promptstring, 必填

    编辑提示词，最大长度 50000。

  • image_urlsstring<uri>[], 必填

    参考图 URL 列表，不支持 mask。

  • aspect_ratioenum

    画面纵横比，支持 4:1、1:4、8:1 和 1:8 等极端比例。

    default: auto

  • resolutionenum

    输出分辨率。

    default: 1K

  • output_formatenum

    输出图片格式。

    default: png

  • thinking_levelenum

    模型思考强度。

  • safety_toleranceenum

    内容审核宽松度，1 最严格，6 最宽松。

  • system_promptstring

    引导模型风格的系统提示词。

请求

POST/queue/fal-ai/gemini-3.1-flash-image-preview/edit
curl 'https://api.qnaigc.com/queue/fal-ai/gemini-3.1-flash-image-preview/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 this image to red",
  "image_urls": [
    "https://storage.googleapis.com/falserverless/example_inputs/nano-banana-edit-input.png"
  ],
  "thinking_level": "minimal"
}'

响应

object

任务已入队

响应体属性

  • statusenum, 必填
  • request_idstring, 必填
    必填。
  • response_urlstring, 必填
    必填。
  • status_urlstring, 必填
    必填。
  • cancel_urlstring, 必填
    必填。
  • queue_positioninteger, 必填
    必填。
  • logsobject[], 必填
    • messagestring
      可选。
    • levelstring
      可选。
    • sourcestring
      可选。
    • timestampstring
      可选。

响应

application/json
{
  "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"
    }
  ]
}

查询任务状态

GET
/queue/fal-ai/gemini-3.1-flash-image-preview/requests/{request_id}/status

查询文生图或图片编辑任务状态。进行中返回 HTTP 202 和 IN_QUEUE 或 IN_PROGRESS；完成或失败返回 HTTP 200 和 COMPLETED，失败详情通过 detail 提供。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

路径参数

  • Name
    request_id
    Type
    string, 必填
    Description

    提交任务时返回的 request_id。

请求体

暂无请求体

请求

GET/queue/fal-ai/gemini-3.1-flash-image-preview/requests/{request_id}/status
curl https://api.qnaigc.com/queue/fal-ai/gemini-3.1-flash-image-preview/requests/{request_id}/status \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json'

响应

object

任务已完成或失败

响应体属性

  • statusenum, 必填
  • 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[], 必填
    • usageobject

      异步生图任务的 Token 用量。仅在任务成功完成且存在用量记录时返回；历史任务可能不含此字段。明细字段已包含在对应的输入或输出总量中，详见 Usage 字段与计费对账。

响应

application/json
{
  "status": "COMPLETED",
  "request_id": "qimage-root-1782369141807001000",
  "response_url": "https://api.qnaigc.com/queue/fal-ai/gemini-3.1-flash-image-preview/requests/qimage-root-1782369141807001000",
  "status_url": "https://api.qnaigc.com/queue/fal-ai/gemini-3.1-flash-image-preview/requests/qimage-root-1782369141807001000/status",
  "cancel_url": "",
  "queue_position": 0,
  "logs": null,
  "metrics": {
    "inference_time": 38
  },
  "result": {
    "images": [
      {
        "url": "https://aitoken-image.qnaigc.com/gemini-image/root/qimage-root-1782369141807001000/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
      }
    }
  }
}

获取任务结果

GET
/queue/fal-ai/gemini-3.1-flash-image-preview/requests/{request_id}

获取文生图或图片编辑任务结果。任务进行中返回 HTTP 400 状态响应；参数错误返回 Fal 错误响应；任务失败返回对应错误码和 Fal 错误详情；成功返回 Fal 格式图片列表。

认证方式

FalApiKeyAuthAPI 密钥

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

header 参数：Authorization

路径参数

  • Name
    request_id
    Type
    string, 必填
    Description

    提交任务时返回的 request_id。

请求体

暂无请求体

请求

GET/queue/fal-ai/gemini-3.1-flash-image-preview/requests/{request_id}
curl https://api.qnaigc.com/queue/fal-ai/gemini-3.1-flash-image-preview/requests/{request_id} \
  --header 'Authorization: YOUR_FAL_API_KEY_AUTH' \
  --header 'Accept: application/json'

响应

object

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

响应体属性

  • detailobject, 必填
    • locstring[], 必填

      错误位置。

    • msgstring, 必填

      人类可读的错误描述。

    • typestring, 必填

      机器可读的错误分类标识符。

    • urlstring, 必填

      错误类型文档链接。

    • ctx

      附加结构化上下文（可选）。

    • input

      导致错误的输入（可选）。

响应

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

火山格式图片生成

POST
/volcengine/v3/images/generations

使用火山格式图片生成协议同步调用平台支持的图片模型。文生图、图生图、多图融合和图层拆分共用一个接口：POST /volcengine/v3/images/generations。

当前支持模型：

  • bytedance/doubao-seedream-5.0-pro
  • bytedance/doubao-seedream-5.0-flash
  • byteplus/dola-seedream-5.0-pro
  • byteplus/dola-seedream-5.0-flash

四个模型均通过 model 字段选择，并使用下方 Schema 中声明的 Seedream 5.0 Pro/Flash 参数。普通生图支持 0～10 张参考图；图层拆分必须且只能输入 1 张 PNG 或 JPEG，并允许 prompt 为空。未在 Schema 中声明的 SDK 通用字段不属于当前四个模型的公开能力。

认证方式

BearerAuthBEARER

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

Bearer 格式：JWT

请求体

请求体属性

  • modelenum, 必填

    模型 ID，必须是当前平台已接入的火山格式图片生成模型。

  • promptstring

    普通生图必填，去除首尾空白后不能为空；图层拆分可以省略或传空字符串，也可以指定需要拆分的目标元素。建议中文不超过 300 字、英文不超过 600 词。

  • imagestring | string[]

    参考图，支持可访问的公网 URL 或 data:image/<格式>;base64,<数据>。普通生图最多 10 张；支持 jpeg、png、webp、bmp、tiff、gif、heic、heif，单图不超过 30 MB，宽高比为 1/16～16，宽和高均大于 14 px，总像素为 196～36000000。图层拆分必须且只能传 1 张 PNG 或 JPEG，单图不超过 30 MB，总像素为 262144～36000000。

    • oneOf[0]string
      可选。
    • oneOf[1]string[]
      可选。
  • response_formatenum

    图片返回格式。url 返回约 24 小时有效的临时链接；b64_json 返回 Base64 数据。响应会在 data[].url 和 data[].b64_json 中二选一。

    default: url

  • sizestring

    输出尺寸。普通生图支持 1K、1.5K、2K 或 widthxheight，默认 2K；自定义尺寸总像素须为 921600～4624220，宽高比须为 1/16～16。图层拆分仅支持 1K、1.5K、2K、auto，默认 auto。

  • watermarkboolean

    是否添加 AI 生成水印。

    default: true

  • optimize_prompt_optionsobject

    提示词优化配置。Seedream 5.0 Pro 支持 standard 和 fast；Seedream 5.0 Flash 仅支持 standard。

    additionalProperties: false

    • modeenum

      standard 质量更高、耗时较长；fast 延迟更低，但仅 Seedream 5.0 Pro 支持。

      default: standard

  • output_formatenum

    输出格式，支持 jpeg 或 png。通常默认 jpeg；background=transparent 且省略该字段时默认 png，显式传入 jpeg 会报错。图层拆分时仅控制底图，拆分图层始终为 PNG。

  • backgroundenum

    背景透明度。transparent 仅适用于图生图，且只能输入 1 张带透明通道的图片；显式指定 output_format 时只能使用 png。输入 JPEG 等不支持透明通道的格式会报错。

    default: opaque

  • layer_decompositionboolean

    是否开启图层拆分。true 时将单张输入图拆为 1 张底图和最多 16 个独立图层；任一图层生成失败时整次请求失败。必须传 JSON 布尔值，不能传字符串 "true"。

    default: false

  • allOf[0]
    可选。

请求

POST/volcengine/v3/images/generations
curl https://api.qnaigc.com/volcengine/v3/images/generations \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "bytedance/doubao-seedream-5.0-pro",
  "prompt": "一只红色陶瓷茶壶放在浅色木桌上，摄影棚柔光，4:3 构图",
  "size": "1.5K",
  "watermark": false,
  "response_format": "url"
}'

响应

object

图片生成成功。

响应体属性

  • modelstring, 必填

    实际执行的模型标识。

  • createdinteger, 必填

    创建时间，Unix 时间戳（秒）。

  • data[], 必填
    • urlstring<uri>

      临时图片 URL。response_format=url 时返回，通常约 24 小时有效。

    • b64_jsonstring

      Base64 图片数据。response_format=b64_json 时返回。

    • sizestring, 必填

      实际输出尺寸，格式为 widthxheight。

    • output_formatenum, 必填

      实际输出格式。

    • z_indexinteger

      图层顺序。底图为 0，其他图层从 1 开始。

    • namestring

      图层名称。

    • descriptionstring

      图层内容描述。

    • bounding_boxobject

      additionalProperties: false

    • anyOf[0]
      可选。
    • anyOf[1]
      可选。
  • usageobject

    additionalProperties: false

    • input_imagesinteger

      输入图片数量。

      minimum: 0

    • generated_imagesinteger

      生成图片数量；图层拆分时包含底图和图层。

      minimum: 0

    • output_tokensinteger

      上游返回的技术用量。

      minimum: 0

    • total_tokensinteger

      上游返回的总技术用量。

      minimum: 0

响应

application/json
{
  "model": "doubao-seedream-5-0-pro-260628",
  "created": 1790234881,
  "data": [
    {
      "url": "https://example.com/generated.jpeg",
      "size": "1792x1344",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "input_images": 0,
    "generated_images": 1,
    "output_tokens": 9408,
    "total_tokens": 9408
  }
}

Last updated

© 2026 Modelink. All rights reserved.

构建来自Clarify