模型与文本接口

模型目录和文本对话都使用同一把平台 API Key。公共约定（基础地址、认证、限流、重试）见认证与基础规范。

查询模型列表

GET/v1/models

请求示例

这一步不需要请求体，直接在请求头带上 API Key 即可。返回的 data[].id 就是后续所有调用要用的模型 ID。

请求

curl "https://locopalai.com/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

响应参数

参数	类型	说明
`object`	string	固定为 `list`
`success`	boolean	查询成功时为 `true`
`data`	array	当前 Key 可调用的模型列表
`data[].id`	string	模型 ID，提交请求时原样填写
`data[].object`	string	固定为 `model`
`data[].created`	integer	目录记录时间（Unix 秒）
`data[].owned_by`	string	模型提供方标识，仅供参考
`data[].supported_endpoint_types`	string[]	该模型可用的接口类型

object 与 success 是顶层字段，不在 data[] 内。object 固定为 list， success 成功时为 true。判断请求是否成功请以 HTTP 状态码为准，success 仅作辅助。

响应体

{
  "data": [
    {
      "id": "doubao-seedance-2.0",
      "object": "model",
      "created": 1626777600,
      "owned_by": "doubaovideo",
      "supported_endpoint_types": ["openai"]
    },
    {
      "id": "claude-sonnet-4-5-20250929",
      "object": "model",
      "created": 1626777600,
      "owned_by": "claude",
      "supported_endpoint_types": ["anthropic", "openai"]
    }
  ],
  "object": "list",
  "success": true
}

返回 "data": [] 表示当前 Key 所属调用分组没有可用模型，请先确认分组配置或联系平台支持，不要改用页面展示名称重试。模型目录会随授权和平台可用性变化，建议在服务启动、用户选择模型或收到「模型不可用」时刷新一次。

错误响应

HTTP	响应	说明
`401`	`{"error":{"code":"","message":"Invalid token (request id: ...)","type":"new_api_error"}}`	API Key 缺失、错误或已失效
`500`	`{"error":{"message":"...","type":"new_api_error"}}`	目录查询失败，保留请求标识后重试

文本对话

POST/v1/chat/completions

请求体 · application/json

参数	类型	必填	说明
`model`	string	是	从 `/v1/models` 返回的文本模型 ID
`messages`	array	是	按时间顺序排列的消息
`messages[].role`	string	是	`system`、`user` 或 `assistant`
`messages[].content`	string	是	当前消息内容
`stream`	boolean	否	`true` 时使用 SSE 流式返回，读到 `[DONE]` 结束
`temperature`	number	否	是否支持以当前模型实际能力为准
`max_tokens`	integer	否	是否支持以当前模型实际能力为准

请求示例

model 必须写成 /v1/models 返回的 id，不要用页面上的展示名称。 stream 设为 true 时按 SSE 逐段返回，读到 [DONE] 结束。

右侧给出三种语言的等价写法，切换标签即可对照。

curl -X POST "https://locopalai.com/v1/chat/completions" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的文本模型 ID",
  "messages": [{ "role": "user", "content": "只回复两个字：你好" }],
  "stream": false
}
JSON

响应参数

参数	类型	说明
`id`	string	本次响应标识，用于排查和对账
`object`	string	非流式时为 `chat.completion`
`created`	integer	响应时间（Unix 秒）
`model`	string	本次请求使用的模型 ID
`choices`	array	结果列表
`choices[].index`	integer	结果序号
`choices[].message.role`	string	固定为 `assistant`
`choices[].message.content`	string	生成的文本
`choices[].finish_reason`	string	结束原因，`length` 表示被长度截断
`usage.prompt_tokens`	integer	输入用量
`usage.completion_tokens`	integer	输出用量
`usage.total_tokens`	integer	总用量
`choices[].message.refusal`	string / null	模型拒绝内容时的说明，普通回答通常为 `null`
`choices[].message.annotations`	array	模型的附加标注，可能为空

usage 还会包含本次计费的详细用量字段（缓存命中、输入/输出拆分等），以实际返回为准。部分渠道还会返回 latency_checkpoint、routing、system_fingerprint 等扩展字段，客户端应忽略不认识的字段，不要按固定字段全集解析。

响应体

{
  "id": "msg_011CevNtsfivFKb6YP3WcL7A",
  "model": "claude-haiku-4-5-20251001",
  "object": "chat.completion",
  "created": 1789071575,
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20587,
    "completion_tokens": 6,
    "total_tokens": 20593
  }
}

流式响应（请求体加 "stream": true，响应为 text/event-stream）：

data: {"choices":[{"delta":{"content":"这是"}}]}
data: {"choices":[{"delta":{"content":"模型输出"}}]}
data: [DONE]

客户端必须持续读取直到 [DONE]；流式响应不要被中间层缓存或拼接成重复内容。最后一个数据块可能只包含 usage，此时 choices 可能为空。

部分推理模型会把输出额度优先用于隐藏推理。实测请求 gpt-5-nano 且 max_tokens 过小时，HTTP 返回 200，但 message.content 为空、finish_reason 为 length，usage.completion_tokens_details.reasoning_tokens 等于输出上限。遇到这种情况应提高额度或改用非推理文本模型，不能把空字符串当成模型故障或接口失败。

服务端示例

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()

不要把 API Key 放进浏览器代码；前端请求先到你的业务后端，再由后端转发。

错误响应

{
  "error": {
    "code": "model_not_found",
    "message": "No available channel for model xxx under group xxx (distributor) (request id: ...)",
    "type": "new_api_error"
  }
}

HTTP	响应 / 原因	处理
`400`	`{"error":{"code":"","message":"Model name not specified, model name cannot be empty (request id: ...)","type":"new_api_error"}}`	请求体缺少 `model`
`401`	`Invalid token`	API Key 缺失、错误或已失效
`503`	`{"error":{"code":"model_not_found","message":"No available channel for model ..."}}`	当前分组没有该模型的可用渠道，改选同类模型或联系平台支持
`429`	请求频率受限	退避后重试

完整说明见错误码与排查。

模型与文本接口

模型与文本接口

查询模型列表

认证方式

请求参数

请求示例

响应参数

响应体

错误响应

文本对话

认证方式

请求体 · application/json

请求示例

响应参数

响应体

推理模型可能返回空内容

服务端示例

错误响应

本页目录