进阶 docs.leonardo.ai 2026-11-22 15:11:20 · 0 阅读

第69章 Leonardo.Ai API 常见错误消息排查指南

API 错误消息 调试通过 API 集成 Leonardo.Ai 时遇到的常见问题。如果你的应用在 API 集成中出现问题,此列表可帮助你排查。如果问题仍未解决,请联系 Leonardo.Ai 支持团队以获取更多帮助。 授权钩子返回无效响应 ```json { "error": "Invalid response from authorization hook", "path": "$", "code": "unexpected" } ``` * 检查 API 密钥是否遵循有效的 UUID 格式。 * 检查 API 密钥是否正确。 * 检查是否正确设置了 API 密钥。应将其作为 `authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` 添加到请求头中。 * 例如,使用 curl 命令时: ```bash curl --request POST \ --url https://cloud.leonardo.ai/api/rest/v1/generations \ --header 'accept: application/json' \ --header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \ --header 'content-type: application/json' \ --data ' { "height": 512, "modelId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "prompt": "An oil painting of a cat", "width": 512 } ' ``` 认证钩子拒绝此请求 ```json { "error": "Authentication hook unauthorized this request", "path": "$", "code": "access-denied" } ``` 与“授权钩子返回无效响应”类似,请检查是否正确设置了 API 密钥。应将其作为 `authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` 添加到请求头中。 无效的文件扩展名 ```json { "error": "invalid file extension", "path": "$", "code": "unexpected" } ``` Upload Init Image API 中的 `extension` 参数是指你要上传的图像文件的扩展名。文件扩展名的示例包括 png、jpg、jpeg 和 webp。该参数不接受文件名或图像数据。 Upload Init Image API 返回一个用于上传图像的预签名 URL。关于如何使用返回的预签名 URL 的详细指南,请参阅:《如何使用预签名 URL 上传图像》。 期望布尔值 Boolean 但找到了字符串 ```json { "error": "expected a boolean for type 'Boolean', but found a string", "path": "$.selectionSet.sdGenerationJob.args.arg1.photoReal", "code": "validation-failed" } ``` 检查你的代码是否错误地将输入转换为字符串,而不是布尔值。接受的值是 `true` 或 `false`。使用引号包裹 `"true"` 或 `"false"` 可能会被解释为字符串。 意外的变量 ```json { "error": "Unexpected variable sd_Version", "path": "$", "code": "bad-request" } ``` 检查是否指定了正确的 body 参数。Body 参数区分大小写。例如,`sd_version` 是正确的参数,因此指定 `sd_Version` 会触发意外变量错误。 上传图像时出现 204 (No Content) 通过预签名 URL 上传图像时,204 是预期的成功响应码,且不会返回任何内容。此处不会返回图像 ID。相反,图像 ID 已经在前一步调用 Upload Init Image API 时返回了。 例如,图像 ID 位于下方的 `uploadInitImage.id` 中: ```json { "uploadInitImage": { "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "fields": …, "key": …, "url": … } } ``` 400 Bad Request: 图像数量过多 创建图像生成任务时,如果单次请求中的 `num_images` 过大,请将其降低。根据图像生成请求的大小和设置,每次请求支持的图像数量上限不同。如果需要更多图像,需发起单独的图像生成请求。 上传图像时出现 403 Forbidden 错误 通过预签名 URL 上传图像时,请移除与认证相关的请求头(如 API 密钥),因为使用预签名 URL 时不需要这些。 403 Forbidden: 内容审核过滤 示例 1: ```json { "error": "Your prompt appears to contain inappropriate content, please be mindful of our Terms of Service. You may modify your prompt and try again.", "path": "$", "code": "unexpected" } ``` 示例 2: ```json { "error": "content moderation filter: naked", "path": "$", "code": "unexpected" } ``` 此错误意味着你的生成请求可能会生成超出 Leonardo 服务条款范围的图像。我们建议避免使用可能导致描绘色情、暴力等内容的提示词,这些内容在服务条款的“使用限制”中已有列出。 无法访问图像 ```json { "error": "couldn't access image", "path": "$", "code": "unexpected" } ``` 使用 Create Upscale API 和 Create Unzoom API 等变体功能时,预期的图像 ID 应为在 Leonardo.Ai 上生成的图像的 ID。该图像 ID 由 Get a Single Generation API 返回。 例如,图像 ID 位于下方的 `generations_by_pk.generated_images[0].id` 中: ```json { "generations_by_pk": { "generated_images": \[ { "url": …, "nsfw": …, "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "likeCount": …, "generated_image_variation_generics": \[] }, ], … } } ``` 目前,我们不支持对通过 Upload Init Image API 上传的图像使用变体功能。 未找到初始变体 ```json { "error": "failed to find init variation", "path": "$", "code": "unexpected" } ``` 与“无法访问图像”类似,预期的图像 ID 应为在 Leonardo.Ai 上生成的图像的 ID。该图像 ID 由 Get a Single Generation API 返回。 无效的 init image id ```json { "error": "invalid init image id", "path": "$", "code": "unexpected" } ``` 检查你的 init image ID 是否遵循有效的 UUID 格式。 `init_image_id` 参数接受由 Upload Init Image API 返回的图像 ID。如果要使用在 Leonardo.Ai 中生成的图像作为初始图像,请改用 `init_generation_image_id` 参数指定图像 ID。 200 Success 但图像 URL 数组为空 检查响应体中是否包含 `"status": "COMPLETE"`。该端点返回 `generations_by_pk.status` 属性。成功完成的图像生成任务状态为 COMPLETE。 原因是 Get a Single Generation API 端点返回了 200 成功响应,但 `generations_by_pk.generated_images[]` 为空。因此未返回图像 URL。
​
图片生成并非即时完成,所以发送生成图片请求后不要期望立刻拿到图片。最佳做法是在创建 API key 时指定 webhook 回调地址,这样生成完成后会收到一条包含图片 URL 的消息。 Key Creation Error Occurred 症状:在创建 Production API key 时指定 webhook 回调地址,界面上报错"Key Creation Error Occurred"。 请检查 webhook URL 是否使用了 https 而不是 http。如果用的是 http,控制台会出现如下错误"WebhookCallbackUrl is not a valid url": { "errors": [ { "message": "WebhookCallbackUrl is not a valid url (must be https://)", "extensions": { "path": "$", "code": "unexpected" } } ] } Failed to find init variation { "error": "failed to find init variation", "path": "$", "code": "unexpected" } 在使用 unzoom、no background 这类 variation API 端点时,将参数 isVariation 设为 true 表示你提供的图片 ID 是之前某次 variation 生成的结果。
​

举个例子,你使用了变体 API 端点 upscale 并获取了一个图像 ID。如果希望该 ID 生成的图像无背景,需将 isVariation 设置为 true。若该 ID 并非来自之前的变体,则应将 isVariation 设为 false,或省略该字段。

Service Error
{
"error": "Service Error",
"path": "$",
"code": "unexpected"
}
这是 Leonardo.Ai 的通用错误提示。如需进一步排查问题,请联系技术支持。若此错误发生在创建 Motion SVD 生成任务时,请确认你使用的是 Get a single Generation 返回的图像 ID,而非 Create a generation of Images 返回的生成 ID。

Invalid Dimensions
{
"error": "invalid dimensions",
"path": "$",
"code": "unexpected"
}
这是应用 Alchemy 时常见的错误。请确保高度和宽度在 32 到 1024 之间,且为 8 的倍数。经过 Alchemy 流程处理的图像最终尺寸会大于初始输入尺寸。

Expecting a value for non-nullable variable: "prompt"
{
"error": "expecting a value for non-nullable variable: \"prompt\"",
"path": "$",
"code": "validation-failed"
}
当 API 请求体格式不正确时,会出现此通用错误。由于 'prompt' 是 Create Generation of Images 端点唯一必填的字段,因此显示此消息。请检查 API 请求体格式是否正确。

Invalid prompt, maximum length of 1500 characters exceeded.
{
"error": "Invalid prompt, maximum length of 1500 characters exceeded.",
"path": "$",
"code": "unexpected"
}
当提示词超过 1,500 个字符时,通常会看到此错误。尝试缩短提示词以符合长度限制。

Prompt is too long, please keep it under 200 characters
{
"error": "Prompt is too long, please keep it under 200 characters",
"path": "$",
"code": "unexpected"
}
使用 Improve Prompt 端点时,通常会遇到此错误。请确保提示词在 200 个字符以内。

Model is not supported within the Production API
{
"error": " is not supported within the Production API. Please try again with a different model ID.",
"path": "$",
"code": "unexpected"
}
当请求的模型不受 Production API 支持时,会返回此错误。更新于 10 个月前 此页面是否有帮助?

评论 (0)