快速开始

适用场景

这部分适合第一次接入心宝 AI 的开发者。建议先读完这里，再进入具体能力页。

接入前准备

获取当前渠道可用的 API Key
确认使用的 Base URL
根据业务能力选择对应接口
为图片或视频输入准备公网可访问的 URL

核心规则

所有接口统一使用 Authorization: Bearer <API_KEY>
请求体统一使用 JSON，建议显式使用 UTF-8
图像生成和视频生成都可能依赖公网图片 URL
异步生图提交通常仍走 :generateContent，但返回值会先给任务 id
视频任务默认是异步流程，需要提交任务后轮询结果

第一个请求

推荐先从图像生成能力开始验证链路：

bash

curl -X POST "https://api.xinbao-ai.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "生成一张简洁的产品海报，背景干净，光线自然。" }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["IMAGE"]
    }
  }'

如果你的渠道接入的是异步生图网关，最小流程通常是：

POST https://async.xinbao-ai.com/v1beta/models/{model}:generateContent 请求里的 output=url 可以放在 query，也可以放在请求体里
拿到返回中的 id
等待约 50s 后 再开始第一次轮询
单任务可用 GET https://async.xinbao-ai.com/v1/tasks/{id}；多个进行中任务建议改用 POST https://async.xinbao-ai.com/v1/tasks/batch-get
客户端默认可固定每 10s 轮询一次
如果服务端返回更大的 Retry-After 或 next_poll_after_ms，优先遵守更大的值
如果同时轮询的任务超过 100 个，请拆成多个 batch，并放在同一个轮询周期里发出
客户端建议提供“手动刷新 / 手动轮询”按钮，便于用户主动查看最新状态
任务成功后读取 candidates[*].content.parts[*].inlineData.data
或直接访问 GET https://async.xinbao-ai.com/v1/tasks/{id}/content 获取 302 跳转

常见错误

401/403：通常是 API Key 无效或未按 Bearer 格式传递
404：接口路径或模型名不正确
400：参数结构不符合能力要求，例如把图片字段写错位置
异步生图 409：任务还没完成，继续按 Retry-After 轮询
异步生图 429：单任务或同一批次轮询过快，先按 Retry-After / next_poll_after_ms 退避
异步生图已确认可以成功返回图片；同日复测 4/4 最小任务成功，但也出现过 upstream_timeout
异步任务 failed/upstream_timeout：任务已成功创建，但上游执行超时；先检查输入资源可达性、提示词复杂度，再决定是否重试
视频任务长时间处理中：先检查轮询间隔是否过短或输入资源是否不可访问

快速开始 ​

适用场景 ​

接入前准备 ​

核心规则 ​

第一个请求 ​

常见错误 ​

下一步 ​

快速开始

适用场景

接入前准备

核心规则

第一个请求

常见错误

下一步