Leonardo.ai API 快速上手：从申请密钥到生成第一张图片

Leonardo.ai 的图像生成能力除了可以在网页应用里手动操作，也通过 REST API 对外开放。如果你想把文生图、图生图、视频生成这类能力接进自己的后端服务、批处理脚本或内部工具，就需要走 API 这条路。API 与网页应用的订阅是两套体系：网页应用的免费额度或付费套餐并不会自动解锁 API 调用权限，必须单独购买 API 额度并生成密钥。这篇教程面向有一定 HTTP 请求基础的开发者，从零开始走完「拿到密钥 → 发出第一个生成请求 → 取回图片」的完整链路。如果你更想先在浏览器里直观地试用这个工具，可以先看站内的 Leonardo.ai 工具页，再决定是否接入 API。

准备工作

在写第一行请求代码之前，需要先把账号和额度准备好。以下几项缺一不可。

注册并登录网页应用

Leonardo.ai 的 API 密钥是在网页应用里生成的，所以第一步是注册或登录 Leonardo.ai 的网页应用。没有账号就无法进入 API Access 页面，也就拿不到密钥。

购买 API 额度

这是最容易踩坑的一点：API 访问权限与网页应用的免费额度、订阅套餐是分开的。即使你已经在网页应用里有可用的生成额度，也不能直接拿去调 API。要调用 API，必须单独购买 API Credits。购买入口在网页应用的 API Access 页面里，进入该页面后选择 Buy Credit 即可。

计费方式上，API 用量以美元计价，可以在 API Access 页面查看剩余额度。具体的价格档位、额度包大小会随时间调整，下单前请以官网当前展示的信息为准。

确认调用地址与鉴权方式

API 的基础地址是 https://cloud.leonardo.ai/api/rest/v1（v2 版本的部分接口路径为 https://cloud.leonardo.ai/api/rest/v2）。鉴权使用 Bearer Token，也就是在请求头里带上 authorization: Bearer <YOUR_API_KEY>。请求与响应都使用 JSON，因此需要同时设置 accept: application/json 与 content-type: application/json。

操作步骤

第一步：创建 API 密钥

登录网页应用后，在左侧菜单里找到 API Access，进入该页面。页面上会有一个 Create New Key 按钮，点击它开始创建密钥。

创建时需要给密钥起一个名字，方便日后区分用途。命名建议带上环境或服务标识，例如 myapp-prod 表示生产环境，backend-service 表示某个后端服务。这样在排查用量或需要轮换密钥时，能一眼看出哪把密钥属于哪个系统。

创建过程中还可以选择性地配置一个 webhook 回调地址。配置之后，生成任务完成时服务端会主动把结果推送到这个地址，你就不必反复轮询查询任务状态。如果暂时不确定要不要用回调，可以先跳过，后续再补。

密钥创建完成后请妥善保存。不要把它写进前端代码或任何会分发给终端用户的客户端代码里，因为任何拿到密钥的人都能以你的账号身份消耗额度。正确的做法是把密钥放在服务端的环境变量或密钥管理服务中，由后端代理请求。

第二步：发出第一个生成请求

密钥就绪后就可以调用生成接口了。图像生成使用 POST /generations 端点。下面是一个可以直接运行的 cURL 示例：

curl --request POST \
  --url https://cloud.leonardo.ai/api/rest/v1/generations \
  --header 'accept: application/json' \
  --header 'authorization: Bearer <YOUR_API_KEY>' \
  --header 'content-type: application/json' \
  --data '
{
  "alchemy": false,
  "height": 1080,
  "modelId": "7b592283-e8a7-4c5a-9ba6-d18c31f258b9",
  "contrast": 3.5,
  "num_images": 4,
  "styleUUID": "111dc692-d470-4eec-b791-3475abac4c46",
  "prompt": "A serene watercolor painting of a mountain lake at sunrise",
  "width": 1920,
  "ultra": false
}'

把 <YOUR_API_KEY> 替换成上一步生成的密钥即可。请求体里的字段含义如下：

字段	类型	说明
prompt	string	描述想要生成画面的文本提示词
modelId	string	指定使用的模型，不同模型支持的参数与出图风格不同
width / height	number	输出图片的宽高像素值
num_images	number	本次任务生成几张图
styleUUID	string	风格预设的标识，用于统一出图风格
contrast	number	对比度相关的调节参数
alchemy	boolean	是否启用增强处理
ultra	boolean	是否启用更高画质的处理模式

请求发出后，返回结果里会包含一个 generationId。这个 ID 是后续取回图片的凭据，需要保存下来。生成是异步的，也就是说接口不会在响应里直接返回图片，而是先返回任务标识，等任务跑完再去查询结果。

第三步：用 generationId 取回生成结果

拿到 generationId 之后，用它去查询该次生成任务的状态与产物。查询时同样需要带上 Bearer 鉴权头。由于生成需要一定时间，通常的做法是间隔若干秒轮询一次，直到任务状态变为完成，再从响应里取出图片地址。

如果不想写轮询逻辑，可以在创建密钥时或后续配置 webhook 回调地址。任务完成时服务端会把结果推送到该地址，你的服务只需暴露一个接收端点即可，这样能省掉轮询带来的额外请求和延迟。

第四步（可选）：从网页应用导出 API 代码

如果不想从零手写请求体，可以利用 Get API Code 功能。在网页应用里完成一次图像或视频生成后，可以把这次生成直接导出为可用的 API 代码。这样得到的参数组合是经过网页应用验证的，适合作为自己代码的起点，再逐步替换提示词、模型和尺寸。

一个完整示例

下面把前面的步骤串成一个最小可运行的流程。假设你已经拿到了 API 密钥，并把它放在环境变量 LEONARDO_API_KEY 里。

第一步，提交生成任务。

curl --request POST \
  --url https://cloud.leonardo.ai/api/rest/v1/generations \
  --header 'accept: application/json' \
  --header "authorization: Bearer $LEONARDO_API_KEY" \
  --header 'content-type: application/json' \
  --data '
{
  "alchemy": false,
  "height": 1080,
  "modelId": "7b592283-e8a7-4c5a-9ba6-d18c31f258b9",
  "contrast": 3.5,
  "num_images": 4,
  "styleUUID": "111dc692-d470-4eec-b791-3475abac4c46",
  "prompt": "A serene watercolor painting of a mountain lake at sunrise",
  "width": 1920,
  "ultra": false
}'

第二步，从响应里取出 generationId。响应是 JSON 格式，其中包含本次任务的标识。把这个值记下来，下一步要用。

第三步，用该 ID 查询任务结果。带上同样的鉴权头请求查询接口，等待任务完成后从返回内容里取出图片地址。如果任务尚未完成，稍等几秒再查一次。

第四步，下载或转发图片。拿到图片地址后，按你的业务需要下载到本地、上传到自己的对象存储，或直接返回给前端展示。

整个链路的核心只有两点：提交任务拿到 ID，再用 ID 换结果。把这两步封装成一个函数，后续换模型、换提示词都只是改请求体的事。

注意事项

API 套餐与网页应用套餐相互独立

这是新手最容易误解的地方。网页应用的免费额度和订阅套餐只作用于网页应用本身，不会解锁 API 调用。要调 API，必须单独购买 API 额度。反过来，API 额度也不等同于网页应用里的订阅权益。规划预算时要把这两笔开销分开算。

密钥安全

API 密钥等同于账号在 API 层面的身份凭证。不要把它嵌入客户端代码，不要提交到公开的代码仓库，也不要在日志里明文打印。建议通过环境变量或密钥管理服务注入，并定期轮换。

并发、队列与速率限制

API 存在并发限制与用量上限。当并发任务数达到上限时，新提交的任务会进入队列等待，而不是立即失败。设计批量生成流程时，需要把排队等待时间考虑进去，避免因为超时误判为失败而重复提交。具体的并发数值与速率上限请以官网当前信息为准。

计费透明度

API 用量以美元计价，剩余额度可以在 API Access 页面查看。不同模型、不同分辨率、不同生成张数消耗的额度并不相同，批量任务上线前建议先用小批量试跑，估算单张成本，再决定生产环境的参数配置。价格与额度规则可能调整，请以官网当前信息为准。

内容安全

平台对生成内容有安全策略。涉及敏感题材的生成请求可能被拦截或返回相应提示，业务侧需要处理这类返回，而不是把它当成普通的网络错误重试。

模型与接口版本

可用的模型列表会持续更新，不同模型对参数的支持范围也不一样。例如某些模型支持特定的宽高比或额外的控制参数，换模型时需要重新核对请求体字段。接口本身也区分 v1 与 v2 路径，接入前先确认目标端点属于哪个版本。模型标识、参数支持范围与端点路径都可能变化，请以官网当前文档为准。

善用回调与导出功能

如果生成任务量大，轮询会带来不必要的请求开销和延迟，此时配置 webhook 回调更合适。如果只是想快速验证某个参数组合是否可行，用 Get API Code 从网页应用导出代码，比手写请求体更省事。