> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Lana API - Solana AI 代理

> 通过 HTTP 调用 Solana AI 代理 Lana：询问钱包、代币、交易和价格，并以流式方式接收回答。包含快速入门、API 参考和定价。

Lana API 是一个可通过 HTTP 调用的 Solana AI 代理。你用自然英语向它提问，它会为你查询钱包、代币、交易和价格，然后以流式方式返回回答。

Lana 在 Helius 端执行所有查询，因此你无需定义或运行任何工具。付费 Helius 套餐（Developer 及以上）可使用此服务，并按请求收取固定费用：`lana-thinking` 为 10,000 积分，`lana-fast` 为 2,000 积分。请参阅[定价](#定价)。

该 API 的形式与 Anthropic Messages API 类似，但 Anthropic SDK 无法与它配合使用。请像下面的示例一样，通过普通 HTTP 调用它。请参阅[与 Anthropic Messages API 的差异](#与-anthropic-messages-api-的差异)。

Lana 基于 Anthropic 的 Claude 模型运行。你的问题和对话会发送给 Anthropic 以生成回答。

> [!NOTE]
>
> Lana API 目前在 [Gatekeeper（测试版）](https://www.helius.dev/docs/zh/gatekeeper/overview.md)端点 `beta.helius-rpc.com` 上处于测试阶段。`mainnet.helius-rpc.com` 暂不支持。测试期间可能会添加新的事件和字段。

## 你可以向 Lana 询问什么

你的用户可以询问有关其交易及相关钱包的问题：

* “为什么我上一笔交易失败了？”
* “这次兑换的滑点是多少？”
* “我为这笔交易支付了哪些费用？”
* “这个钱包的资金来自哪里，又转到了哪里？”
* “这个钱包是否与另一个钱包有关联？”
* “这个代币的最大持有者有哪些？”

在 [`extensions.user_context.wallet`](#扩展) 中传入用户的钱包，这样有关“我的”钱包或“我的上一笔交易”的问题就能正常处理。

## 快速入门

**1. Get an API key**

从 [Helius Dashboard](https://dashboard.helius.dev) 复制一个 API 密钥。

**2. Ask a question**

替换 `YOUR_API_KEY`，然后运行：

```bash cURL theme={"system"}
curl -N https://beta.helius-rpc.com/v1/lana/messages \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "model": "lana-thinking",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Who are the largest holders of EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v?" }
    ],
    "extensions": { "read_only": true }
  }'
```

`-N` 会让 curl 在每个事件到达后立即打印它。第一个事件最多可能需要 10 秒才会到达。

**3. Read the answer**

响应是一个[事件](#流式事件)流：

```text theme={"system"}
event: message_start
data: {"type":"message_start","message":{"id":"msg_3f9c...","model":"lana-thinking"}}

event: tool_use
data: {"type":"tool_use","tool_use_id":"toolu_01...","name":"...","input":{"mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}}

event: tool_result
data: {"type":"tool_result","tool_use_id":"toolu_01...","content":"{\"holders\":[..."}

event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"The largest USDC holders are"}}

event: message_end
data: {"type":"message_end","stop_reason":"end_turn","usage":{"input_tokens":91200,"output_tokens":212,"tool_calls":1,"prompt_tokens":46100,"context_window":200000}}
```

回答由按顺序排列的 `text_delta` 分块组成。`lana-thinking` 也可能发送 `thinking_delta` 分块：这是 Lana 的推理过程，因此请将其与回答分开显示，或将其跳过。

### 在代码中读取流

两个示例都会先检查 HTTP 状态，再将正文作为流读取；在 `429` 或 `503` 时等待 `Retry-After`；以流式方式打印回答；并在本轮失败或流提前结束时停止。

```typescript TypeScript theme={"system"}
async function askLana(question: string): Promise<Response> {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch("https://beta.helius-rpc.com/v1/lana/messages", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Api-Key": process.env.HELIUS_API_KEY!,
      },
      body: JSON.stringify({
        model: "lana-thinking",
        stream: true,
        messages: [{ role: "user", content: question }],
        extensions: { read_only: true },
      }),
    });
    if (res.ok) return res;

    // Errors before the stream starts arrive as a normal HTTP response, not as events.
    const body = await res.text();
    const retryable = (res.status === 429 && !body.includes("max usage reached")) || res.status === 503;
    if (!retryable || attempt === 3) throw new Error(`${res.status}: ${body}`);

    const retryAfterSeconds = Number(res.headers.get("Retry-After")) || 5;
    await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1000));
  }
}

const res = await askLana("What is the current price of SOL?");

const reader = res.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";
let finished = false;

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  // Events are separated by a blank line.
  const frames = buffer.split("\n\n");
  buffer = frames.pop() ?? "";

  for (const frame of frames) {
    const data = frame.split("\n").find((line) => line.startsWith("data:"));
    if (!data) continue;
    const event = JSON.parse(data.slice(5));

    switch (event.type) {
      case "content_block_delta":
        if (event.delta.type === "text_delta") process.stdout.write(event.delta.text);
        break;
      case "message_end":
        if (event.stop_reason === "error") throw new Error("Lana turn failed");
        finished = true;
        break;
      case "error":
        throw new Error(`${event.error.type}: ${event.error.message}`);
      // Ignore every other event type, including ones added later.
    }
  }
}

// The connection closed without message_end or error.
if (!finished) throw new Error("Lana stream ended early");
```

```python Python theme={"system"}
import json
import os
import time

import requests

def ask_lana(question: str) -> requests.Response:
    attempt = 1
    while True:
        res = requests.post(
            "https://beta.helius-rpc.com/v1/lana/messages",
            headers={"X-Api-Key": os.environ["HELIUS_API_KEY"]},
            json={
                "model": "lana-thinking",
                "stream": True,
                "messages": [{"role": "user", "content": question}],
                "extensions": {"read_only": True},
            },
            stream=True,
            timeout=(10, 60),  # connect, read; keep the read timeout at 30 seconds or more
        )
        if res.status_code == 200:
            return res

        # Errors before the stream starts arrive as a normal HTTP response, not as events.
        retryable = (
            res.status_code == 429 and "max usage reached" not in res.text
        ) or res.status_code == 503
        if not retryable or attempt == 3:
            raise RuntimeError(f"{res.status_code}: {res.text}")

        time.sleep(int(res.headers.get("Retry-After", 5)))
        attempt += 1

res = ask_lana("What is the current price of SOL?")

finished = False
for line in res.iter_lines(decode_unicode=True):
    if not line or not line.startswith("data:"):
        continue
    event = json.loads(line[5:])

    if event["type"] == "content_block_delta" and event["delta"]["type"] == "text_delta":
        print(event["delta"]["text"], end="", flush=True)
    elif event["type"] == "message_end":
        if event["stop_reason"] == "error":
            raise RuntimeError("Lana turn failed")
        finished = True
    elif event["type"] == "error":
        raise RuntimeError(f'{event["error"]["type"]}: {event["error"]["message"]}')
    # Ignore every other event type, including ones added later.

# The connection closed without message_end or error.
if not finished:
    raise RuntimeError("Lana stream ended early")
```

## 与 Anthropic Messages API 的差异

* 模型为 `lana-thinking` 和 `lana-fast`。
* Lana 运行自己的工具。`tools`、`tool_choice`、`temperature`、`top_p`、`top_k`、`stop_sequences` 和 `metadata` 会返回 `400`。
* `system` 会添加到 Lana 的指令中。
* `max_tokens` 是可选的（默认值和最大值均为 8,192），且图像必须使用 URL。
* 事件有所不同。没有 `content_block_start`、`content_block_stop`、`message_delta` 或 `message_stop`。流以 `message_end` 或 `error` 结束。
* `usage` 增加了 `tool_calls`、`prompt_tokens` 和 `context_window`。`stop_reason` 可以是 `error`。
* `extensions` 仅供 Lana 使用。

## 端点和身份验证

```text theme={"system"}
POST https://beta.helius-rpc.com/v1/lana/messages
```

通过以下任一方式发送 Helius API 密钥：

| 方法 | 示例 |
| - | - |
| `X-Api-Key` 标头（推荐） | `X-Api-Key: YOUR_API_KEY` |
| `api-key` 查询参数 | `https://beta.helius-rpc.com/v1/lana/messages?api-key=YOUR_API_KEY` |

`Authorization: Bearer` 不适用于此端点，并会返回 `401`。

`mainnet.helius-rpc.com` 尚未提供此路由，并会返回 `503`。

在每个请求中发送 `Content-Type: application/json`。

> [!WARNING]
>
> 你的 API 密钥会消耗套餐积分。请从服务器调用 Lana，不要从浏览器或交付给用户的应用中调用。

## 请求正文

正文是一个 JSON 对象。未知字段会被拒绝并返回 `400`，包括 `extensions` 和内容块中的未知字段。

**model** `string` *required*

`lana-thinking` 或 `lana-fast`。请参阅[模型](#模型)。

**messages** `object[]` *required*

对话，最早的消息在前。至少需要一条消息，且最后一条必须具有 `role: "user"`。请参阅[消息](#消息)。

**max\_tokens** `integer` (default: 8192)

Lana 在一个模型步骤中最多可写入的输出 token 数，范围为 `1` 到 `8192`。包含查询的一轮需要多个步骤，因此该轮的 `output_tokens` 总数可能高于 `max_tokens`。低于 2,048 时，`lana-thinking` 不会进行推理。

**stream** `boolean` (default: false)

`true` 会以流式方式返回[事件](#流式事件)。`false` 会在本轮结束时返回一个 [JSON 响应](#非流式响应)。

**system** `string`

额外指令，长度为 1 到 10,000 个字符，例如“用三个要点回答”。这些指令会添加到 Lana 自身的指令中，而不是替代它们。

**extensions** `object`

Lana 专用选项。请参阅[扩展](#扩展)。

### 模型

| | `lana-thinking` | `lana-fast` |
| - | - | - |
| 最适合 | 多步骤分析 | 快速查询和单一事实 |
| 每轮查询步骤 | 最多 20 个 | 最多 4 个 |
| 每轮 Web 搜索 | 最多 3 次 | 最多 2 次 |
| 每轮网页获取 | 最多 2 次 | 最多 2 次 |
| 流式返回推理过程 | 有时会，以 `thinking_delta` 返回。Lana 自行决定何时推理。 | 否 |

仅当 `max_tokens` 为 2048 或更高时，`lana-thinking` 才会进行推理。

### 消息

每条消息都有一个 `role`（`user` 或 `assistant`）和 `content`：

```json theme={"system"}
{ "role": "user", "content": "How many holders does USDC have?" }
```

该 API 不存储对话。要提出后续问题，请重新发送整个对话，并在末尾添加新问题。对于 `assistant` 轮次，只需提供 Lana 的回答文本：

```json theme={"system"}
{
  "model": "lana-thinking",
  "messages": [
    { "role": "user", "content": "What is the USDC mint on Solana?" },
    { "role": "assistant", "content": "The USDC mint is EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v." },
    { "role": "user", "content": "How many holders does it have?" }
  ]
}
```

Lana 只查询出现在对话、自身查询结果或 `extensions.user_context.wallet` 中的地址。

`content` 是非空字符串或非空块数组：

| 块 | 允许用于 | 结构 |
| - | - | - |
| `text` | `user`、`assistant` | `{ "type": "text", "text": "..." }` |
| `image` | `user` | `{ "type": "image", "source": { "type": "url", "url": "https://..." } }` |
| `tool_use` | `assistant` | `{ "type": "tool_use", "id": "...", "name": "...", "input": {} }` |
| `tool_result` | `user` | `{ "type": "tool_result", "tool_use_id": "...", "content": "..." }` |

图像必须使用 URL。不支持 Base64 图像。

你不需要 `tool_use` 或 `tool_result` 块。它们允许你按照 Lana 返回时的形式重放较早轮次中的查询，使 Lana 可以复用这些结果。`tool_result` 还接受一个可选的 `is_error` 布尔值。

### 扩展

所有扩展均为可选。

| 字段 | 类型 | 默认值 | 作用 |
| - | - | - | - |
| `read_only` | boolean | `true` | 移除转账、兑换和代币发行工具。请将其保留为 `true`：此 API 未说明如何展示和签署钱包操作。 |
| `output_format` | `"markdown"` \| `"plain"` | `"markdown"` | `plain` 会指示 Lana 不使用 Markdown，并移除 `{{cite:N}}` 标记。`source` 事件仍会到达。 |
| `include_ui_schema` | boolean | `false` | 允许 UI 组件，以 `ui_block` 和 `ui_schema` 事件返回。 |
| `include_followups` | boolean | `false` | 最多允许 3 个建议的后续问题。 |
| `include_documents` | boolean | `false` | 允许生成可下载的 CSV、JSON 或文本文件，以 `document` 事件返回。 |
| `enable_deep_scan` | boolean | `false` | 允许 Lana 读取某个地址历史记录中的最多 10,000 笔交易（计数和总额最多 50,000 笔），每轮最多扫描 3 次。仅限主网。如果不启用，Lana 每次查询最多读取 100 笔交易。深度扫描更慢，但固定价格相同。它们会计入 5 分钟的轮次限制。 |
| `user_context` | object | 无 | 提问者的信息。见下文。 |
| `attachments` | object\[] | 无 | 最多向最后一条用户消息添加 8 张图像。`messages` 中的 `image` 块不计入此限制。每张图像均为 `{ "url": "https://...", "kind": "image" }`。 |

`include_*` 选项使相应输出成为可能。是否发送由 Lana 决定。

`extensions` 还接受 `progress_context` 和 `transaction_filter_context`。[Orb](https://www.helius.dev/docs/zh/orb.md) 浏览器会使用它们，你不需要使用。

`user_context` 字段：

| 字段 | 类型 | 作用 |
| - | - | - |
| `wallet` | string，最多 128 个字符 | 用户的地址，用于处理“我的钱包”和“我的余额”。 |
| `address_kind` | string，最多 32 个字符 | `"wallet"` 或 `"token"`：说明 `wallet` 的类型。需要 `wallet`。 |
| `time_zone` | string，最多 64 个字符 | IANA 时区，例如 `"America/New_York"`，用于处理“今天”。 |
| `network` | `"mainnet"` \| `"devnet"` | 要查询的网络。默认为主网。 |

## 流式事件

使用 `"stream": true` 时，你会获得状态 `200` 和 `Content-Type: text/event-stream`。每个事件的格式如下：

```text theme={"system"}
event: <type>
data: <json>

```

`data` 是一行 JSON。它的 `type` 与 `event` 名称一致。

`200` 和首批事件会在 Lana 首次响应时（推理、回答文本、查询或文件）到达，最迟不超过 10 秒。在此之前不会发送任何内容，因此在这段时间内失败的请求会获得普通的[错误响应](#流开始之前)，且不会收费。此后，Lana 工作期间每 10 秒会到达一个 `ping`。

将 HTTP 客户端的读取超时设置为至少 30 秒。像 `httpx` 中那样使用默认的 5 秒超时太短：它可能在收到第一个字节之前或两个事件之间到期。

事件按以下顺序到达：

1. `message_start`，始终最先到达。
2. `content_block_delta`、`tool_use`、`tool_result`、`source`、`ui_block`、`document`、`progress_update` 和 `ping` 的任意组合。
3. `ui_schema`，最多一次。
4. `follow_up`，最多一次。
5. 如果本轮完成，则为 `message_end`；如果失败，则为 `error`。它始终是最后一个事件。

可能会添加新的事件类型和字段。忽略无法识别的内容。

| 事件 | 含义 | `data` 示例 |
| - | - | - |
| `message_start` | 本轮已开始。 | `{"type":"message_start","message":{"id":"msg_3f9c...","model":"lana-thinking"}}` |
| `content_block_delta`（`text_delta`） | 回答的一个分块。 | `{"type":"content_block_delta","delta":{"type":"text_delta","text":"SOL is trading at"}}` |
| `content_block_delta`（`thinking_delta`） | 推理过程的一个分块。仅限 `lana-thinking`，且仅在 Lana 进行推理时。 | `{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"I should check..."}}` |
| `tool_use` | Lana 开始了一次查询。 | `{"type":"tool_use","tool_use_id":"toolu_01...","name":"...","input":{"address":"..."}}` |
| `tool_result` | 一次查询已完成。`content` 是最多 500 个字符的预览。`is_error: true` 表示查询失败；请参阅[工具错误](#工具错误)。 | `{"type":"tool_result","tool_use_id":"toolu_01...","content":"{\"balance\":..."}` |
| `source` | Lana 使用的网页。`index` 与回答中的 `{{cite:N}}` 标记对应。`snippet` 是可选的。 | `{"type":"source","index":0,"url":"https://...","title":"...","snippet":"..."}` |
| `progress_update` | 较长轮次中的简短状态行。请将其与回答分开显示。`created_at` 是 Unix 毫秒时间戳。 | `{"type":"progress_update","id":"progress_8a1b...","message":"I'll check this wallet's recent swaps.","created_at":1760436000000}` |
| `ui_block` | 一个 UI 组件。需要 `include_ui_schema`。`tool_use_id` 是可选的。 | `{"type":"ui_block","tool_use_id":"toolu_01...","component":"...","schema":{...}}` |
| `document` | 可下载文件。需要 `include_documents`。`format` 为 `csv`、`json` 或 `txt`。`tool_use_id` 和 `description` 是可选的。 | `{"type":"document","filename":"usdc-holders","format":"csv","content":"owner,amount\n...","description":"..."}` |
| `ui_schema` | 以单个树结构表示的所有 UI 组件。需要 `include_ui_schema`。 | `{"type":"ui_schema","schema":{...}}` |
| `follow_up` | 建议的后续问题。需要 `include_followups`。 | `{"type":"follow_up","suggestions":["Show the top 10 holders' recent transfers"]}` |
| `message_end` | 本轮已完成。请参阅[停止原因](#停止原因)和[用量](#用量)。 | `{"type":"message_end","stop_reason":"end_turn","usage":{"input_tokens":91200,"output_tokens":212,"tool_calls":1,"prompt_tokens":46100,"context_window":200000}}` |
| `error` | 本轮失败。请参阅[错误](#错误)。 | `{"type":"error","error":{"type":"overloaded_error","message":"Lana is temporarily overloaded. Retry the request shortly."}}` |
| `ping` | 每 10 秒发送一次的心跳。忽略它。 | `{"type":"ping"}` |

展示流的提示：

* 仅将 `tool_use` 用于进度指示器。工具名称和输入可能会变化。
* 使用 `"markdown"` 输出时，将每个 `{{cite:N}}` 转换为指向具有相应 `index` 的 `source` 的链接，或将其移除。
* `ui_block` 和 `ui_schema` 携带相同的组件。Lana 可能只发送 `ui_schema`，因此如果收到 `ui_block` 事件，则显示它们；否则渲染 `ui_schema`。
* Web 搜索会发送一个包含文本 `Web search completed.` 或 `Web fetch completed.` 的 `tool_result`。页面以 `source` 事件到达。

### 工具错误

查询失败不会导致本轮失败。Lana 会绕过该问题，你无需重试。`tool_result` 包含 `is_error: true`，而 `content` 是一个 JSON，其中包含简短消息和 `code`：

```json theme={"system"}
{ "error": "the data service failed (502)", "code": "upstream_unavailable" }
```

> [accordion] Tool error codes
>
> | `code` | 含义 |
> | - | - |
> | `invalid_input` | 查询参数无效。 |
> | `not_found` | 此查询没有数据。某些查询会将缺失项报告为正常结果，例如 `{"found": false}`。 |
> | `rejected` | 数据服务拒绝了该查询。 |
> | `rate_limited` | 数据服务正在限流。 |
> | `upstream_timeout` | 数据服务超时。 |
> | `upstream_unavailable` | 数据服务失败。 |
> | `upstream_error` | Helius 数据工具失败。 |
> | `timeout` | 查询超时。 |
> | `tool_failed` | 查询无法给出答案。`error` 会说明原因。 |
> | `internal` | 发生意外故障。 |
>
> 可能会添加新代码。将未知代码视为 `internal`。

### 停止原因

`stop_reason` 位于 `message_end` 和 JSON 响应中：

| 值 | 含义 |
| - | - |
| `end_turn` | Lana 已完成回答。 |
| `max_tokens` | 回答达到了 `max_tokens`，可能已被截断。 |
| `tool_use` | 本轮在查询步骤结束，通常是因为达到了步骤限制。 |
| `error` | 本轮失败。回答不完整。 |

### 用量

| 字段 | 含义 |
| - | - |
| `input_tokens` | 整轮的输入 token 数。 |
| `output_tokens` | 整轮的输出 token 数。 |
| `tool_calls` | 本轮执行的查询数，包括部分从未以 `tool_use` 形式出现的查询。 |
| `prompt_tokens` | 最后一个模型步骤中的输入 token 数。可用于了解上下文已使用多少。 |
| `context_window` | 模型的上下文窗口，目前为 `200000`。 |

Lana 自身的指令和查询工具在每个模型步骤中约占用 45,000 个 token，因此即使问题很短，`input_tokens` 也会很高。定价按请求计算，因此 token 数不会改变你支付的费用。

## 非流式响应

使用 `"stream": false` 时，本轮结束后你会获得一个 JSON 对象：

```json theme={"system"}
{
  "id": "msg_3f9c...",
  "type": "message",
  "role": "assistant",
  "model": "lana-thinking",
  "content": [
    { "type": "tool_use", "id": "toolu_01...", "name": "...", "input": { "mint": "So11111111111111111111111111111111111111112" } },
    { "type": "tool_result", "tool_use_id": "toolu_01...", "content": "{\"price\":..." },
    { "type": "text", "text": "SOL is trading at ..." }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 90800, "output_tokens": 96, "tool_calls": 1, "prompt_tokens": 45600, "context_window": 200000 }
}
```

回答由按顺序连接的 `text` 块组成。推理和 `progress_update` 仅以流式方式提供。

以下字段仅在有值时出现：

| 字段 | 出现条件 |
| - | - |
| `ui_schema` | `include_ui_schema` 已开启，且有内容可显示。 |
| `documents` | `include_documents` 已开启，且 Lana 生成了文件。字段与 `document` 事件相同，但不包含 `type`。 |
| `follow_up` | `include_followups` 已开启，且 Lana 建议了问题。值为字符串数组。 |
| `sources` | Lana 使用了网页。字段与 `source` 事件相同，但不包含 `type`。 |
| `error` | `stop_reason` 为 `"error"`。值为包含 `type` 和 `message` 的对象。 |

## 错误

### 流开始之前

在响应开始前失败的请求会返回非 `200` 状态和普通错误正文，即使使用 `"stream": true` 也是如此。不会发送任何事件，也不会收费。将正文作为流读取之前，请检查 HTTP 状态。

使用 `"stream": true` 时，响应会在 Lana 首次响应时开始，最迟不超过 10 秒。在此之前失败的轮次（例如模型过载或对话过长）也属于这种情况。

| 状态 | 原因 | 处理方式 |
| - | - | - |
| `400` | 正文无效，例如模型未知或 `max_tokens` 超过 8,192。`message` 会列出每个无效字段。 | 修复请求。 |
| `401` | API 密钥缺失或无效，或通过 `Authorization: Bearer` 发送。 | 通过 `X-Api-Key` 或 `?api-key=` 发送密钥。 |
| `403` | 你的套餐不包含 Lana（Free 套餐），或密钥的访问设置阻止了它。 | 升级到 Developer 或更高套餐，或在 [Helius Dashboard](https://dashboard.helius.dev) 中检查密钥的访问设置。 |
| `400`，正文为 `Bad Request` | 正文超过 10 MB。Gatekeeper 会在 Lana 看到正文之前拒绝它。 | 发送更小的请求，例如减少消息数量或缩短消息。 |
| `429`，正文为 `Too Many Requests` | 超过了套餐的[速率限制](https://www.helius.dev/docs/zh/billing/rate-limits.md)。 | 按照 `Retry-After` 标头等待（1 秒），然后重试。 |
| `429`，正文为 `max usage reached` | 项目积分已用完。 | 添加积分或升级套餐。此时没有 `Retry-After`；在完成上述操作前，重试仍会失败。 |
| `429`，`error.type` 为 `rate_limit_error` | 你的项目已有大约 3 个 Lana 请求正在运行。 | 按照 `Retry-After` 标头等待（5 秒），然后重试。 |
| `503` | Lana 已满载或正在重启。 | 按照 `Retry-After` 标头等待（满载时 5 秒，重启时 30 秒），然后重试。 |
| `400`，`error.type` 为 `context_overflow` | 对话无法容纳在上下文窗口中。 | 删除较早的消息，或提出范围更小的问题。 |
| `529`，`error.type` 为 `overloaded_error` | 模型过载。`529` 是 Anthropic 用于此情况的状态；某些 HTTP 客户端无法识别它，因此请像处理 `503` 一样处理。 | 使用指数退避重试。 |
| `500`、`502`、`504` | 本轮在产生首个输出之前因 `api_error`、`tool_error` 或 `timeout_error` 而失败。 | 按照[错误类型](#错误类型)中的说明处理。 |

前两个 `429` 来自你的套餐，响应正文会说明触发了哪一个。第三个来自 Lana，并具有 JSON 正文。

如果收到没有 `Retry-After` 标头的 `429` 或 `503`，请等待几秒后再重试。

Lana 自身的错误（无效正文或 `context_overflow` 对应的 `400`、带 `rate_limit_error` 的 `429`、`500`、`502`、`503`、`504` 和 `529`）具有 JSON 正文。来自 Gatekeeper 的错误（`401`、`403`、正文过大时的 `400`，以及套餐导致的 `429`）是纯文本。请根据 `error.type` 分支处理，而不是 `message`：

```json theme={"system"}
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: max_tokens must be <= 8192"
  }
}
```

### 流开始之后

此时状态已经是 `200`，因此失败会以最终的 `error` 事件结束流，或以 `message_end` 和 `stop_reason: "error"` 结束。该 `message_end` 不包含 `error` 对象；请像处理 `api_error` 一样处理。此前的任何回答文本都不完整。将其标记为不完整，或将其丢弃。

### 不使用流式传输

使用 `"stream": false` 时，失败的轮次会返回以下任一结果：

* 如果本轮生成了任何内容（包括查询），则返回 `200`、`stop_reason: "error"` 和一个 `error` 对象。始终检查 `stop_reason`。
* 如果本轮未生成任何内容，则返回 JSON 错误正文。状态与 `error.type` 对应：`context_overflow` 对应 `400`，`api_error` 对应 `500`，`tool_error` 对应 `502`，`timeout_error` 对应 `504`，`overloaded_error` 对应 `529`（这是 Anthropic 用于模型过载的状态；某些 HTTP 客户端无法识别它，因此请像处理 `503` 一样处理）。这些请求不会收费。按照[错误类型](#错误类型)中的说明处理。

### 错误类型

| `error.type` | 含义 | 处理方式 |
| - | - | - |
| `invalid_request_error` | 请求无效。 | 修复请求。 |
| `context_overflow` | 对话和查询结果无法容纳在上下文窗口中。 | 删除较早的消息，或提出范围更小的问题。 |
| `overloaded_error` | 模型过载。 | 使用指数退避重试。 |
| `timeout_error` | 本轮超时。 | 提出范围更小的问题，或使用 `lana-fast`。 |
| `tool_error` | Lana 依赖的查询服务失败。 | 使用退避策略重试。 |
| `rate_limit_error` | 你的项目约有 3 个请求正在运行。 | 按照 `Retry-After` 标头等待后重试。 |
| `api_error` | Lana 在 Helius 端发生故障，或已满载。 | 使用退避策略重试。 |

将任何其他类型视为 `api_error`。

## 限制

| 限制 | 值 |
| - | - |
| `max_tokens` | 1 到 8,192（默认 8,192） |
| `system` | 最多 10,000 个字符 |
| `extensions.attachments` | 最多 8 张图像 |
| 请求正文 | 10 MB |
| 上下文窗口 | 200,000 个 token，其中约 80%（扣除 `max_tokens` 后）用于对话和查询结果 |
| 轮次时长 | 5 分钟 |
| 速率限制 | 你套餐的 DAS & Enhanced APIs 速率限制。请参阅[速率限制](https://www.helius.dev/docs/zh/billing/rate-limits.md#lana-api)。 |
| 并发请求 | 每个项目大约 3 个。额外请求可能会收到 `429`，直到其中一个请求完成。 |

当一轮接近 5 分钟时，Lana 会停止查询，并根据已有信息回答。较长的轮次通常会以说明缺失内容的部分回答结束，而不是超时。

使用流式传输时，请将 HTTP 客户端的读取超时设置为至少 30 秒。第一个字节最多可能需要 10 秒才会到达，之后每 10 秒会到达一个 `ping`，因此如果间隔长得多，说明连接已断开。像 `httpx` 中那样使用默认的 5 秒超时太短。不使用流式传输时，在本轮结束之前不会收到任何内容，因此请将读取超时设置为 5 分钟以上。

如果断开连接，Lana 会停止本轮。流已经开始的请求仍会收费。

当 Lana 已满载时，新请求会在流式传输任何内容之前收到 `503`。这些请求不会收费。按照 `Retry-After` 标头等待后重试。

## 定价

每个请求按固定价格收费，价格取决于模型：

| 模型 | 每个请求的积分 |
| - | - |
| `lana-thinking` | **10,000** |
| `lana-fast` | **2,000** |

流式和非流式请求的价格相同，所有付费套餐（Developer 及以上）的价格也相同。Free 套餐无法使用 Lana。

积分来自你的套餐。请参阅[积分](https://www.helius.dev/docs/zh/billing/credits.md#lana-api-积分)。

### 收费范围

无论是否使用流式传输，也无论本轮如何结束，只要请求获得 HTTP `200`，就会收费。在响应开始前失败的请求会获得其他状态，且不收费。

* 如果流式轮次以 `error` 事件失败，或你在其开始后断开连接，则会收费：因为状态已经是 `200`。
* 在本轮开始前被拒绝的请求（`400`、`401`、`403`、`429`、`503`）不收费。
* 在响应开始前失败的轮次（`400`、`5xx`），无论是否使用流式传输，均不收费。

## 更多示例

### 设置语气和用户的钱包

```bash cURL theme={"system"}
curl https://beta.helius-rpc.com/v1/lana/messages \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "model": "lana-thinking",
    "system": "Answer in at most three bullet points.",
    "messages": [{ "role": "user", "content": "How did my wallet do this week?" }],
    "extensions": {
      "read_only": true,
      "user_context": {
        "wallet": "YOUR_WALLET_ADDRESS",
        "address_kind": "wallet",
        "time_zone": "America/New_York"
      }
    }
  }'
```

### 扫描钱包的完整历史记录

```bash cURL theme={"system"}
curl -N https://beta.helius-rpc.com/v1/lana/messages \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "model": "lana-thinking",
    "stream": true,
    "messages": [{ "role": "user", "content": "Over the last 5,000 transactions of YOUR_WALLET_ADDRESS, which programs did it use most?" }],
    "extensions": { "read_only": true, "enable_deep_scan": true }
  }'
```

### 获取 UI 组件、后续问题和 CSV

```bash cURL theme={"system"}
curl https://beta.helius-rpc.com/v1/lana/messages \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "model": "lana-thinking",
    "messages": [{ "role": "user", "content": "Export the top holders of So11111111111111111111111111111111111111112 as a CSV" }],
    "extensions": {
      "read_only": true,
      "include_ui_schema": true,
      "include_followups": true,
      "include_documents": true
    }
  }'
```

## 后续步骤

> [card] [API Reference](https://www.helius.dev/docs/zh/api-reference/lana/messages.md)
>
> 请求和响应架构，并提供交互式测试工具。

> [card] [Rate Limits](https://www.helius.dev/docs/zh/billing/rate-limits.md#lana-api)
>
> Lana 各套餐的速率限制。

> [card] [Credits](https://www.helius.dev/docs/zh/billing/credits.md#lana-api-积分)
>
> Lana 请求如何使用你的套餐积分。

> [card] [Contact Support](https://www.helius.dev/docs/zh/support/contact-support)
>
> 通过 Discord、聊天或电子邮件获取帮助。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.