青云TOP API使用教程&开发文档小白用户&专业开发者快速使用指南
控制台
返回模型调用 API 参考
POST/fal-ai/flux-pro/kontext/text-to-image

/fal-ai/flux-pro/kontext/text-to-image

通过青云TOP API 调用 Fal.ai 图片生成入口。本文按该动作的独立 Body schema 说明参数、异步结果和下载处理。

API Key application/json

通过青云TOP API 调用 Fal.ai 图片生成入口。本文按该动作的独立 Body schema 说明参数、异步结果和下载处理。

功能与适用场景

本页用于 Fal.ai 图片生成，请求结构只适用于路径中的动作和模型。需要更换模型或动作时，请返回 Fal.ai 目录选择对应页面。

支持模型与组合

路径模型：flux-pro/kontext/text-to-image。调用前用 GET /v1/models 检查完整模型 ID、分组权限和当前渠道；Fal.ai 官方模型页的更新不会自动改变本站 allowlist。
图片 URL、Base64、数组顺序、尺寸和安全检查器按本页 schema 填写；上游支持的字段不代表本站当前入口一定透传。

第一步：设置鉴权

请求头使用 Authorization: Bearer YOUR_API_KEY 和 Content-Type: application/json。不要发送 Fal Token，也不要把真实 API Key 写入前端、日志或仓库。

第二步：调用模型

请求地址：POST https://top.qingyuntop.ai/fal-ai/flux-pro/kontext/text-to-image。提交成功后保存 request_id、status_url 和 response_url。

Fal.ai 异步协议

调用与返回说明

创建 Fal.ai 图片任务。本站公开流程是提交/查询/读取结果；模型和参数是否对当前 API Key 开放，以 GET /v1/models、分组权限和实际响应为准。

请求时注意

  • 使用 `Authorization: Bearer YOUR_API_KEY`；这是青云TOP API Key，不是 Fal.ai Token。
  • 创建前调用 `GET /v1/models`，确认完整模型 ID、渠道和分组权限。官方模型页可用于能力参考，不能作为本站已开放承诺。
  • 请求体使用本页递归 schema；图片/视频 URL 必须从服务端可访问，Base64 和数组顺序按字段说明处理。
  • Fal.ai 官方还支持 queue、streaming 和 webhook；本站页面未声明的字段不能自行推断为可用。

返回时注意

  • HTTP 2xx 只表示请求被接受；业务结果以 status 和 output/result 字段为准。
  • 保存 request_id、status_url 和 response_url，按退避轮询到终态后再下载。
  • 结果 URL 可能过期，成功后立即下载到自己的存储；不要把临时 URL 当作永久公共资源。
Request

请求

/fal-ai/flux-pro/kontext/text-to-image

Body

必填
Bodyapplication/json
Bodyobject
promptstring必填

描述希望生成或编辑的画面/视频内容。 生成图像的提示。

示例一只橘猫坐在窗边，柔和自然光
guidance_scalenumber

本接口的模型参数。请结合类型、枚举和范围填写。 CFG（无分类器引导）量表用于衡量您希望模型在寻找相关图像时与提示的贴近程度。默认值：3.5 范围值1-20

示例0
num_imagesinteger

一次任务生成的图片数量。结果可能以数组返回，生成成功后立即保存。 生成的图像数量。默认值：1 范围值1-4

示例https://example.com/input.png
output_formatstring

本接口的模型参数。请结合类型、枚举和范围填写。 生成图片的格式。默认值："jpeg" 支持default、png、jpeg

示例jpeg
safety_tolerancestring

本接口的模型参数。请结合类型、枚举和范围填写。 生成图像的安全容差等级。1 表示最严格，5 表示最宽松。默认值："2"

示例
aspect_ratiostring

本接口的模型参数。请结合类型、枚举和范围填写。 生成图像的宽高比。默认值："1:1" 支持：21：9、16：9、4：3、3：2、1：1、2：3、3：4、9：16、9：21

示例16:9
Response

返回响应 200

HTTP 响应
响应 200json
响应 200object
statusstring

任务状态。常见阶段为 queued、in_progress/processing、completed/succeeded、failed、cancelled；以实际响应为准。

示例queued
request_idstring

创建请求返回的公开请求 ID，后续查询时原样使用。

示例REQUEST_ID
response_urlstring

任务完成后读取结果的 URL；地址可能过期，应立即下载。

示例https://example.com/result.json
status_urlstring

查询状态的 URL。

示例https://top.qingyuntop.ai/fal-ai/model/requests/REQUEST_ID
cancel_urlstring

可取消任务的 URL，仅在当前任务状态允许时有效。

示例https://top.qingyuntop.ai/fal-ai/model/requests/REQUEST_ID/cancel
queue_positioninteger

排队位置，任务运行后可能缺省。

示例1
outputstring | array<string> | object

成功结果。图片、视频或文件可能以 URL、URL 数组或对象返回，按 schema 分支读取。

errorobject

失败详情；记录 code/message，不要把失败响应当作可下载结果。

Fal.ai 异步协议

调用与返回说明

创建 Fal.ai 图片任务。本站公开流程是提交/查询/读取结果；模型和参数是否对当前 API Key 开放，以 GET /v1/models、分组权限和实际响应为准。

请求时注意

  • 使用 `Authorization: Bearer YOUR_API_KEY`；这是青云TOP API Key，不是 Fal.ai Token。
  • 创建前调用 `GET /v1/models`，确认完整模型 ID、渠道和分组权限。官方模型页可用于能力参考，不能作为本站已开放承诺。
  • 请求体使用本页递归 schema；图片/视频 URL 必须从服务端可访问，Base64 和数组顺序按字段说明处理。
  • Fal.ai 官方还支持 queue、streaming 和 webhook；本站页面未声明的字段不能自行推断为可用。

返回时注意

  • HTTP 2xx 只表示请求被接受；业务结果以 status 和 output/result 字段为准。
  • 保存 request_id、status_url 和 response_url，按退避轮询到终态后再下载。
  • 结果 URL 可能过期，成功后立即下载到自己的存储；不要把临时 URL 当作永久公共资源。

异步任务、查询与下载

创建成功不等于生成完成。按响应中的 status_url 查询并实施退避，直到成功、失败或取消终态。不要自行拼接 fal.ai 官方 URL，也不要把上游内部 ID 改写成其他格式。

常见错误、限制与迁移

  • 401/403：API Key、分组权限或模型未开放；重新请求 GET /v1/models，不要改用 Fal Token。
  • 400/422：Body 字段、类型、媒体 URL、数组顺序或模型组合不符合本页 schema；先缩小到最小请求再逐项加入可选字段。
  • 429/5xx 或网络中断：按退避重试提交/查询；提交可能已经成功时不要盲目重复创建，先用已保存的 request ID 查询。
  • 页面中的 Apifox 快照用于结构化展示，模型是否最新以官方资料、本站当前模型目录和实际响应共同核对。

官方参考