#常见问题

#API 错误与重试速查

先区分“创建请求失败”“查询失败”和“任务状态为 failed”。它们的下一步不同： 查询可按规则退避重试，创建是否已受理需要先核对任务记录；任务失败则先读取错误原因。

错误结构示例，字段与文案以实际响应为准：

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: EXAMPLE_REQUEST_ID)",
    "type": "new_api_error"
  }
}

响应不一定总是 JSON。先检查 HTTP 状态和 Content-Type，再解析错误；不要将 HTML 错误页当作成功结果。 排查时保留任务 ID、请求时间、模型 ID、HTTP 状态与响应头 X-Oneapi-Request-Id。 不要公开 API Key、签名素材 URL 或私人素材地址。实际计费与失败退款以账户用量记录和模型规则为准。

#completed 后应该怎样下载？

读取查询响应中的 url，原样用于播放或下载；不要自行拼接文件路径，也不要再请求 /v1/videos/{id}/content。 媒体请求不附带 THQ API Key。若结果暂时无可用 URL，继续查询原任务，不创建新任务。 下载前检查最终响应状态与 Content-Type，详见任务查询与结果下载。

#processing、进度不变或等待超时代表失败吗？

不代表。queued、in_progress、processing 都是等待中的状态，progress 只作提示。 每隔 5–10 秒继续查询；总等待时间与单次请求超时分开设置。本地等待上限到期后保留任务 ID，之后继续查询。 只有明确失败状态才按任务错误处理，不要因为处理较久就重新提交。

#多图或音视频参考为什么不生效？

多图使用真正的 JSON images 数组，音视频分别使用 reference_videos、reference_audios 数组， 并确认模型支持这些输入。不要重复 JSON 键、把数组编码为字符串，或同时混用多种单图与多图别名。 素材需要可读取的 HTTPS 直链，不能使用本地路径、blob: 地址或需要登录的页面。 multipart 只提交一张 input_reference 文件；多素材改用 URL 数组。 完整示例见参考图片、视频与音频。

#size 与 resolution 怎么填写？

size 直接填写画面比例，例如 "16:9"；resolution 单独填写清晰度，例如 "720p"。 比例不等于固定像素尺寸，两个字段的可选范围都由模型决定。新接入不把比例换算成像素，也不改用 ratio 字段。 seconds 使用字符串，完整说明见请求参数。

#文本或图片必须调用模型吗？

不用。文本节点可选择手动输入，图片节点可上传图片，直接作为后续生成的参考。 需要 AI 辅助时才选择对应模型；图片也可以独立生成或基于参考图编辑。

#以前的图像创作入口在哪里？

官网统一使用 new.thqllm.com/studio 介绍文本、图像与视频创作。 图片提示词、生成、参考图编辑和版本选择在文本与图片流程中说明。 旧官网图像文档地址会跳转到新的工作台文档。

#为什么外接文本或图片模型列表为空？

确认 URL 是带 API 前缀的完整 HTTPS 基址，例如 THQ API 的 https://api.thqllm.com/v1，再检查自己的 Key。 保存并重新获取模型。服务需要提供兼容的 /models 接口，节点所选模型也要支持对应文本、图片生成或编辑接口。

#文本返回闲聊、空内容或 invalid JSON 怎么办？

确认所选模型能通过外接服务输出普通文本。检查服务返回的 Content-Type 和脱敏响应，区分正常 JSON、流式事件、HTML 错误页和空响应。 不要直接把网页、控制台地址或完整 /chat/completions 路径当作 Base URL。 结果可在文本编辑区确认后再用于生图或视频；问题持续时提供模型 ID、URL 和脱敏错误，勿发送 Key。

#图片生成成功，但参考图编辑失败？

纯生图与参考图编辑使用不同接口，列出同一个模型不代表服务支持两者。 确认图片服务支持 /images/edits、所选模型支持参考图，并检查输入数量和图片格式。 多参考图失败时，先用一张有效图片验证，再扩展组合。

#为什么视频分组不可用或没有模型？

工作台只能使用当前账号可选择的分组。重新选择有效分组并刷新模型列表，检查渠道是否启用、目标模型是否属于该分组。 API 调用还需检查 Key 的分组与模型限制。管理员能够看到模型，不代表当前用户或 Key 可以调用它。

#为什么时长或分辨率报错？

参数取决于实际渠道。相似别名可能分别使用固定时长、自由时长或不同分辨率。 按模型弹窗与渠道说明填写，不要用旧模型的 5/10/15 秒规则限制所有新模型。 API 的 seconds 必须是字符串；出现 “cannot unmarshal number ... seconds ... string” 时，把 5 改成 "5"。

#出现 522、超时或没有使用日志怎么办？

先保存错误和请求时间，查看任务记录与请求状态。视频任务可能排队或仍在提交，不能仅凭超时判定失败。 有任务 ID 时查询原任务；状态不明时先确认是否已创建任务，再决定重试，避免重复计费。 一直没有任务或日志时，检查权限、模型路由和请求是否被网关拒绝，并提供脱敏信息排查。

#连线之后为什么参考没有生效？

检查连线方向、素材是否已有可用结果，以及连接选用的版本。 手动文本和上传图片可以直接传入；需要生成的前置节点应先成功。 区分首帧、参考图、参考视频和视频延长；连接正确也仍需所选视频渠道支持该能力。 切换模型或调整渠道后，重新检查请求预览与引用素材。

#多个版本、AI 最终视频和本地成片是什么关系？

先为每个镜头选择想使用的版本。本地合成按顺序拼接这些已有片段，不新增视频模型调用。 AI 续创最终视频会另外生成一个新视频并产生计费任务，模型可能重新组织参考内容。

#换设备为什么找不到项目？

账号保存外接服务配置，项目与素材保存在当前浏览器，两者保存方式不同。 目前项目不自动跨设备同步。换设备前导出包含素材的项目 ZIP，再在另一设备导入；重要结果也建议单独下载。