用 Peryn API 开发

01快速上手#

三步拿到第一个回答。

1. 用邮箱登录，然后在充值中充值额度。
2. 在API 密钥中创建密钥。密钥只显示一次，我们只保存它的哈希。把它放在 PERYN_API_KEY 环境变量里。
3. 把任意 OpenAI SDK 指向这个 Base URL，发送请求。

curl https://api.peryn.ai/v1/chat/completions \-H "Authorization: Bearer $PERYN_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "llama-3.1-8b-instruct","max_tokens": 64,"messages": [{"role": "user", "content": "Say hello in five words."}]}'

回答采用 OpenAI 的格式，你付费的 token 数在 usage 中：

{"id": "chatcmpl-…","object": "chat.completion","created": 1791216000,"model": "llama-3.1-8b-instruct","choices": [{"index": 0,"message": { "role": "assistant", "content": "Hello. Nice to meet you." },"logprobs": null,"finish_reason": "stop"}],"usage": { "prompt_tokens": 16, "completion_tokens": 8, "total_tokens": 24 }}

02Base URL 与模型#

所有端点共用一个 Base URL。以 Bearer token 发送你的密钥。

https://api.peryn.ai/v1

每个运行模型的请求都需要 Authorization: Bearer <key> 请求头。生产环境的密钥以 pc_live_ 开头。请求体为 JSON，最大 2 MB。

curl https://api.peryn.ai/v1/models

请求字段

下列字段会被读取；其他不影响回答的 OpenAI 字段（如 user 或 metadata）会被忽略。

模型输入文本、输出文本。图片及其他非文本内容、不等于 1 的 n 或 best_of、echo、suffix、token-id 形式的提示词、一个请求多个提示词，以及旧的 functions 和 function_call 字段（请改用 tools 和 tool_choice）会收到 400，并指明是哪个字段。如果你需要其中某项，请联系我们。每个模型在 GET /v1/models 的 supported_parameters 中列出它支持的可选字段。

工具调用

API 接受 OpenAI 格式的 tools、tool_choice、parallel_tool_calls 以及 role 为 tool 的消息，并原样传给模型。本版本中没有模型声明支持工具调用。未声明该功能的模型可能拒绝请求：发送 tools 时默认的 tool_choice auto 会收到 400，代码 bad_request，并附上模型给出的原因。

结构化输出

response_format 的 type 可以是 json_object 或 json_schema。请求运行前我们会检查 json_schema：无法使用的会在生成任何 token 之前收到 400。我们也会检查每个非流式回答：如果不是有效 JSON，或与你的 schema 不符，你会收到 502 invalid_output，且不计费（检查未能及时完成时为 output_check_failed）。被 max_tokens 截断的回答原样返回，finish_reason 为 length。流式回答不做检查。 本版本中没有模型声明支持结构化输出。

对数概率

logprobs 和 top_logprobs 会传给模型，模型返回的内容在每个 choice 的 logprobs 中。 本版本中没有模型声明支持它们。

文本补全

curl https://api.peryn.ai/v1/completions \-H "Authorization: Bearer $PERYN_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "llama-3.1-8b-instruct", "prompt": "The capital of France is", "max_tokens": 16}'

响应头

• 每个响应都带 x-request-id 和 Inference-Id：回答、错误和流式响应都有，网关重启时的 503 也有。两者的值相同，以 req_ 开头。你的请求、它的 token 数和费用都记录在这个 id 下。
• 由 GPU 节点处理的每个响应（无论是否流式）都带 x-pc-node-country：节点所在国家的两字母代码（ISO 3166-1）。

把请求 id 和你自己的日志一起保存，就某个请求联系我们时请附上它。我们不存储提示词和回答，只能靠这个 id 找到请求。出错时，OpenAI SDK 以 request_id（Python）和 requestID（JavaScript）给出它；错误一节的示例会打印它。

curl -sS -D - -o /dev/null https://api.peryn.ai/v1/chat/completions \-H "Authorization: Bearer $PERYN_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "llama-3.1-8b-instruct", "max_tokens": 8, "messages": [{"role": "user", "content": "Hi"}]}'

03流式输出#

OpenAI 格式的 server-sent events：模型写出一个 token，你就收到一个。

设置 stream: true。每个事件是一行带 chat.completion.chunk 的 data:；文本在 choices[0].delta.content 中，最后一个 chunk 带 finish_reason。设置 stream_options: {"include_usage": true} 时，每个 chunk 都有 "usage": null，另有一个 choices 为空的 chunk 携带 token 数。流以 data: [DONE] 结束。

curl -N https://api.peryn.ai/v1/chat/completions \-H "Authorization: Bearer $PERYN_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "llama-3.1-8b-instruct","max_tokens": 128,"stream": true,"stream_options": {"include_usage": true},"messages": [{"role": "user", "content": "Write a haiku about GPUs."}]}'

: ping
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":1791216000,"model":"llama-3.1-8b-instruct","choices":[{"index":0,"delta":{"role":"assistant","content":"Silicon"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {…,"choices":[{"index":0,"delta":{"content":" hums"},"logprobs":null,"finish_reason":null}],"usage":null}
data: {…,"choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}],"usage":null}
data: {…,"choices":[],"usage":{"prompt_tokens":16,"completion_tokens":19,"total_tokens":35}}
data: [DONE]

• 以冒号开头的行（: ping）在模型生成第一个 token 期间保持连接。OpenAI SDK 会跳过它们。
• 第一个事件之前的错误以普通 HTTP 错误返回。流开始后的错误以一行 event: error 加错误 JSON 送达，然后是 data: [DONE]。
• 如果流中断或你关闭了它，你只为已送达的 token 付费。一个都没送达就不收费。
• 如果没有 GPU 在运行该模型，流式请求同样会等待，在 GPU 接手之前不发送任何内容（见GPU 繁忙时）。

04模型与价格#

实时价格，单位为美元 / 百万 token，不含增值税。

把模型 id 填在 model 字段。以下是各模型的 Standard 价格，比市场价低 30%。价格可能变动；请求按开始时生效的价格计费。

• llama-3.1-8b-instruct可用

  Llama 3.1 8B Instruct · 8B · 32,768 token，最大输出 8,192

  输入

  $0.014

  输出

  $0.028

同一张表的 JSON 版在 https://app.peryn.ai/api/pricing，带上下文长度的版本在 GET /v1/catalog。同样的价格也在价格页面上；每个模型的许可证见许可证页面。

curl https://api.peryn.ai/v1/catalog

一个请求的费用

输入 token 数乘以输入价格，加上输出 token 数乘以输出价格，向上取整到百万分之一美元。token 由我们用模型自己的分词器计数；计数就是每个回答中的 usage，也显示在你的用量页面上。

05隐私层级#

新密钥使用 Standard 层级。Private 层级需申请：联系我们。

Standard

永不用提示词或补全内容训练。零留存：我们不记录、不存储提示词或补全内容；只保留请求元数据（如请求 ID、账户、时间戳、模型、token 数、延迟、费用和状态），用于计费和保障可靠性。Standard 层级运行在同时挖 $PEARL 的 GPU 上；隐私政策中的“挖矿与你的数据”一节说明了这意味着什么。上面的价格是 Standard 价格。

你的请求在哪里运行

默认情况下，请求可在任何国家的任一健康节点上运行。在设置中为整个账户设置地区规则，在API 密钥页面为单个密钥进一步收窄。规则可以是仅欧盟、仅美国、美国 + 欧盟、你自己列出的国家，或要排除的国家。设置后，请求只在允许国家的节点上运行。如果这些节点全部繁忙，请求会收到 429 no_capacity。如果它们都不运行该模型，请求会按“GPU 繁忙时”中所述被保留，之后以 503、代码 no_capacity_in_region 失败。请求绝不会改到其他地方运行。

节点的国家来自运营者的声明，并与其 IP 地址的位置核对。不诚实的运营者可能同时伪造两者（例如用 VPN）；被我们发现的节点会被移除。每个回答都在 x-pc-node-country 中写明节点所在国家，你的用量页面也按国家细分你的请求。

06速率限制与额度#

按密钥计的每分钟限制，以及以美元预付的额度。

速率限制

• 每个密钥每分钟允许 60 个请求 和 200,000 token。两者都持续恢复。API 密钥页面显示每个密钥的限制。需要更多？联系我们。
• 请求开始时，按输入 token 数加 max_tokens 计入 token 限制；结束时退回没用完的部分。不设 max_tokens 时，按模型的全部输出上限（最多 8,192 token）计入，所以设置它可以让更多请求同时运行。
• 超出限制时，请求会立即被拒绝，返回 429、代码 rate_limit_exceeded，以及以秒为单位的 Retry-After 响应头。不会排队；等待相应时间后重试。
• 当某个模型的 GPU 全部繁忙时，请求会立即被拒绝，返回 429、代码 no_capacity 和 Retry-After 响应头，而不是排队等待。

额度

• 额度以美元预付，不含增值税。 用稳定币支付： 接受客户条款后，你账户专属的 Base、Arbitrum或Ethereum 充值地址和应发送的代币都在充值中。充值所在区块最终确认后，按一美元对一美元入账。低于 $1 的充值会暂存，直到暂存总额达到 $1。只在这些网络上发送这一种代币：其他任何转账都不会自动入账。
• 请求开始时，我们按最坏情况冻结费用：输入 token 加 max_tokens，按模型价格计算。结束时按实际用量扣费，其余解冻。如果可用额度不够冻结，请求会被拒绝，返回 402，代码 insufficient_quota。
• 在任何 token 送达你之前就失败的请求不收费。
• 用量页面按密钥、模型和国家显示最近 7、30 或 90 天的请求数、token 数和费用。
• 连续 12 个月没有任何活动（登录、请求或购买）时，未用完的额度会过期。我们至少提前 30 天给你发邮件。

07错误#

错误采用 OpenAI 的格式，OpenAI SDK 会把它们作为带状态码的异常抛出。

可能自行恢复的错误（429、503）带有 Retry-After 响应头。

curl -i https://api.peryn.ai/v1/chat/completions \-H "Authorization: Bearer $PERYN_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "no-such-model", "messages": [{"role": "user", "content": "Hi"}]}'

对 429、500、502、503 和 504 用退避方式重试；OpenAI SDK 会替你做（默认重试两次）。其他代码需要修改请求。解决不了？写信到 hello@peryn.ai，附上 x-request-id 或 Inference-Id 中的请求 id。

08用 Peryn 挖矿#

通过我们的矿池挖 Pearl。

设置你的机器

在任何带 NVIDIA GPU 的 Linux 机器上运行我们的 agent。无需账户：命令中的 $PEARL 地址就是收款地址。

curl -fsSL https://peryn.ai/install | sh -s -- YOUR_PEARL_ADDRESS

• 它会请求 sudo 权限，把我们的 agent 安装为服务，并自动更新。
• 在 HiveOS 上，一个 flight sheet 就能在每台矿机上运行我们的 agent：用 HiveOS 挖矿。
• 如果要加入账户，把地址换成矿工门户中的 fleet key。

在找钱包？ → Pearl Safe（在新标签页打开）

付款

• 费用以我们的矿池条款为准。
• 区块奖励在 100 次确认后入账。在此之前脱离主链的区块没有奖励，其入账会被撤销。
• 发放到你自己的 $PEARL 地址（每天），累计满 1 $PEARL 即付。 不足的部分继续累计，在之后的批次中支付，不会丢失。
• 每笔付款在发出前都会经过制裁名单筛查。

费用与结算方式

PPLNS

1%

按矿池找到的区块结算。费率最低。默认方式。

FPPS

2%

每个份额一笔固定收入，另加交易手续费。不靠运气。

创始矿工

0% / 1%

PPLNS / FPPS，直到 Pearl 的 FP8 升级后 6 个月。

创始矿工条款不与云合作伙伴条款叠加：机群工作适用合作伙伴费率。

每台矿机在密码里选择 FPPS：x;mode=fpps。

使用 PPLNS 时，矿池找到区块后，整笔奖励分给最近一段工作中的份额：难度合计达到网络难度两倍的最新已接受份额。你的部分就是这段工作中你的份额难度之和。一个份额在这段窗口内时，会计入期间找到的每一个区块，所以稳定挖矿就有稳定收入，只在矿池看起来运气好时才加入不会多得。

你的数据面板

查询你的 $PEARL 地址，查看算力、被接受和被拒绝的份额、预估、应付和已付的 $PEARL，以及每台矿机。无需登录。查询你的地址。

在找钱包？ → Pearl Safe（在新标签页打开）

在运营一批 GPU？告诉我们你的机群情况。在 peryn.ai/live 查看网络实时挖矿和推理。

故障排查

被拒绝的份额会在你的数据面板上按原因列出。各原因的含义：

21 Stale share (job expired: new block)

份额到达矿池之前，新区块已经出现。 每百个中有几个属于正常。更多则说明网络较慢：使用离你最近的 TLS 端口，或改用有线连接。

21 Stale share (job not found)

这个份额对应的任务从未下发给这个连接，或早已被替换。 重启矿机程序以获取新任务。如仍出现，检查是否只有一个矿机进程在使用这个连接。

22 Duplicate share

同一个证明被发送了两次。 通常是矿机程序在回复丢失后重试。检查矿机与矿池之间的网络。

22 Duplicate share (already credited, sent again in other bytes)

一个已入账的份额以不同的编码再次发送。 正常的重试会发送相同的字节。请更新矿机程序；这类份额会计入封禁。

23 Low difficulty share

份额低于矿池要求的难度。 从密码中删除 d=N 设置，或调高它。如果矿机程序忽略任务难度，请更新它。

23 Low difficulty share (rank penalty)

份额达到了普通目标，但没有满足 Pearl 对其噪声秩的秩惩罚。 把矿机程序更新到支持秩惩罚的版本。这类拒绝不会导致封禁。

20 Invalid proof

Pearl 自身的验证器拒绝了这个证明。 通常是超频不稳定或显存错误。降低频率，更新驱动，然后更新矿机程序。

20 Invalid proof: decode

无法读取这个证明。 更新矿机程序。检查它是否已为 Pearl 配置。

20 Invalid proof: rank

这个证明使用了网络不接受的噪声秩。 使用矿机程序针对 Pearl 的默认设置。

24 Unauthorized worker (banned)

这个连接发送了过多无效份额，已被暂停一段时间。 解决无效份额的原因；暂停会自动结束。

09面向 GPU 所有者#

你的 GPU 可以处理这些请求，同时挖 $PEARL。

你的 GPU 通过我们的矿池挖 $PEARL，同时处理请求。我们的矿工镜像运行模型和我们的节点软件，节点软件从不记录、不存储提示词或补全内容。在运营一批 GPU？告诉我们你的机群情况。

你需要准备

• 一张 NVIDIA Hopper 或 Blackwell GPU（x86_64 或 arm64）。
• NVIDIA 驱动 r580 或更新版本（CUDA 13）。
• 一个有 16 GB 共享内存的容器，以及放我们的镜像和模型权重的磁盘空间。
• 只需出站 HTTPS 和 WebSocket。无需开放入站端口：由节点主动连接我们。

接入一个节点

1. 登录矿工门户，选择添加节点。填写名称、所在国家和模型。你会得到一个注册令牌：一次性使用，24 小时内有效。
2. 在 RunPod、Vast.ai 或你自己的服务器上，用我们发给你的镜像地址运行门户显示的命令。 节点会完成注册，并连接到我们的网关和矿池。 向我们索取镜像地址：介绍一下你的机群。
3. 节点一开始就挖矿。我们审核通过后才开始接客户请求：我们会核实你的身份、节点的测试请求和所在国家。
4. 在付款中添加你的收款地址：Pearl 上的一个 $PEARL 地址。添加之前，你赚到的 $PEARL 会一直记为应付。

   在找钱包？ → Pearl Safe（在新标签页打开）

如果只挖矿、不处理 API 请求，创建令牌时勾选仅矿池（不接 API 流量）。这样节点只赚 $PEARL，无需审核。

费用以我们的矿池条款为准。 区块奖励在 100 次确认后计入。付款规则见付款；$PEARL 预估见GPU 云厂商页面。