兼容调用
聊天接口采用 OpenAI 兼容的消息结构，支持普通与流式响应。
User Guide
平台介绍
闽都睿词为应用提供统一的大模型调用入口。公开文档覆盖聊天推理、媒体生成与模型目录，帮助开发者用稳定、清晰的合同完成服务端集成。
模型目录
通过公开模型列表和详情选择模型，并确认能力与参数。
安全接入
API Key 仅保存在服务端环境变量中，不应写入浏览器代码或仓库。
Get Started
快速上手
- 1
准备 API Key
在控制台创建并启用 API Key，然后仅通过服务端环境变量 AIFLOW_API_KEY 使用。
- 2
选择模型
先查询模型列表，再通过模型详情确认模型 ID、能力与可用参数。
- 3
发起聊天请求
向聊天补全接口提交 messages，可选指定 model；需要增量输出时设置 stream=true。
- 4
处理失败与限流
根据 HTTP 状态和请求 ID 排障；收到 429 时采用带抖动的指数退避。
示例中的 Base URL、API Key 和模型 ID 均为占位值。不要将真实密钥写入前端代码、URL、日志或版本控制。
Security
认证
公开推理接口使用 API Key。请在服务端请求的 Authorization 请求头中传入 Bearer <API_KEY>，不要把真实密钥放入浏览器、URL、日志或仓库。
认证失败检查
收到 HTTP 401 时，检查 Bearer 格式、Key 状态与有效期。文档中的 Key 均为占位符，页面不会读取或保存真实密钥。
Errors
错误码
客户端应同时记录 HTTP 状态和服务端返回的请求 ID，用于安全排障；不要记录请求中的密钥或敏感内容。
- HTTP 400
- 请求格式或参数不符合公开合同，请修正后重试。
- HTTP 401
- API Key 缺失、无效、停用或已过期。
- HTTP 429
- 请求超过当前限制，请遵循重试提示并采用带抖动的指数退避。
- HTTP 500
- 服务暂时不可用，请保留请求 ID，稍后重试或联系支持。
Help
常见问题
为什么返回 401？
确认 Authorization 使用 Bearer 方案，并检查 API Key 是否存在、启用且未过期。
普通响应和流式响应有什么区别？
普通响应在推理完成后一次返回；流式响应通过 SSE 持续发送增量内容。
收到 429 应如何处理？
降低并发或请求频率，并使用带抖动的指数退避；不要立即高频重试。
为什么查不到模型？
确认模型 ID、筛选条件和分页参数；模型目录仅返回当前已发布模型。
可以在浏览器中保存 API Key 吗？
不建议。生产应用应由自己的服务端持有密钥并代理业务请求。
限速与 429 错误
收到 HTTP 429 时，请保留请求 ID，遵循服务端返回的重试提示，并采用带抖动的指数退避。模型专属 RPM、TPM 或并发限制以模型详情和实际响应为准。
Reference
API Reference
公开边界固定为以下 9 个接口。未列出的接口不会进入导航、搜索、示例或在线调试。
API Reference · Media
生成图片
使用已发布的图像模型创建图片。响应 data 中的 url 或 b64_json 可用于展示；expires_at 表示结果的 24 小时有效期。
请求参数
| 参数 | 位置 | 类型 | 说明 |
|---|---|---|---|
| 该接口没有路径或查询参数，请查看请求体说明。 | |||
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 图片生成模型编码 |
| prompt | string | 是 | 图片生成提示词，最多32000个字符 |
| image | array<string> | 否 | 参考图片URL或Base64数据，最多10张；模型支持时生效 |
| n | integer | 否 | 生成图片数量，范围1至15，默认为1 |
| size | string | 否 | 输出图片尺寸，支持auto、2K、3K、4K或宽x高，默认为1024x1024 |
| quality | string | 否 | 输出图片质量，支持auto、standard、hd、low、medium、high，默认为auto |
| response_format | string | 否 | 响应图片格式，支持b64_json或url，默认为b64_json |
| sequential_image_generation | string | 否 | 组图生成模式，支持disabled或auto |
| sequential_image_generation_options | object | 否 | 组图生成配置 |
| sequential_image_generation_options.max_images | integer | 否 | 组图模式最多生成的图片数量，范围1至15 |
| output_format | string | 否 | 图片文件格式，支持jpeg或png |
| watermark | boolean | 否 | 是否添加AI生成水印 |
| negative_prompt | string | 否 | 模型支持时可选 |
响应数据字段
字段来自 HTTP 200 响应 Schema；嵌套对象使用点号表示，数组元素使用 [] 表示。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| created | integer | 否 | 图片生成时间，Unix时间戳（秒） |
| expires_at | integer | 否 | 图片结果过期时间，Unix时间戳（秒） |
| data | array<object> | 否 | 生成图片结果列表 |
| data[].b64_json | string | 否 | 图片Base64编码；response_format为b64_json时返回 |
| data[].url | string | 否 | 图片访问地址；response_format为url时返回 |
| data[].revised_prompt | string | 否 | 模型优化后的提示词；模型支持时返回 |
响应状态
- HTTP 200
- 生成成功，结果有效期由 expires_at 返回
- HTTP 400
- 请求参数错误
- HTTP 401
- API Key 无效或缺失
- HTTP 429
- 请求超过限流
API Reference · Media
创建视频生成任务
multipart/form-data 异步视频任务；input_reference 为可选单张参考图。状态依次可能为 queued、in_progress、completed、failed 或 cancelled。
请求参数
| 参数 | 位置 | 类型 | 说明 |
|---|---|---|---|
| 该接口没有路径或查询参数，请查看请求体说明。 | |||
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 视频生成模型编码 |
| prompt | string | 是 | 视频生成提示词，最多32000个字符 |
| seconds | integer | 否 | 视频时长，支持4至10秒，默认为5秒 |
| size | string | 否 | 视频画面尺寸，支持720x1280、1280x720、1024x1792、1792x1024，默认为720x1280 |
| video_ratio | string | 否 | 视频宽高比，支持adaptive、21:9、16:9、4:3、1:1、3:4、9:16 |
| video_resolution | string | 否 | 视频分辨率，支持480p或720p，默认为720p |
| video_output_format | string | 否 | 视频文件格式，支持mp4或mov，默认为mp4 |
| video_duration_mode | string | 否 | 视频时长模式，支持fixed或adaptive，默认为fixed |
| generate_audio | boolean | 否 | 是否生成音频，默认为true |
| watermark | boolean | 否 | 是否添加AI生成水印，默认为false |
| generation_mode | string | 否 | 生成模式：text_to_video、first_frame、first_last_frame、reference_images或multimodal_reference |
| first_frame_image | string | 否 | 首帧参考图片URL或Base64数据 |
| last_frame_image | string | 否 | 尾帧参考图片URL或Base64数据 |
| reference_images | array<string> | 否 | 参考图片URL或Base64数据列表，最多10项 |
| reference_videos | array<string> | 否 | 参考视频URL或Base64数据列表，最多3项 |
| reference_audios | array<string> | 否 | 参考音频URL或Base64数据列表，最多3项 |
| input_reference | string (binary) | 否 | 可选的单张参考图片文件，最大20MB |
响应数据字段
字段来自 HTTP 200 响应 Schema；嵌套对象使用点号表示，数组元素使用 [] 表示。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 否 | 视频任务ID |
| object | string | 否 | 对象类型，固定为video |
| model | string | 否 | 视频生成模型编码 |
| status | string | 否 | 任务状态：queued、in_progress、completed、failed或cancelled |
| progress | integer | 否 | 任务进度百分比，范围0至100 |
| created_at | integer | 否 | 任务创建时间，Unix时间戳（秒） |
| completed_at | integer | 否 | 任务完成时间，Unix时间戳（秒） |
| expires_at | integer | 否 | 视频结果过期时间，Unix时间戳（秒） |
| error | object | 否 | 任务失败信息；任务成功时为null |
| error.code | string | 否 | 错误编码 |
| error.message | string | 否 | 错误信息 |
| prompt | string | 否 | 视频生成提示词 |
| seconds | string | 否 | 视频时长，单位秒 |
| size | string | 否 | 视频画面尺寸 |
| video_ratio | string | 否 | 视频宽高比 |
| video_resolution | string | 否 | 视频分辨率 |
| video_output_format | string | 否 | 视频文件格式 |
| video_duration_mode | string | 否 | 视频时长模式 |
| generate_audio | boolean | 否 | 是否生成音频 |
| generation_mode | string | 否 | 视频生成模式 |
| video_url | string | 否 | 视频访问地址；任务完成且结果未过期时返回 |
响应状态
- HTTP 200
- 任务已创建，返回 id 与 status
- HTTP 400
- 请求参数错误
- HTTP 401
- API Key 无效或缺失
- HTTP 429
- 请求超过限流
API Reference · Media
查询视频任务
轮询任务状态和 progress。completed 时可读取内容；expires_at 表示结果的 24 小时有效期。
请求参数
| 参数 | 位置 | 类型 | 说明 |
|---|---|---|---|
| video_id* | path | string | 视频任务 ID |
响应数据字段
字段来自 HTTP 200 响应 Schema；嵌套对象使用点号表示，数组元素使用 [] 表示。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 否 | 视频任务ID |
| object | string | 否 | 对象类型，固定为video |
| model | string | 否 | 视频生成模型编码 |
| status | string | 否 | 任务状态：queued、in_progress、completed、failed或cancelled |
| progress | integer | 否 | 任务进度百分比，范围0至100 |
| created_at | integer | 否 | 任务创建时间，Unix时间戳（秒） |
| completed_at | integer | 否 | 任务完成时间，Unix时间戳（秒） |
| expires_at | integer | 否 | 视频结果过期时间，Unix时间戳（秒） |
| error | object | 否 | 任务失败信息；任务成功时为null |
| error.code | string | 否 | 错误编码 |
| error.message | string | 否 | 错误信息 |
| prompt | string | 否 | 视频生成提示词 |
| seconds | string | 否 | 视频时长，单位秒 |
| size | string | 否 | 视频画面尺寸 |
| video_ratio | string | 否 | 视频宽高比 |
| video_resolution | string | 否 | 视频分辨率 |
| video_output_format | string | 否 | 视频文件格式 |
| video_duration_mode | string | 否 | 视频时长模式 |
| generate_audio | boolean | 否 | 是否生成音频 |
| generation_mode | string | 否 | 视频生成模式 |
| video_url | string | 否 | 视频访问地址；任务完成且结果未过期时返回 |
响应状态
- HTTP 200
- 任务状态
- HTTP 401
- API Key 无效或缺失
- HTTP 404
- 任务不存在或已过期
API Reference · Media
下载视频内容
仅在任务 completed 后下载；视频结果自 expires_at 起失效，最长保存 24 小时。
请求参数
| 参数 | 位置 | 类型 | 说明 |
|---|---|---|---|
| video_id* | path | string | 视频任务 ID |
响应状态
- HTTP 200
- 视频二进制内容
- HTTP 401
- API Key 无效或缺失
- HTTP 404
- 任务不存在、未完成或已过期
API Reference · Media
创建豆包官方格式视频任务
采用火山豆包官方 content/type/role 请求结构创建异步视频任务。
请求参数
| 参数 | 位置 | 类型 | 说明 |
|---|---|---|---|
| 该接口没有路径或查询参数，请查看请求体说明。 | |||
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 视频生成模型编码，例如 doubao-seedance-2-0-260128 |
| prompt | string | 否 | 文生视频或首帧图生视频提示词；其他模式可放入 content 的 text 项 |
| content | array<object> | 否 | 文本、图片、视频或音频参考内容 |
| content[].type | string | 是 | 内容类型：text、image_url、video_url 或 audio_url |
| content[].text | string | 否 | type 为 text 时的提示词 |
| content[].image_url.url | string | 否 | HTTP 或 HTTPS 图片地址 |
| content[].video_url.url | string | 否 | HTTP 或 HTTPS 视频地址 |
| content[].audio_url.url | string | 否 | HTTP 或 HTTPS 音频地址 |
| content[].role | string | 否 | first_frame、last_frame、reference_image、reference_video 或 reference_audio |
| generate_audio | boolean | 否 | 是否生成同步音频，默认为 true |
| ratio | string | 否 | 视频比例：adaptive、21:9、16:9、4:3、1:1、3:4 或 9:16 |
| duration | integer | 否 | 视频时长，支持 4 至 15 秒，默认为 5 秒 |
| resolution | string | 否 | 视频分辨率：480p、720p 或 1080p，默认为 480p |
| watermark | boolean | 否 | 是否添加 AI 生成水印，默认为 false |
响应数据字段
字段来自 HTTP 200 响应 Schema；嵌套对象使用点号表示，数组元素使用 [] 表示。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 否 | 视频任务 ID |
响应状态
- HTTP 200
- 任务已创建，返回 id
- HTTP 400
- 请求参数错误
- HTTP 401
- API Key 无效或缺失
- HTTP 429
- 请求超过限流
API Reference · Media
查询豆包官方格式视频任务
返回 queued、running、succeeded 或 failed 状态；成功时 content.video_url 包含视频地址。
请求参数
| 参数 | 位置 | 类型 | 说明 |
|---|---|---|---|
| task_id* | path | string | 视频任务 ID |
响应数据字段
字段来自 HTTP 200 响应 Schema；嵌套对象使用点号表示，数组元素使用 [] 表示。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 否 | 视频任务 ID |
| model | string | 否 | 视频生成模型编码 |
| status | string | 否 | 任务状态：queued、running、succeeded 或 failed |
| content.video_url | string | 否 | 任务成功后返回的视频访问地址 |
| usage.completion_tokens | integer | 否 | 视频生成输出 Token 数 |
| usage.total_tokens | integer | 否 | 视频生成总 Token 数 |
| created_at | integer | 否 | 任务创建时间，Unix 时间戳（秒） |
| updated_at | integer | 否 | 任务更新时间，Unix 时间戳（秒） |
| seed | integer | 否 | 上游返回的随机种子；可用时返回 |
| resolution | string | 否 | 视频分辨率 |
| ratio | string | 否 | 视频宽高比 |
| duration | integer | 否 | 视频时长，单位秒 |
| framespersecond | integer | 否 | 视频帧率；可用时返回 |
| execution_expires_after | integer | 否 | 任务结果有效时长，单位秒 |
| generate_audio | boolean | 否 | 是否生成同步音频 |
| tools | array<object> | 否 | 上游工具调用信息 |
| error.code | string | 否 | 失败错误码 |
| error.message | string | 否 | 失败原因 |
响应状态
- HTTP 200
- 视频任务状态
- HTTP 401
- API Key 无效或缺失
- HTTP 404
- 任务不存在或已过期
API Reference · Chat
创建聊天补全
使用 OpenAI 兼容格式发起模型推理；stream=true 时返回 SSE 流。
请求参数
| 参数 | 位置 | 类型 | 说明 |
|---|---|---|---|
| 该接口没有路径或查询参数，请查看请求体说明。 | |||
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 否 | 模型编码；不传时使用 API Key 绑定的默认模型 |
| messages | array<object> | 是 | 按顺序排列的对话消息列表，至少包含一条消息 |
| messages[].role | string | 否 | 消息角色，例如 system、user、assistant 或 tool |
| messages[].content | string | 否 | 消息正文 |
| messages[].reasoning_content | string | 否 | 推理内容；通常仅在兼容模型返回后续上下文时使用 |
| messages[].name | string | 否 | 消息发送者名称 |
| temperature | number | 否 | 采样温度；有效范围以所选模型参数为准 |
| top_p | number | 否 | 核采样概率；有效范围以所选模型参数为准 |
| max_tokens | integer | 否 | 本次生成的最大 Token 数；有效范围以所选模型参数为准 |
| stream | boolean | 否 | 是否使用 SSE 流式响应；stream=true 时返回 SSE，未传或为 false 时返回普通 JSON |
响应数据字段
嵌套对象使用点号表示，数组元素使用 [] 表示。stream=true 时返回 SSE；未传或为 false 时返回普通 JSON。流式响应的每个 data: 数据块为下列 JSON 结构，并以 data: [DONE] 结束。
在线调试 metadata 事件
在线调试会附加请求ID、执行状态和实际模型，事件格式如下：
event: metadata
data: {"requestId":"req_xxx","status":"SUCCESS","actualModel":"deepseek-v3.1"}| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 否 | 聊天补全响应 ID |
| object | string | 否 | 对象类型，流式响应通常为 chat.completion.chunk |
| created | integer | 否 | 响应创建时间，Unix 时间戳（秒） |
| model | string | 否 | 实际响应使用的模型编码 |
| requestId | string | 否 | 在线调试metadata事件中的请求ID，用于问题排查 |
| status | string | 否 | 在线调试metadata事件中的执行状态，例如PROCESSING或SUCCESS |
| actualModel | string | 否 | 在线调试实际调用的模型编码 |
响应状态
- HTTP 200
- 请求成功
- HTTP 400
- 请求参数错误
- HTTP 401
- API Key 无效或缺失
- HTTP 429
- 请求超过限流
- HTTP 500
- 服务暂时不可用
API Reference · Models
获取模型列表
分页查询当前已发布的模型，可按模型类型、厂商和推荐场景筛选，并按价格、响应速度或可用性排序。
请求参数
| 参数 | 位置 | 类型 | 说明 |
|---|---|---|---|
| current | query | integer (int32) | 页码，从 1 开始 |
| size | query | integer (int32) | 每页条数 |
| modelType | query | string | 模型类型，例如 llm |
| providerId | query | integer (int64) | 厂商 ID，例如 1004 |
| scenarioCodes | query | array<string> | 推荐场景编码，例如 coding_assistant |
| sortBy | query | string | 排序方式：价格最低（price_asc）、响应最快（speed）、可用性最高（availability） |
响应状态
- HTTP 200
- 请求成功
- HTTP 400
- 请求参数错误
- HTTP 500
- 服务暂时不可用
API Reference · Models
获取模型详情
根据模型 ID 查询已发布模型的能力与调用参数。
请求参数
| 参数 | 位置 | 类型 | 说明 |
|---|---|---|---|
| id* | path | integer (int64) | 模型 ID |
响应状态
- HTTP 200
- 请求成功
- HTTP 400
- 模型 ID 格式错误
- HTTP 500
- 服务暂时不可用