OpenAPI 参考

Modelink API · 图像

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

版本 1.0.0

提交文生图任务

POST

/queue/openai/gpt-image-2

提交 gpt-image-2 文生图异步任务。鉴权通过后创建任务并立即返回 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, 必填
图片生成提示词，必填，最长 32000 个字符。
- - square
    1024×1024（1:1）
  - square_hd
    1024×1024（1:1；当前与 square 相同）
  - portrait_4_3
    768×1024（3:4 竖图）
  - portrait_16_9
    864×1536（9:16 竖图）
  - landscape_4_3
    1024×768（4:3 横图）
  - landscape_16_9
    1536×864（16:9 横图）
  - auto
    由模型根据提示词和输入图片自动选择尺寸。
- - widthinteger, 必填
    图像宽度（像素）
    minimum: 1
  - heightinteger, 必填
    图像高度（像素）
    minimum: 1
- auto
- low
- medium
- high
num_imagesinteger
生成图片数量。默认 1，范围 1～4。
default: 1; minimum: 1; maximum: 4
- jpeg
- png
- webp

请求

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

任务已入队

响应体属性

- 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/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

BearerAuthBEARER

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

Bearer 格式：JWT

查询参数

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

请求体

请求体属性

promptstring, 必填
图片编辑提示词，必填，最长 32000 个字符。
image_urlsstring[], 必填
编辑所使用的参考图片 URL 列表，必填。平台当前最多接受 10 张。
mask_urlstring<uri>
可选的遮罩图片 URL，用于指示需要编辑的区域。
- - square
    1024×1024（1:1）
  - square_hd
    1024×1024（1:1；当前与 square 相同）
  - portrait_4_3
    768×1024（3:4 竖图）
  - portrait_16_9
    864×1536（9:16 竖图）
  - landscape_4_3
    1024×768（4:3 横图）
  - landscape_16_9
    1536×864（16:9 横图）
  - auto
    由模型根据提示词和输入图片自动选择尺寸。
- - widthinteger, 必填
    图像宽度（像素）
    minimum: 1
  - heightinteger, 必填
    图像高度（像素）
    minimum: 1
- auto
- low
- medium
- high
num_imagesinteger
生成图片数量。默认 1，范围 1～4。
default: 1; minimum: 1; maximum: 4
- jpeg
- png
- webp

请求

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

任务已入队

响应体属性

- 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/openai/gpt-image-2/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/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

任务已完成或失败

响应体属性

- IN_QUEUE
- IN_PROGRESS
- COMPLETED
request_idstring, 必填
必填。
response_urlstring
可选。
status_urlstring
可选。
cancel_urlstring
可选。
queue_positioninteger
可选。
logsobject | null
可选。
- locstring[]
  错误定位（fal.ai 标准错误详情，恒返回，默认 ["body"]）。
- msgstring
  错误信息。
- typestring
  错误类型。
- urlstring
  错误参考链接（fal.ai 标准错误详情，恒返回，默认空串）。
- - *string
    可选。

object

任务进行中（IN_QUEUE / IN_PROGRESS）

响应体属性

- IN_QUEUE
- IN_PROGRESS
- COMPLETED
request_idstring, 必填
必填。
response_urlstring
可选。
status_urlstring
可选。
cancel_urlstring
可选。
queue_positioninteger
可选。
logsobject | null
可选。
- locstring[]
  错误定位（fal.ai 标准错误详情，恒返回，默认 ["body"]）。
- msgstring
  错误信息。
- typestring
  错误类型。
- urlstring
  错误参考链接（fal.ai 标准错误详情，恒返回，默认空串）。
- - *string
    可选。

响应

{
  "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": {}
  }
}

获取任务结果

GET

/queue/openai/gpt-image-2/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/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 错误详情

响应体属性

- locstring[]
  错误定位（fal.ai 标准错误详情，恒返回，默认 ["body"]）。
- msgstring
  错误信息。
- typestring
  错误类型。
- urlstring
  错误参考链接（fal.ai 标准错误详情，恒返回，默认空串）。
- - *string
    可选。

object | object

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

响应体属性

- - IN_QUEUE
  - IN_PROGRESS
  - COMPLETED
- request_idstring, 必填
  必填。
- response_urlstring
  可选。
- status_urlstring
  可选。
- cancel_urlstring
  可选。
- queue_positioninteger
  可选。
- logsobject | null
  可选。
- - locstring[]
    错误定位（fal.ai 标准错误详情，恒返回，默认 ["body"]）。
  - msgstring
    错误信息。
  - typestring
    错误类型。
  - urlstring
    错误参考链接（fal.ai 标准错误详情，恒返回，默认空串）。
  - *string
    可选。
- - locstring[]
    错误定位（fal.ai 标准错误详情，恒返回，默认 ["body"]）。
  - msgstring
    错误信息。
  - typestring
    错误类型。
  - urlstring
    错误参考链接（fal.ai 标准错误详情，恒返回，默认空串）。
  - *string
    可选。

响应

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