letzai-api

LetzAI API 集成技能

概述

帮助你集成 LetzAI 公共 API，用于生成和编辑 AI 图像及视频、放大图像、上传资源和训练自定义模型（LoRA）。自定义训练的人物、物体和风格模型可在提示词中通过 @modelname 引用。

身份验证

• 基础 URL： https://api.letz.ai
• 身份验证： Authorization: Bearer YOUR_API_KEY
• 获取 API 密钥： letz.ai/subscription
• Swagger（权威来源）： api.letz.ai/doc — 可通过 /doc-json 和 /doc-yaml 获取机器可读版本

const headers = {
  'Content-Type': 'application/json',
  Authorization: `Bearer ${process.env.LETZAI_API_KEY}`,
};

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['LETZAI_API_KEY']}",
}

请勿将公共 API 与私有 API 混淆。 https://api.letz.ai 是此处介绍的公共开发者 API。https://private-api.letz.ai 为 LetzAI 网页应用提供支持，路由名称不同（/upscales、/image_completions、/video-edits）。这些路由在公共 API 上会返回 404。

拒绝未知字段

API 会严格验证请求正文。发送架构中不存在的字段会返回 400。特别是，POST /images 不支持 negativePrompt、seed 或 aspectRatio；宽高比通过 width/height 表示。

核心工作流

1. 图像生成 — POST /images

参数	类型	默认值	说明
prompt	字符串	—	**必填。**可包含 @modelname 标签。
baseModel	字符串	账户默认值	请参阅下方的模型表。
mode	字符串	模型默认值	分辨率档位——允许值因模型而异。
width	整数	1600	480–2160
height	整数	1600	480–2160
quality	整数	2	1–6
creativity	整数	2	1–6
hasWatermark	布尔值	true
systemVersion	整数	账户默认值	2 或 3
hideFromUserProfile	布尔值	false
webhookUrl	字符串	—	任务完成时会发送 POST 请求。
organizationId	UUID	—	从你所属的组织扣除点数。

图像模型

mode 是分辨率档位，可接受的值因模型而异。

模型	baseModel	mode 值	点数（生成）	点数（编辑）
Nano Banana Pro（Google）	gemini-3-pro-image	default（1K） · 2k（HD） · 4k	80 / 160 / 240	80 / 160 / 240
Nano Banana 2（Google）	nbf-inferencesh	default（1K） · 2k（HD） · 4k	40 / 80 / 160	50 / 100 / 150
Nano Banana 2 Lite（Google）	nano-banana-2-lite	default（1K）	20	25
Seedream 5 Pro（ByteDance）	seedream-5-0-pro	2k（HD） · 4k	80 / 160	80 / 160
Seedream 4.5（ByteDance）	seedream-4-5-251128	2k（HD） · 4k	80 / 160	80 / 160
Flux 2（Black Forest Labs）	flux2	1k · hd	60 / 120	60 / 120
GPT Image 2（OpenAI）	gpt-image-2	1k · hd · 4k	160 / 240 / 480	160 / 240 / 480
WAN 2.7 Image Pro（Alibaba）	wan-2-7-image-pro	1k · 2k	10	10

也接受别名，例如，gemini-3-pro-image-preview 仍会解析为 Nano Banana Pro。 包含价格的实时目录位于 letz.ai/docs/models.json。

工作流

1. POST /images
2. 从响应中读取 id
3. 每隔 3 s 轮询一次 GET /images/{id}
4. 当 status === "ready" 时，读取 imageVersions.original

请参阅 examples/image_generation.js。

2. 视频生成 — POST /videos

参数	类型	说明
prompt	string	必填。
originalImageCompletionId	UUID	为之前生成的 LetzAI 图像制作动画。
imageUrl	string	为公开图像 URL 制作动画。
imageUrls	string[]	多帧：[0] = 首帧，[1] = 尾帧。
prompts	object[]	多镜头故事板（video-kling3）：[{ prompt, duration }]。
baseModel	string	可选；通常使用 settings.mode 选择模型。
width / height / resolution	number	可选的输出尺寸设置。
settings	object	模型 + 时长 + 音频（见下文）。
webhookUrl	string
hidePrompt	bool
organizationId	UUID

图像输入为可选项——纯文本转视频时，请省略 originalImageCompletionId / imageUrl / imageUrls。

settings

字段	说明
mode	视频模型键，参见下表。
duration	秒数，会限制在模型允许的值范围内。
withSound	在支持的情况下启用原生音频。
highQuality	更高分辨率档位，价格通常翻倍。
resolution	按秒计价的模型可选 "720p"、"1080p"、"4k"。

视频模型

将带 video- 前缀的键用作 settings.mode。

模型	settings.mode	时长	积分
Google Veo 3.1	video-veo31	8 s（固定）	1500 · 启用音频 ×2 · 1080p ×2
Kling V3	video-kling3	3–15 s	150 · 启用音频 300
Kling V2.6	video-kling26	5 或 10 s	150 · 启用音频 ×2 · 1080p ×2
WAN 2.5	video-wan25	5 或 10 s	110 · 1080p ×2（仅限图像转视频）
Seedance 2.0	video-seedance2	4–15 s	按秒计价：480p 为 105 · 720p 为 210 · 1080p 为 500 · 4K 为 1000（始终启用音频）
Seedance 2.0 Enterprise	video-seedance2-enterprise	4–15 s	与 Seedance 2.0 相同；需要 organizationId
Gemini Omni Flash	video-gemini-omni	3–10 s	每秒 100（始终启用音频）

工作流

1. POST /videos
2. 每隔 2–3 s 轮询 GET /videos/{id}
3. 当 status === "ready" 时，读取 videoVersions.original

参见 examples/video_generation.py。

3. 图像编辑 — POST /image-edits

参数	类型	说明
mode	string	必填。 context（AI 编辑）或 skin（修复皮肤）。
prompt	string	编辑指令。可包含 @modelname 标签。
imageUrl	string	单张源图像 URL。
inputImageUrls	string[]	多张参考源图像（实际最多 9 张）。
originalImageCompletionId	UUID	编辑之前生成的 LetzAI 图像。
originalImageCompletionIds	UUID[]	将多张 LetzAI 图像用作源图像。
baseModel	string	与图像生成使用相同的标识符。
settings	object	{ resolution, aspect_ratio, model }
imageCompletionsCount	int	要生成的变体数量（1–5，默认值为 1）。skin 不使用此参数。
mask	string	Base64 掩码，仅用于旧版修复填充。
width / height	number	目标尺寸。
webhookUrl、organizationId、hidePrompt

settings：

• resolution："2k"（高清）或 "4k"（超高清）
• aspect_ratio："1:1"、"16:9"、"9:16"、"4:3"、"3:4"、"21:9"、"9:21"
• model：与 baseModel 相同的标识符

至少提供一个源图像：imageUrl、inputImageUrls、originalImageCompletionId 或 originalImageCompletionIds。

优先使用顶层的 baseModel。 服务端队列路由会读取 baseModel； settings.model 会转发给工作器。将两者设为相同值最稳妥。

工作流

1. POST /image-edits
2. 每隔 3 s 轮询 GET /image-edits/{id}
3. 当 status === "ready" 时，读取 generatedImageCompletion.imageVersions.original

mode: "in"（修复填充）和 mode: "out"（扩展填充）已弃用，请改用 context。

4. 放大 — POST /upscale

公共路由是 /upscale（单数）。/upscales 是私有 Web 应用路由， 在此处会返回 404。

参数	类型	默认值	备注
imageId	UUID	—	LetzAI 图像生成任务 ID。
imageUrl	string	—	公共图像 URL。使用此参数代替 imageId。若要放大自己的文件，请通过 /user-assets 上传，并传入返回的 imageUrl。
mode	string	default	放大模型 — 见表格。
size	number	—	2–12；输出档位 — 见表格。
strength	number	1	1–5。
prompt	string	—	创意放大模型的可选指导提示。
webhookUrl、organizationId

mode	放大模型	size → 输出	点数
nano-banana-pro	Google Gemini 3 Pro	4 → 1K · 8 → 2K · 12 → 4K	80 / 160 / 240
nano-banana-2	Google Gemini 3.1 Flash	4 → 1K · 8 → 2K · 12 → 4K	50 / 100 / 150
gpt-image-2	OpenAI GPT Image 2	4 → 1K · 8 → 2K · 12 → 4K	160 / 240 / 480
pruna	Pruna P-Image-Upscale	4 → 1 MP · 8 → 4 MP · 12 → 16 MP	20 / 40 / 80
default	LetzAI 自研	—	20

工作流

1. POST /upscale
2. 每隔 3 s 轮询 GET /upscale/{id}
3. 当 status === "ready" 时，读取 imageVersions.original

5. 上传自己的文件 — POST /user-assets

两步式预签名 S3 上传。可用此方式在将本地文件传给 /image-edits、/videos 或 /upscale 前获取公共 URL。

1. 使用 { extension } 调用 POST /user-assets（还可选传入 originalFilename、 mimeType、fileSize、caption、metadata、numberOfImages）。
2. 使用匹配的 Content-Type 标头，将原始文件字节 PUT 到返回的 uploadUrl。 不要添加 Authorization 标头 — 该 URL 已签名。
3. 随后即可通过第 1 步响应中的 imageUrl 访问该文件。

允许的 extension 值：jpg、jpeg、png、gif、webp、mp4、webm、mov、 avi、mp3、wav、ogg、m4a、aac、flac。

POST /user-images 是同一流程的旧版、仅支持图像/视频的变体；建议使用 /user-assets，它还支持音频。

参见 examples/uploads_and_training.md。

6. 自定义 AI 模型（@modelname）

用于人物、物体和风格的训练模型。在任何图像或编辑提示词中添加标签：@john_doe on the beach at sunset。

列表： GET /models — 查询参数 page、limit、sortBy、sortOrder、search、 name、userId、username、class（person | object | style）、type、 description、privacy（public | private | licensed）、systemVersion、 isActive、status。分页信息通过响应标头 X-Total-Count、 X-Current-Page、X-Per-Page 和 X-Total-Pages 返回。

获取单个模型： GET /models/{id}

训练新模型： POST /models — API 支持此功能（Enterprise 计划）。

参数	备注
name	必填。可使用字母数字字符、_ 和 .，最多 50 个字符。此值会成为 @tag。
class	必填。person | style | object
privacy	public | private | licensed
type	可选；省略时自动生成。
trainingDataUrls	1–50 个公共图像 URL。请先通过 /user-assets 上传。
trainingMode	例如 default、slow
settings	例如 ["NO_ADULT_CONTENT", "NO_VIOLENCE"]
description、website、webhookUrl、organizationId	可选。

训练会自动开始。轮询 GET /models/{id}，直到 status 为 available。

管理： PATCH /models/{id}、DELETE /models/{id}、 PUT /models/{id}/thumbnail。

工作流决策树

创建图像 → 从模型表中选择 baseModel + mode → POST /images → 轮询 GET /images/{id} → imageVersions.original。

使用训练好的模型 → 使用 GET /models?class=person 查找名称 → 在提示词中填入 @name → 正常生成。

编辑图像 → 获取源图像（URL、通过 /user-assets 上传，或 LetzAI 完成记录 id） → 使用 mode: "context" 调用 POST /image-edits → 轮询 → generatedImageCompletion.imageVersions.original。

创建视频 → 可选源图像 → 使用 settings.mode = video-* 键调用 POST /videos → 轮询 → videoVersions.original。

放大 → 使用 imageId 或 imageUrl 调用 POST /upscale → 轮询 → imageVersions.original。

训练模型 → 通过 /user-assets 上传图像 → 使用 trainingDataUrls 调用 POST /models → 轮询 GET /models/{id}，直到状态变为 available。

状态轮询

每个生成端点都是异步的：POST 返回一个 id，然后轮询对应的 GET，直到状态变为终止状态。

资源	状态
图像	new · generating · ready · failed · interrupted · not_allowed · hidden
视频	new · generating · ready · saved · failed · interrupted
图像编辑	new · generating · ready · saved · failed · interrupted
放大	new · generating · ready · failed
模型	new · pending · training · finished · available · failed

没有 "in progress" 状态——正在处理的任务会报告 generating。将 ready 和 saved 视为成功；将 failed、interrupted 和 not_allowed 视为终止 失败。响应还包含 progress（0–100），并且在生成期间包含 base64 previewImage。

建议的间隔：图像／编辑／放大为 3 s，视频为 2–3 s。生产工作负载可使用 webhookUrl 代替轮询。

完整实现请参阅 examples/polling_pattern.md。

错误处理

状态	含义	解决方法
400	参数无效，或请求正文中包含未知字段	检查取值范围，并删除架构中未定义的字段
401	缺少密钥、密钥无效，或不是 organizationId 的成员	检查 Authorization 标头
402	点数不足	前往 letz.ai/subscription 充值
404	未找到资源，或使用了私有 API 路由	检查 id，以及 api.letz.ai 上是否存在该路径
429	请求受到速率限制	逐步延长重试间隔
500	服务器错误	采用退避策略重试

限制

• 所有生成都是异步的——请轮询或使用 Webhook。
• 视频按模型计费；逐秒计费的模型在 1080p/4K 下可能费用较高。
• mode 的取值因模型而异；不支持的档位会回退到模型默认值。
• Seedance 2.0 Enterprise 需要使用者是 organizationId 的成员。
• API 访问需要付费订阅。

快速参考：API 端点

端点	方法	用途
/images	POST	创建图像
/images	GET	列出 / 筛选图像
/images/{id}	GET	图像状态 + URL
/images/{id}/interruption	PUT	停止生成
/images/{id}/privacy	PUT	{ privacy: "public" | "private" | "licensed" }
/images/{id}/prompt-privacy	PUT	隐藏 / 公开显示提示词
/image-edits	POST	创建编辑
/image-edits	GET	列出编辑
/image-edits/{id}	GET	编辑状态 + URL
/image-edits/{imageCompletionId}/mask	GET	获取旧版局部重绘使用的蒙版
/videos	POST	创建视频
/videos	GET	列出视频
/videos/{id}	GET	视频状态 + URL
/videos/{id}/privacy	PUT	更改视频隐私设置
/videos/{id}/prompt-privacy	PUT	隐藏 / 公开显示提示词
/upscale	POST	创建放大任务
/upscale	GET	列出放大任务
/upscale/{id}	GET	放大任务状态 + URL
/upscale/{id}	DELETE	删除放大任务
/models	GET	列出模型
/models	POST	训练新模型
/models/{id}	GET	模型详情
/models/{id}	PATCH	更新模型元数据
/models/{id}	DELETE	删除模型
/models/{id}/thumbnail	PUT	设置缩略图
/user-assets	POST	获取预签名上传 URL（图像 / 视频 / 音频）
/user-assets	GET	列出上传内容
/user-assets/{id}	GET / PATCH / DELETE	管理上传内容
/user-images	POST / GET	旧版仅支持图像和视频的上传流程
/user-images/{id}	GET / DELETE	管理旧版上传内容
/realtime/health	GET	实时网关运行状况

不属于公共 API 的端点（私有 Web 应用路由——这些端点会返回 404）：/upscales、 /video-edits、/image_completions、PUT /videos/{id}/interruption。

关键响应字段

• 图像 / 放大任务： imageVersions.original、imageVersions["1920x1920"]、imageVersions["640x640"]
• 编辑： generatedImageCompletion.imageVersions.original（源图像位于 originalImageCompletion 中）
• 视频： videoVersions.original
• 进行中： progress（0–100）、previewImage（base64）、失败时的 statusDetail

模型目录

如需查看 LetzAI 当前支持的 AI 模型列表（包括其参数和令牌成本），请始终阅读 models.json 文件：

模型目录（实时）： letz.ai/docs/models.json

其他资源

• Swagger / OpenAPI： api.letz.ai/doc · /doc-json
• 开发者文档： letz.ai/docs/api
• 模型目录（实时）： letz.ai/docs/models.json
• 详细参考： api_reference.md
• 代码示例： examples/
• LetzAI 平台所有功能的文档： letz.ai/docs