LLM Hub API

Artific LLM Hub 把多家大模型供应商聚合成一个对话接口：统一的请求格式、自动选路与故障切换、统一以配额计费，并可随时查询每一次调用的用量与扣费。

Base URL

https://api.artific.social

格式

JSON（对话可选 SSE 流式）

认证

API Key 或会话 Cookie

成功响应统一包在 {"success": true, "data": …} 里；错误响应是 {"detail": …}，见「错误处理」。平台内的 GamEcho、MemoryEcho 也经 LLM Hub 调用模型，这些调用同样计入您的用量。

认证

会话 Cookie

登录 artific.social 后，浏览器持有 HttpOnly 会话 Cookie。在 artific.social 页面内的请求带上 credentials: 'include' 即可；命令行调试可从浏览器开发者工具复制 Cookie 头。

GET /models 无需登录；其余接口未认证返回 401 {"detail": "invalid or missing session"}。

API Key（服务器端推荐）

在 artific.social 控制台 → 服务 → LLM Hub 创建 as_ 开头的 API Key，请求时放进 Authorization: Bearer as_…。Key 只在创建时显示一次，请妥善保存；泄露后立即在控制台撤销。

Key 的 scope 须为空（全功能）或包含 llm-hub，否则返回 403。Key 代表创建者本人：调用计入本人用量、从本人配额扣费，权限与本人登录相同。

快速开始

两步：查模型 → 发起对话。

# 0. 在 artific.social 控制台 → 服务 → LLM Hub 创建 API Key
KEY='as_…'

# 1. 查可用模型（无需登录）
curl https://api.artific.social/api/v1/llm-hub/models

# 2. 非流式对话
curl -X POST https://api.artific.social/api/v1/llm-hub/chat \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KEY" \
  -d '{"model": "<model_id>", "messages": [{"role": "user", "content": "你好"}]}'
# => { "success": true, "data": { "content": "…", "finish_reason": "stop", … } }

# 3. 流式对话（-N 关闭缓冲）
curl -N -X POST https://api.artific.social/api/v1/llm-hub/chat \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $KEY" \
  -d '{"model": "<model_id>", "messages": [{"role": "user", "content": "你好"}], "stream": true}'

OpenAI 兼容

现有的 OpenAI SDK 或任何支持「自定义 OpenAI 端点」的工具，把 base URL 设为 https://api.artific.social/api/v1/llm-hub/v1、API Key 填 as_… 即可接入。提供 POST /chat/completions（含 stream: true）和 GET /models，请求、响应、SSE 与错误（{ "error": { message, type, code, param } }）都是 OpenAI 标准形状。计费、模型可见性与上面的原生接口相同。

from openai import OpenAI

client = OpenAI(
    base_url="https://api.artific.social/api/v1/llm-hub/v1",
    api_key="as_…",  # 控制台 → 服务 → LLM Hub 创建的 API Key
)

print([m.id for m in client.models.list().data])

resp = client.chat.completions.create(
    model="<model_id>",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content, resp.usage)

# 流式
for chunk in client.chat.completions.create(model="<model_id>", messages=[{"role": "user", "content": "你好"}], stream=True):
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")

支持工具调用：tools、tool_choice、parallel_tool_calls，响应（含流式 delta）带回 tool_calls，再用 role: "tool" + tool_call_id 回传结果。
支持多模态：content 可以是 parts 数组（text / image_url 等），模型本身要支持对应输入。
不支持老式 functions / function_call（请改用 tools）、n > 1 与音频输出，带上会返回 400 UNSUPPORTED_PARAM。
top_p、stop、seed、response_format 等参数只在模型的供应商支持时生效，否则被忽略、不报错。
流式结束前总会多发一个 choices 为空、带 usage 的 chunk，然后是 data: [DONE]。
每个响应都带 x-llm-hub-query-id 头，可用它在「用量与历史」里查这次调用。

模型 Models

先查可用模型与价目，再用模型 ID 发起对话。

GET/api/v1/llm-hub/models

列出可直接调用的公开模型（无需登录）

响应

{
  "success": true,
  "data": {
    "models": [
      {
        "id": "deepseek-flash",
        "name": "deepseek flash",
        "provider_name": "Artific LLM Hub",
        "provider_type": "aggregated",
        "sell_units_per_1m_input": 5550000000000,
        "sell_units_per_1m_output": 14400000000000,
        "sell_units_per_1m_cached_input": null,
        "visibility": "public"
      }
    ]
  }
}

只列出已启用且公开的模型；未公开的模型只供平台内部服务使用，直接调用返回 403。
sell_units_per_1m_input / output 是每百万输入 / 输出 token 的实扣售价，单位是配额的存储单位（10^8 = 1 配额）。示例中 5,550,000,000,000 即每百万输入 token 55,500 配额。sell_units_per_1m_cached_input 是命中提示缓存那部分输入的单价，为 null 时按输入全价计。价目暂时取不到时为 null。
同一模型可能由多家上游供应商提供，LLM Hub 自动选路并在故障时切换，对调用方透明；按模型计价，与实际落到哪家无关。
回包里的 input_price_per_1m / output_price_per_1m 是旧的美分价，已与实扣脱钩、将被移除，请勿使用。

对话生成 Chat

统一的对话接口：不论背后是哪家供应商，请求与响应形状一致。

请求字段

model	string	必填。模型 ID，取自 GET /models 的 id
messages	array	必填。对话消息：[{ "role": "system" \| "user" \| "assistant", "content": "…" }]
stream	boolean	是否 SSE 流式返回，默认 false
max_tokens	integer	输出 token 上限（思考 token 也计在内）
temperature	number	采样温度
thinking	boolean	思考模式开关。不传 = 用模型默认（多数模型默认开启）；传 false 明确关闭，适合只要结构化结果的场景，省输出 token

流式响应（stream: true）

event: chunk
data: 我是

event: chunk
data: ……

event: done
data: {"input_tokens": 21, "output_tokens": 18, "finish_reason": "stop", …}

chunk：data 是一段纯文本增量，按顺序拼接即为完整回复。
done：data 是 JSON，含 input_tokens、output_tokens、finish_reason；其中的 *_cost_cents 是旧美分口径，不是实扣。
error：输出开始后出错，data 是错误描述，流随即结束、不再有 done。

POST/api/v1/llm-hub/chat

对话生成（JSON 或 SSE 流式）

请求体

{
  "model": "deepseek-flash",
  "messages": [
    { "role": "system", "content": "你是一个简洁的助手。" },
    { "role": "user", "content": "用一句话介绍你自己" }
  ],
  "stream": false,
  "max_tokens": 1024
}

响应

{
  "success": true,
  "data": {
    "content": "我是……",
    "finish_reason": "stop",
    "usage": { "prompt_tokens": 21, "completion_tokens": 18 }
  }
}

finish_reason 为 stop 表示正常结束；length 表示达到 max_tokens 被截断；incomplete 表示上游流中途断开、内容不完整。请先判断 finish_reason 再使用 content。
回包里的 cost_cents / sell_cost_cents 是旧美分口径，不等于实扣配额，实扣请看 /queries 的 charged_credit_units。
调用前先向配额服务预授权（按输入估算 + max_tokens 预冻结），结束后按实际 token 结算并释放差额；被拒时在调用模型之前返回 403，见「错误处理」。

用量与历史

查询自己在 LLM Hub 上的 token 用量、配额消耗与调用记录。

GET/api/v1/llm-hub/usage

当前用户的累计用量，按模型与按来源服务汇总

响应

{
  "success": true,
  "data": {
    "models": [
      {
        "model": "deepseek-flash",
        "query_count": 42,
        "input_tokens": 51200,
        "output_tokens": 18300,
        "charged_credit_units": 51230000000,
        "payg_credit_units": 0,
        "subscription_credit_units": 51230000000,
        "last_used_at": "2026-10-26T09:12:00Z"
      }
    ],
    "services": [
      { "service_slug": "llm-hub", "query_count": 30, "charged_credit_units": 3600000000, … },
      { "service_slug": "gamecho", "query_count": 12, … }
    ]
  }
}

统计全部历史（不分月）。charged_credit_units 为实扣配额（存储单位，10^8 = 1 配额），其中 payg_credit_units 从您的账户余额扣、subscription_credit_units 由套餐额度承担。
services 按来源拆分：llm-hub 是您自己直连（网页对话或本 API）的调用，其余是平台服务（如 GamEcho、MemoryEcho）代您发起的调用。

GET/api/v1/llm-hub/queries?model=&limit=50&offset=0

调用历史（按时间倒序，可按模型筛选）

响应

{
  "success": true,
  "data": {
    "queries": [
      {
        "query_id": "3f0c…",
        "service_slug": "llm-hub",
        "model": "deepseek-flash",
        "status": "succeeded",
        "input_tokens": 21,
        "output_tokens": 18,
        "charged_credit_units": 40800000,
        "payer_kind": "user",
        "started_at": "2026-10-26T09:12:00Z",
        "completed_at": "2026-10-26T09:12:02Z",
        "content_visible": true,
        "request_preview": "用一句话介绍你自己",
        "response_preview": "我是……"
      }
    ],
    "total": 42, "limit": 50, "offset": 0
  }
}

limit 取值 1–200，默认 50。
payer_kind 为 user 表示从您的余额扣，service 表示由套餐额度承担。
只有您自己直连的调用（content_visible = true）返回内容预览；平台服务代发的调用只给模型、token、扣费与状态等元数据。

GET/api/v1/llm-hub/queries/{query_id}

单次调用详情（含完整输入输出）

字段同列表项，另含 messages（完整输入消息数组）、response_content（完整输出）与 error_message。
平台服务代发的调用 messages 为空数组、response_content 为 null。
不属于当前用户或不存在返回 404。

配额与计费

Artific 平台内以配额（Credit）结算，按当前价目 1,000,000 配额 = ¥72 = $11.11（仅供参考，以配额数为准）。LLM Hub 按模型价目、按输入与输出 token 分别计费，价目以 GET /models 返回的 sell_units_per_1m_input / output 为准。

每次调用前先预授权：按输入估算 + max_tokens 冻结一笔额度，结束后按实际 token 结算、释放差额——max_tokens 设得过大只会多冻结，不会多扣，但余额不够冻结时会被拒。有套餐时先用套餐额度，超出部分从账户余额扣（需已开启按量付费）。

失败的调用不扣费；流式输出中途失败时，已生成的 token 照常计费。用量见 /usage 与 /queries，逐笔扣费明细见 artific.social 钱包的配额流水，套餐见订阅中心。

错误处理

错误响应为 {"detail": "描述信息"}。计费被拒与内容拦截的 detail 是对象，带机器可读的 error_code：{"detail": {"error_code": "INSUFFICIENT_BALANCE", "message": "…"}}，请按 error_code 分支处理，不要解析文案；配额服务以后可能新增取值，未识别的按通用计费失败提示。

状态码	detail	处理建议
400	model is required / messages is required	缺少必填字段。
401	invalid or missing session	未登录或会话过期。重新登录 artific.social，或改用 API Key。
401	invalid, revoked or expired api key	API Key 不存在、已撤销或已过期。到控制台重新创建。
403	insufficient scope: this API key does not grant 'llm-hub'	API Key 的 scope 不含 llm-hub。在 LLM Hub 页面创建的 key 自带该 scope。
403	detail.error_code: PAYG_CONFIRM_REQUIRED	需要从账户配额余额扣费，但尚未开启按量付费。在 artific.social 开启按量付费后重试。
403	detail.error_code: INSUFFICIENT_BALANCE	配额余额不足。充值后重试。
403	detail.error_code: QUOTA_EXHAUSTED	本月按量付费已达您设置的上限。调高上限或等待下月。
403	model '…' is not available for direct use	模型未公开，只供平台内部服务使用。换用 GET /models 列出的模型。
404	model '…' not found in any enabled provider	模型不存在或当前没有可用的供应商。
404	query not found	调用记录不存在或不属于当前用户。
422	detail.error_code: CONTENT_BLOCKED	内容被上游供应商的安全策略拦截。修改输入后再试，原样重试不会成功。
500	upstream error	所有候选供应商都失败。可稍后重试；流式请求已开始输出后出错会以 event: error 结束。
502	failed to verify session / failed to verify api key	会话或 API Key 校验服务暂时不可用（不代表凭证无效），稍后重试。