API 概览

接口目录

方法	路径	用途
`GET`	`/v1/models`	返回当前 API Key 可调用的模型 ID。
`POST`	`/v1/chat/completions`	文本对话与多轮生成。
`POST`	`/v1/images/generations`	根据提示词创建图片。
`POST`	`/v1/video/generations`	创建异步视频任务，详见视频生成 API。
`POST`	`/api/v3?Action=<Action>&Version=2024-01-01`	管理虚拟人物素材、真人素材和状态查询，详见素材库 API。

基础地址与认证

所有 API 使用平台域名加路径，例如：

https://你的平台域名/v1/chat/completions

每个请求都携带 API Key：

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

API Key 只应由你的服务端使用。浏览器、桌面客户端和移动应用应先请求你自己的业务后端，再由后端转发模型请求。

素材库 API 使用控制台“AccessKey 管理”创建的 AccessKey / SecretKey，并采用独立 HMAC-SHA256 签名。虚拟人物素材、真人素材的提交和状态查询请参阅素材库 API。

请求项	值	说明
基础地址	`https://locopalai.com`	在路径前添加此地址。
认证 Header	`Authorization: Bearer <YOUR_API_KEY>`	每个受保护接口都必须携带。
请求格式	`application/json`	除明确要求文件上传的接口外均使用 JSON。
模型名称	`/v1/models` 的 `data[].id`	不要根据展示名称手动拼写。

通用响应

文本和图片等兼容接口会按对应 API 协议返回结果。HTTP 非 2xx 时，响应体通常包含 error 对象：

{
  "error": {
    "message": "错误说明",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}

不要通过匹配完整错误文案写业务逻辑；请根据 HTTP 状态、error.code 和是否可重试处理。

获取模型列表

GET /v1/models

curl "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

返回对象的 data[].id 是调用时应填写的模型名称。该列表会随你的授权和平台可用性变化，因此建议定期刷新，不要把模型名永久写死在客户端。

建议在服务启动、用户选择模型或收到“模型不可用”提示时刷新一次模型列表。展示给终端用户时，使用你自己的名称映射，但提交请求时必须使用原始 id。

成功响应示例

{
  "object": "list",
  "data": [
    {"id": "可调用的模型 ID", "object": "model"}
  ]
}

文本对话

POST /v1/chat/completions

{
  "model": "模型名称",
  "messages": [
    {"role": "system", "content": "你是专业的中文助手。"},
    {"role": "user", "content": "为春季新品写一条 30 字以内的文案。"}
  ],
  "temperature": 0.7
}

流式返回时在请求中加入 "stream": true。客户端应持续读取 Server-Sent Events，收到 [DONE] 后结束本次响应。

参数	类型	必填	说明
`model`	string	是	从模型列表返回的文本模型 ID。
`messages`	array	是	按时间顺序传入的对话消息。
`messages[].role`	string	是	使用 `system`、`user` 或 `assistant`。
`messages[].content`	string	是	当前消息内容。
`stream`	boolean	否	为 `true` 时使用 SSE 分段返回。
`temperature`	number	否	支持与否以当前模型实际能力为准。

成功响应重点字段：从 choices[0].message.content 读取文本；usage 用于记录本次用量。流式响应不应被代理缓存或拼接为重复消息。

JavaScript 服务端示例

const response = await fetch('https://locopalai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LOCOPAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '从 /v1/models 选择的模型 ID',
    messages: [{ role: 'user', content: '写一条产品简介。' }],
  }),
})

if (!response.ok) throw new Error(await response.text())
const data = await response.json()

不要从浏览器代码直接调用该接口，也不要把环境变量编译进前端包。

图片生成

POST /v1/images/generations

{
  "model": "图片模型名称",
  "prompt": "简洁的产品海报，暖色背景，中文留白标题区域",
  "size": "1024x1024",
  "n": 1
}

不同图片模型支持的尺寸、数量和格式并不完全相同。先在模型广场确认能力，并以接口返回的参数校验错误为准。

参数	类型	必填	说明
`model`	string	是	从模型列表返回的图片模型 ID。
`prompt`	string	是	图片内容与视觉要求。
`size`	string	否	例如 `1024x1024`；以模型返回的参数要求为准。
`n`	integer	否	生成数量；仅在当前模型支持时使用。

成功后从 data[] 中读取平台返回的图片结果。不要假定所有模型都返回相同字段或支持相同尺寸。

可靠性与幂等

对于会产生费用的生成请求，先在自己的服务端创建业务记录，再调用平台接口。网络中断时，应先检查是否已经取得平台响应或任务 ID，避免同一用户操作重复提交。业务侧可使用自己的请求 ID 关联日志、账单和最终结果；发生异常时仅记录必要的脱敏信息。

调用建议

每次请求都设置合理的服务端超时，并将超时与用户取消区分处理。
对 429 和短暂 5xx 按响应头或错误类型进行有限、退避的重试；不要在客户端并发重复提交同一生成请求。
保存你的业务请求 ID、模型名称和平台返回的请求 ID，方便查询用量或提交支持请求。
不要把用户的 API Key 记录在日志、错误追踪、前端埋点或截图中。

本页目录