AI 接口帮助中心

准备工作与密钥安全

1. 请先查看账号的接口配置，准备接口地址、模型编码、API Key（调用密钥）和计费说明。找不到配置或不确定是否开通时，请联系松松云客服。
2. 仅在服务端环境变量或密钥管理系统中保存密钥，配置用量上限和访问权限。
3. 先用短提示词、小尺寸或短时长验证请求，核对返回结果与用量，再接入业务。
4. 日志仅保留脱敏错误、状态和请求编号；不要记录完整密钥、认证链接或私人素材。

疑似泄露时立即停用或轮换密钥，并排查异常调用。网页和小程序应通过你自己的服务器调用接口，不要把密钥放进用户能看到的页面代码中。

OpenAI 对话 API

适用于使用 Chat Completions 协议的文本模型。请求：POST {网关地址}/chat/completions。请求头使用 Authorization: Bearer {API_KEY}、Content-Type: application/json；流式调用增加 Accept: text/event-stream。

请求字段与示例

model 和 messages 必填。消息由 role 与 content 组成，文本角色包括 system、user、assistant；多轮对话需按顺序传入历史。stream 控制流式输出；temperature、top_p、max_tokens 及其他参数只能在模型支持时使用。

{
  "model": "MODEL_ID",
  "messages": [
    {"role": "system", "content": "回答简洁、准确。"},
    {"role": "user", "content": "为一份产品说明拟定三个标题。"}
  ],
  "stream": true
}

读取结果

按 SSE 事件拼接 choices[].delta.content，遇 data: [DONE] 结束。不能把每个网络数据块当成一条完整事件；应缓存未完成的行与事件。finish_reason 表示结束原因，usage 为用量信息；部分模型另有 reasoning_content，不能与正文混合解析。

排查无输出时先检查是否正确消费增量事件，再检查模型权限与输出限制。不同模型并不保证支持完全相同的参数。

Responses API

请求：POST {网关地址}/responses，使用 Bearer 鉴权和 JSON。它与 Chat Completions 的字段、流事件不同，不应仅替换接口路径而保留旧解析器。

必填 model、input；下方示例将 input 写成消息数组。可按模型能力设置 stream、temperature、top_p、max_output_tokens，注意输出上限字段不是 max_tokens。

{
  "model": "MODEL_ID",
  "input": [{"role": "user", "content": "把这句话改为正式语气：明天请早点到。"}],
  "stream": true,
  "max_output_tokens": 512
}

读取 response.output_text.delta 事件中的 delta 文本，并在 response.completed 中读取 response.usage。中断或错误事件不能当成成功完成。工具调用、会话保存和多模态能力需另行确认，不能从协议名称推断网关支持。

Anthropic API

请求：POST {网关地址}/messages。请求头为 x-api-key: {API_KEY}、anthropic-version: 2023-06-01、Content-Type: application/json；流式响应使用 SSE。

必填 model、messages、max_tokens。messages 使用 user 或 assistant；系统提示放在顶层 system，不放入 messages。请把示例的 MODEL_ID 换成账号已开通的 Claude 模型编码，否则请求会失败。

{
  "model": "MODEL_ID",
  "system": "用清晰的步骤回答。",
  "messages": [{"role": "user", "content": "整理一份文档发布检查清单。"}],
  "max_tokens": 1024,
  "stream": true
}

在 content_block_delta 事件中读取 delta.text；输出用量可能由 message_delta 返回。分别处理内容块开始、结束与 message_stop，不使用 OpenAI 的 choices 解析器。temperature、top_p 和扩展能力以所选模型为准。

通用生图 API

文生图：POST {网关地址}/images/generations；图生图：POST {网关地址}/images/edits。下方示例按 JSON 格式提交，并在请求头中携带密钥。不同模型的图片上传方式可能不同，接入时请核对已开通接口的说明。

文生图必填 model、prompt；n 为张数，size 为尺寸，如 1024x1024，具体可用值由模型决定。

{
  "model": "MODEL_ID",
  "prompt": "简洁的蓝白色云计算概念插画，无文字、无商标",
  "n": 1,
  "size": "1024x1024"
}

图生图在对应请求中增加 image 地址数组，例如 "image": ["{参考图公网地址}"]，同时保留模型及编辑描述。地址必须在执行期间可读，不能依赖本地路径或浏览器登录。

结果与保存

优先根据实际响应读取 data[].url；部分模型返回 data[].b64_json。下载结果前验证类型和大小，图片链接可能有有效期，请及时存入有权限控制的存储。编辑效果、图片数量和尺寸不是所有模型通用能力。

DashScope 生图 API

请求：POST {网关地址}/dashscope/api/v1/services/aigc/multimodal-generation/generation，使用 Bearer 鉴权和 JSON。

必填 model、input.messages；消息 role 使用 user，content 是内容项数组。文本项为 text，参考图项为 image。生成参数放入 parameters，尺寸使用星号分隔，例如 1024*1024，而不是 1024x1024。

{
  "model": "MODEL_ID",
  "input": {"messages": [{
    "role": "user",
    "content": [{"text": "设计一张浅蓝色办公空间概念图，无品牌标识"}]
  }]},
  "parameters": {"n": 1, "size": "1024*1024"}
}

图生图可在 content 的文本项前加入 {"image":"{参考图公网地址}"}，前提是模型支持参考图。返回图片可能在 output.results[].url、output.choices[].message.content 或 data[]；按实际结构解析，不能假定只存在一种返回形式。

豆包 Seedream 生图 API

请求：POST {网关地址}/doubao/api/v3/images/generations，使用 Bearer 鉴权和 JSON。下面介绍根据文字生成图片的用法。如需编辑图片或一次生成多张，请先查看所选模型是否支持。

必填 model、prompt；size 是模型支持的尺寸，watermark 为水印选项。参数默认值与尺寸范围不跨模型通用。

{
  "model": "MODEL_ID",
  "prompt": "暖色调的原创咖啡杯静物，自然光，纯色背景",
  "size": "2048x2048",
  "watermark": true
}

从 data[].url 获取生成图片，并及时转存。提示词应明确主体、构图、光线和风格；不要通过参数承诺文字准确度或固定生成效果。是否能关闭水印、是否需要补充 AI 标识，须遵守平台规则和适用法律。

视频生成 HappyHorse API

创建：POST {网关地址}/happyhorse/api/v1/services/aigc/video-generation/video-synthesis；查询：GET {网关地址}/happyhorse/api/v1/tasks/{task_id}。两者使用 Bearer 鉴权，创建请求为 JSON。

model、input.prompt 必填；parameters 可包含 resolution 和 duration，分辨率写为 720P 等大写 P 格式。图生视频可在 input.media 中增加 type 与 url，首帧用 first_frame；参考视频支持情况以模型为准。

{
  "model": "MODEL_ID",
  "input": {"prompt": "镜头缓慢靠近一片清晨的树林，阳光穿过树叶"},
  "parameters": {"resolution": "720P", "duration": 5}
}

异步执行

1. 保存创建响应的 output.task_id，不重复提交同一生成请求。
2. 每 3～5 秒查询一次，并设置总等待上限；遇到限流适当退避。
3. submitted、queued 表示等待，running 表示执行；succeeded 后读取 output.video_url。
4. failed 时查看 output.message 并停止轮询。

请求已受理不等于生成成功。创建超时可能已经产生任务，先确认任务记录再决定是否重试，避免重复费用。

视频生成 Seedance API

创建：POST {网关地址}/seedance/api/v3/contents/generations/tasks；查询：GET {网关地址}/seedance/api/v3/contents/generations/tasks/{id}。请求头使用 Bearer 鉴权和 JSON。

必填 model 和 content 数组。文本项为 type=text；图片、视频、音频项分别使用 image_url、video_url、audio_url 及同名嵌套对象。resolution、ratio、duration、generate_audio、return_last_frame 等参数仅在模型支持时设置。

{
  "model": "MODEL_ID",
  "content": [{"type": "text", "text": "一只原创纸艺小鸟从桌面起飞，镜头平稳跟随"}],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "watermark": true
}

参考素材与任务管理

首帧项可写为 {"type":"image_url","image_url":{"url":"{参考图公网地址}"},"role":"first_frame"}。尾帧角色为 last_frame，参考图为 reference_image；视频可用 reference_video 或 extend_video，音频参考按模型要求组合。图片、音视频的尺寸、体积、时长和数量限制须核对单模型能力。

保存创建响应 id，再读取查询响应 status。queued、running 继续等待；succeeded 后读取 content.video_url；failed、cancelled、expired 是终止状态。失败信息在 error.code 与 error.message。结果地址可能过期，应及时转存。

任务列表使用 GET {网关地址}/seedance/api/v3/contents/generations/tasks，可按账号接口支持的 page_num、page_size 与 filter.status 等参数筛选；取消或删除使用同一路径附加 /{id} 的 DELETE。执行中的任务可能不能取消；删除前确认记录及费用影响。

视频编辑、延长、音频、样片、联网工具和离线档位不是每个模型都支持。Webhook 回调应校验可信来源，并再次查询任务确认结果，不能仅信任回调中的下载地址。

Seedance 素材库 API

素材库用于管理可重复引用的图片、视频和音频。流程为：建立组 → 添加素材 → 等待就绪 → 使用 asset:// 引用。真人素材必须取得本人授权并完成要求的认证，不能用虚拟组绕过真人验证。

接口路径与身份区分

管理接口：POST {网关域名}/v1/seedance?Action={动作名}&Version=2024-01-01，使用 Bearer 鉴权及 JSON。此处 {网关域名} 不含 /v1，不要重复拼接。ProjectName 是项目名称，请按账号配置填写；示例中的 default 只用于演示，不确定时请先咨询客服。

• GroupId 是素材组标识，以字符串原样保存。
• 素材 Id 通常为 asset-*，用于 GetAsset 及 asset:// 引用。
• BytedToken 为真人认证会话标识，不是 API Key。
• 视频任务 id 与上述标识不同，应单独保存。

虚拟组与真人认证

虚拟组使用 CreateAssetGroup，提交 Name、Description 和 GroupType=AIGC。真人使用 CreateVisualValidateSession，保存返回的 Id、BytedToken、H5Link；本人通过原始 H5Link 完成验证，不自行拼接链接。通过 GetVisualValidateResult 并传 BytedToken 查询，取得非空 Result.GroupId 后才添加真人素材。

查询真人认证结果时，HTTP 404 可能表示尚未完成，也可能表示认证标识无效或无权查看，请结合返回的错误信息判断。应设置有限轮询和总超时，不能把所有 404 都当作等待。认证失败或过期的 400 应停止重试。H5Link、token、签名地址均需限制访问并脱敏记录。

添加、查询与引用

{
  "ProjectName": "default",
  "GroupId": "{素材组ID}",
  "URL": "{授权素材公网地址}",
  "AssetType": "Image",
  "Name": "产品参考图"
}

上例提交给 CreateAsset。URL 大小写须保持一致；地址必须能由上游直接读取。保存 Result.Id 后调用 GetAsset，传 Id 查询：Processing 为处理中，Active 才可使用，Failed 查看 Error 并停止轮询。HTTP 200 不代表素材已就绪。

Active 素材引用为 asset://{素材Id}，不可填组 ID、token 或预览地址。使用素材库生成视频时，请核对账号是否支持以下接口： POST {网关域名}/v1/seedance/v3/contents/generations/tasks，查询同一路径附加 /{id}。与上一节的 /seedance/api/v3 路由不同，须确认开通路由并在创建和查询时保持一致。

列表、维护与签名地址

ListAssetGroups、GetAssetGroup 用于查组；ListAssets、GetAsset 用于查素材。列表可使用 PageNumber、PageSize 与 Filter，具体筛选字段按已开通协议配置。UpdateAssetGroup、UpdateAsset 修改名称等信息；DeleteAssetGroup、DeleteAsset 删除资源，执行前确认影响，不视为可撤销操作。

素材接口响应通常包含 ResponseMetadata 与 Result，错误也可能在 ResponseMetadata.Error，不应只解析 error.message。预览 URL 可能省略或过期，重新查询取得新签名地址，不删改签名参数，不假定固定有效期；缺少预览链接不等于 Active 素材失效。

常见错误与接入检查

• 400：核对 JSON、必填字段、参数范围、余额以及认证会话状态，读取具体错误信息。
• 401 / 403：确认 Key、账户权限与模型开通情况，不循环重试认证错误。
• 404：检查路径、模型或资源 ID；只有特定真人认证查询才可能表示等待。
• 429：降低并发并按限流提示退避，轮询也计入请求频率。
• 5xx / 超时：查询可有限重试；创建操作先核实是否受理，避免重复任务或资源。

上线前验证失败状态、断流、轮询超时、签名地址过期、权限不足和费用上限。首次接入建议先做少量测试，确认能拿到结果、费用符合预期，再用于正式业务。