Models and Text API

The model catalog and text chat both use the same platform API key. For shared conventions (base URL, authentication, rate limiting, retries), see Authentication and Common Conventions.

Query the model list

Authentication

Authorization: Bearer <API_KEY>.

Request parameters

There is no request body; simply include the API key in the request header.

Request example

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

Response parameters

object and success are top-level fields and are not inside data[]. object is always list, and success is true on success. Determine whether the request succeeded by the HTTP status code; success is only supplementary.

Response body

{
  "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
}

A response of "data": [] means the call group that the current key belongs to has no available models; first check the group configuration or contact platform support, and do not retry with the display name shown on the page. The model catalog changes with authorization and platform availability, so refresh it once when the service starts, when the user selects a model, or when you receive a "model unavailable" error.

Error response

Text chat

Authentication

Authorization: Bearer <API_KEY>.

Request body · application/json

Request example

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

Response parameters

usage also contains detailed usage fields for this request's billing (cache hits, input/output breakdown, etc.); rely on the actual response. Some channels also return extension fields such as latency_checkpoint, routing, and system_fingerprint; clients should ignore fields they do not recognize rather than parsing against a fixed full set of fields.

Response body

{
  "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
  }
}

Streaming response (add "stream": true to the request body; the response is text/event-stream):

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

Clients must keep reading until [DONE]; streaming responses must not be cached or concatenated into duplicated content by intermediary layers. The final data chunk may contain only usage, in which case choices may be empty.

Reasoning models may return empty content

Some reasoning models spend the output quota on hidden reasoning first. Observed: when requesting gpt-5-nano with a very small max_tokens, the HTTP response is 200, but message.content is empty, finish_reason is length, and usage.completion_tokens_details.reasoning_tokens equals the output limit. In this case, increase the quota or switch to a non-reasoning text model; do not treat an empty string as a model malfunction or API failure.

Server-side example

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

Never put the API key in browser code; frontend requests should go to your own backend first, and the backend forwards them.

Error response

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

For the complete explanation, see Error Codes and Troubleshooting.