面向生产环境的统一 LLM API 接入说明

你可以把 Primordial AI 看成一个统一的 API 网关。当前推荐的接入方式有两种：

• OpenAI 兼容方式：适合大多数 SDK 与应用，使用 /v1/chat/completions 或 /v1/responses。
• Claude Messages 方式：如果你现有代码已经是 Anthropic 风格，可以直接对接 /v1/messages。

接口与参数总览

现在站内模型已经不止一种调用形态。最容易踩坑的地方是： 文本模型大多可以统一走 OpenAI 兼容接口，但图片生成和 Claude 原生接口的入参格式不同。

当前模型分类

可用模型会随账号分组和已启用上游渠道变化。本页不再固定一份容易过期的模型清单： 接入前请使用自己的 API Key 请求 GET /v1/models，并直接复制返回的模型 ID。

最稳妥的做法始终是先请求一次 GET /v1/models，再从返回结果里读取模型名。

curl https://www.primoraihub.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

OpenAI Chat Completions

这是当前最通用的接入方式。GPT、Claude、Gemini 在这个网关里都可以先用这一套格式联调。

curl 示例

curl https://www.primoraihub.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_V1_MODELS",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "请用一句话介绍 Primordial AI"}
    ],
    "max_tokens": 512
  }'

Python 示例

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://www.primoraihub.com/v1"
)

resp = client.chat.completions.create(
    model="MODEL_ID_FROM_V1_MODELS",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "请用一句话介绍 Primordial AI"}
    ],
    max_tokens=512,
)

print(resp.choices[0].message.content)

JavaScript 示例

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PRIMORDIAL_API_KEY,
  baseURL: "https://www.primoraihub.com/v1",
});

const resp = await client.chat.completions.create({
  model: "MODEL_ID_FROM_V1_MODELS",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "请用一句话介绍 Primordial AI" }
  ],
  max_tokens: 512
});

console.log(resp.choices[0].message.content);

Gemini 模型接入说明

这一组模型在站内已经统一封装成 OpenAI 兼容格式，所以 不要直接照搬 Google 原生 API 的 contents、parts、generateContent 写法。 最简单的方法就是继续使用 /v1/chat/completions。

Gemini 文本模型 curl 示例

curl https://www.primoraihub.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GEMINI_MODEL_ID_FROM_V1_MODELS",
    "messages": [
      {"role": "user", "content": "请只回复 ok"}
    ],
    "max_tokens": 64
  }'

Gemini 图像能力模型联调示例

如果 GET /v1/models 为当前 Key 返回具备图像能力的 Gemini 模型 ID，请替换下面的占位符， 并先通过 chat/completions 验证能力，再用于生产。

curl https://www.primoraihub.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GEMINI_IMAGE_MODEL_ID_FROM_V1_MODELS",
    "messages": [
      {"role": "user", "content": "请只回复 ok"}
    ],
    "max_tokens": 64
  }'

图片生成

如果你要的是直接生成图片，不要走 /v1/chat/completions，而是使用单独的 /v1/images/generations。

curl 示例

curl https://www.primoraihub.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "IMAGE_MODEL_ID_FROM_V1_MODELS",
    "prompt": "一张极简风格的蓝色立方体产品海报，白色背景，工作室打光",
    "n": 1,
    "size": "1024x1024"
  }'

Python 示例

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://www.primoraihub.com/v1"
)

result = client.images.generate(
    model="IMAGE_MODEL_ID_FROM_V1_MODELS",
    prompt="一张极简风格的蓝色立方体产品海报，白色背景，工作室打光",
    size="1024x1024",
    n=1,
)

print(result.data[0].b64_json[:80])

流式输出

对支持流式输出的模型和路由，将 stream 设为 true。 在命令行测试 SSE 返回时请加上 -N。

curl -N https://www.primoraihub.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_V1_MODELS",
    "stream": true,
    "messages": [
      {"role": "user", "content": "请分三行输出：第一行 hello，第二行 primordial，第三行 ai"}
    ]
  }'

返回内容是标准的 data: {...} 事件流，结束时会收到 [DONE]。

Responses API

如果你的 SDK 或应用已经迁移到 OpenAI 新版统一接口，可以直接使用 /v1/responses。

curl https://www.primoraihub.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_V1_MODELS",
    "input": "请只回复 ok",
    "max_output_tokens": 32
  }'

生产验证过的最小 Python 请求、Agents SDK 配置方式和未验证可选功能清单，见Responses API 自定义 Base URL 指南。

Claude Messages 接口

对 Claude 模型，如果你手头的调用代码已经是 Anthropic 风格，可以继续沿用。

curl https://www.primoraihub.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "CLAUDE_MODEL_ID_FROM_V1_MODELS",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

请把 CLAUDE_MODEL_ID_FROM_V1_MODELS 替换为当前 Key 返回的 Claude 系列模型 ID。 如果你希望统一一套代码，也可以直接通过 OpenAI 兼容的 /v1/chat/completions 来调用 Claude 模型。

邀请计划状态

邀请链接可以把新注册账号与邀请人建立关联。2026 年 8 月 24 日核验的生产配置中，邀请人与被邀请人的注册奖励均为 0。

暂不建议接入的能力

为了保证文档和实际能力一致，以下能力本页暂不提供接入示例：

• /v1/embeddings：当前没有可用的 embedding 渠道。
• 音频、文件、Assistants、Fine-tuning 等其它接口：当前不作为对外主能力说明。

常见问题

1. Base URL 应该填什么？

OpenAI 兼容 SDK 填 https://www.primoraihub.com/v1。

2. 为什么我调用失败提示模型不存在？

模型名请以 GET /v1/models 返回结果为准，不要沿用别的平台模型名。

3. Claude 一定要走 /v1/messages 吗？

不是。你也可以统一走 /v1/chat/completions，只要模型名填 Claude 模型即可。

4. Gemini 为什么不能直接照抄 Google 原生示例？

因为在本平台里 Gemini 已经被统一映射成 OpenAI 兼容接口，推荐直接使用 /v1/chat/completions + messages。

5. 图片生成应该走哪个接口？

纯图片生成请使用 /v1/images/generations，并把 IMAGE_MODEL_ID_FROM_V1_MODELS 替换为当前账号可用的图片模型 ID。

6. 如何验证我的 API Key 是否正常？

最简单的方法是先调用一次 GET /v1/models。能返回模型列表，说明鉴权已生效。