> ## 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 - Tác nhân AI Solana

> Gọi Lana, một tác nhân AI Solana, qua HTTP: hỏi về ví, token, giao dịch và giá, đồng thời nhận câu trả lời dưới dạng luồng. Hướng dẫn bắt đầu nhanh, tài liệu tham khảo API và giá.

Lana API là một tác nhân AI Solana mà bạn gọi qua HTTP. Bạn gửi câu hỏi bằng tiếng Anh thông thường, Lana sẽ tra cứu ví, token, giao dịch và giá, sau đó truyền phát câu trả lời về.

Lana thực hiện mọi lượt tra cứu ở phía Helius, vì vậy bạn không cần định nghĩa hoặc chạy bất kỳ công cụ nào. Dịch vụ có trên các gói Helius trả phí (Developer trở lên), với mức giá cố định cho mỗi yêu cầu: 10.000 tín dụng cho `lana-thinking` và 2.000 tín dụng cho `lana-fast`. Xem [Giá](#giá).

API có cấu trúc giống Anthropic Messages API, nhưng các SDK Anthropic không hoạt động với API này. Hãy gọi API qua HTTP thuần như trong các ví dụ bên dưới. Xem [Điểm khác biệt so với Anthropic Messages API](#điểm-khác-biệt-so-với-anthropic-messages-api).

Lana chạy trên các mô hình Claude của Anthropic. Câu hỏi và cuộc trò chuyện của bạn được gửi đến Anthropic để tạo câu trả lời.

> [!NOTE]
>
> Lana API đang ở giai đoạn beta trên endpoint [Gatekeeper (Beta)](https://www.helius.dev/docs/vi/gatekeeper/overview.md), `beta.helius-rpc.com`. API này chưa có trên `mainnet.helius-rpc.com`. Các sự kiện và trường mới có thể được thêm trong giai đoạn beta.

## Bạn có thể hỏi Lana những gì

Các câu hỏi mà người dùng có thể đặt về giao dịch của họ và những ví mà họ tương tác:

* "Tại sao giao dịch gần nhất của tôi thất bại?"
* "Tôi đã chịu mức trượt giá bao nhiêu trong lần hoán đổi này?"
* "Tôi đã trả những khoản phí nào cho giao dịch này?"
* "Ví này nhận tiền từ đâu và đã gửi tiền đến đâu?"
* "Ví này có liên kết với ví kia không?"
* "Ai là những người nắm giữ nhiều token này nhất?"

Truyền ví của người dùng trong [`extensions.user_context.wallet`](#phần-mở-rộng) để các câu hỏi về ví "của tôi" hoặc "giao dịch gần nhất của tôi" hoạt động.

## Bắt đầu nhanh

**1. Get an API key**

Sao chép khóa API từ [Helius Dashboard](https://dashboard.helius.dev).

**2. Ask a question**

Thay thế `YOUR_API_KEY` rồi chạy:

```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` khiến curl in từng sự kiện ngay khi nhận được. Sự kiện đầu tiên có thể mất tối đa 10 giây mới đến.

**3. Read the answer**

Phản hồi là một luồng [sự kiện](#sự-kiện-truyền-phát):

```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}}
```

Câu trả lời là các đoạn `text_delta` theo đúng thứ tự. `lana-thinking` cũng có thể gửi các đoạn `thinking_delta`: đây là phần suy luận của Lana, vì vậy hãy hiển thị riêng với câu trả lời hoặc bỏ qua.

### Đọc luồng trong mã

Cả hai ví dụ đều kiểm tra trạng thái HTTP trước khi đọc phần thân dưới dạng luồng, chờ `Retry-After` khi gặp `429` hoặc `503`, in câu trả lời trong lúc truyền phát và dừng nếu lượt xử lý thất bại hoặc luồng kết thúc sớm.

```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")
```

## Điểm khác biệt so với Anthropic Messages API

* Các mô hình là `lana-thinking` và `lana-fast`.
* Lana chạy các công cụ riêng. `tools`, `tool_choice`, `temperature`, `top_p`, `top_k`, `stop_sequences` và `metadata` trả về `400`.
* `system` được thêm vào chỉ dẫn của Lana.
* `max_tokens` là tùy chọn (mặc định và tối đa là 8.192), đồng thời hình ảnh phải là URL.
* Các sự kiện khác nhau. Không có `content_block_start`, `content_block_stop`, `message_delta` hoặc `message_stop`. Luồng kết thúc bằng `message_end` hoặc `error`.
* `usage` bổ sung `tool_calls`, `prompt_tokens` và `context_window`. `stop_reason` có thể là `error`.
* `extensions` chỉ dành cho Lana.

## Endpoint và xác thực

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

Gửi khóa API Helius theo một trong các cách sau:

| Phương thức | Ví dụ |
| - | - |
| Header `X-Api-Key` (khuyến nghị) | `X-Api-Key: YOUR_API_KEY` |
| Tham số truy vấn `api-key` | `https://beta.helius-rpc.com/v1/lana/messages?api-key=YOUR_API_KEY` |

`Authorization: Bearer` không hoạt động trên endpoint này và trả về `401`.

`mainnet.helius-rpc.com` chưa cung cấp tuyến này và trả về `503`.

Gửi `Content-Type: application/json` trong mọi yêu cầu.

> [!WARNING]
>
> Khóa API sử dụng tín dụng trong gói của bạn. Hãy gọi Lana từ máy chủ, không phải từ trình duyệt hoặc ứng dụng mà bạn phân phối cho người dùng.

## Phần thân yêu cầu

Phần thân là một đối tượng JSON. Các trường không xác định sẽ bị từ chối với `400`, bao gồm cả các trường không xác định bên trong `extensions` và các khối nội dung.

**model** `string` *required*

`lana-thinking` hoặc `lana-fast`. Xem [Mô hình](#mô-hình).

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

Cuộc trò chuyện, từ cũ nhất đến mới nhất. Cần có ít nhất một tin nhắn và tin nhắn cuối cùng phải có `role: "user"`. Xem [Tin nhắn](#tin-nhắn).

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

Số token đầu ra tối đa mà Lana có thể ghi trong một bước mô hình, từ `1` đến `8192`. Một lượt có tra cứu cần nhiều bước, vì vậy tổng `output_tokens` của lượt có thể cao hơn `max_tokens`. Khi dưới 2.048, `lana-thinking` không suy luận.

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

`true` truyền phát [sự kiện](#sự-kiện-truyền-phát). `false` trả về một [phản hồi JSON](#phản-hồi-không-truyền-phát) khi lượt kết thúc.

**system** `string`

Chỉ dẫn bổ sung, dài từ 1 đến 10.000 ký tự, chẳng hạn như "Trả lời bằng ba dấu đầu dòng." Các chỉ dẫn này được thêm vào chỉ dẫn riêng của Lana chứ không thay thế chúng.

**extensions** `object`

Các tùy chọn chỉ dành cho Lana. Xem [Phần mở rộng](#phần-mở-rộng).

### Mô hình

| | `lana-thinking` | `lana-fast` |
| - | - | - |
| Phù hợp nhất cho | Phân tích nhiều bước | Tra cứu nhanh và thông tin đơn lẻ |
| Số bước tra cứu mỗi lượt | Tối đa 20 | Tối đa 4 |
| Số lượt tìm kiếm web mỗi lượt | Tối đa 3 | Tối đa 2 |
| Số lượt tải trang web mỗi lượt | Tối đa 2 | Tối đa 2 |
| Truyền phát phần suy luận | Đôi khi, dưới dạng `thinking_delta`. Lana quyết định khi nào cần suy luận. | Không |

`lana-thinking` chỉ suy luận khi `max_tokens` từ 2048 trở lên.

### Tin nhắn

Mỗi tin nhắn có một `role` (`user` hoặc `assistant`) và `content`:

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

API không lưu trữ cuộc trò chuyện. Để đặt câu hỏi tiếp theo, hãy gửi lại toàn bộ cuộc trò chuyện với câu hỏi mới ở cuối. Văn bản câu trả lời của Lana là đủ cho các lượt `assistant`:

```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 chỉ tra cứu các địa chỉ xuất hiện trong cuộc trò chuyện, trong kết quả tra cứu của chính Lana hoặc trong `extensions.user_context.wallet`.

`content` là một chuỗi không rỗng hoặc một mảng khối không rỗng:

| Khối | Được phép trong | Cấu trúc |
| - | - | - |
| `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": "..." }` |

Hình ảnh phải là URL. Hình ảnh Base64 không được hỗ trợ.

Bạn không cần các khối `tool_use` hoặc `tool_result`. Chúng cho phép phát lại các lượt tra cứu từ một lượt trước đó theo đúng dữ liệu Lana đã trả về, để Lana có thể tái sử dụng các kết quả đó. `tool_result` cũng nhận một giá trị boolean `is_error` tùy chọn.

### Phần mở rộng

Tất cả phần mở rộng đều là tùy chọn.

| Trường | Kiểu | Mặc định | Chức năng |
| - | - | - | - |
| `read_only` | boolean | `true` | Loại bỏ các công cụ chuyển, hoán đổi và khởi chạy token. Hãy giữ là `true`: API này không ghi lại quy trình hiển thị và ký các thao tác ví. |
| `output_format` | `"markdown"` \| `"plain"` | `"markdown"` | `plain` yêu cầu Lana không dùng Markdown và loại bỏ các dấu `{{cite:N}}`. Các sự kiện `source` vẫn được gửi đến. |
| `include_ui_schema` | boolean | `false` | Cho phép các thành phần UI dưới dạng sự kiện `ui_block` và `ui_schema`. |
| `include_followups` | boolean | `false` | Cho phép tối đa 3 câu hỏi tiếp theo được đề xuất. |
| `include_documents` | boolean | `false` | Cho phép tải xuống tệp CSV, JSON hoặc văn bản dưới dạng sự kiện `document`. |
| `enable_deep_scan` | boolean | `false` | Cho phép Lana đọc tối đa 10.000 giao dịch trong lịch sử của một địa chỉ (50.000 để đếm và tính tổng), với tối đa 3 lượt quét mỗi lượt. Chỉ dành cho mainnet. Nếu không có tùy chọn này, Lana đọc tối đa 100 giao dịch mỗi lượt tra cứu. Quét sâu chậm hơn nhưng có cùng mức giá cố định. Thời gian quét được tính vào giới hạn 5 phút của lượt. |
| `user_context` | object | không có | Người đang đặt câu hỏi. Xem bên dưới. |
| `attachments` | object\[] | không có | Tối đa 8 hình ảnh được thêm vào tin nhắn cuối cùng của người dùng. Các khối `image` trong `messages` không được tính vào giới hạn này. Mỗi hình ảnh là `{ "url": "https://...", "kind": "image" }`. |

Các tùy chọn `include_*` cho phép tạo đầu ra. Lana quyết định có gửi đầu ra đó hay không.

`extensions` cũng chấp nhận `progress_context` và `transaction_filter_context`. Trình khám phá [Orb](https://www.helius.dev/docs/vi/orb.md) sử dụng chúng, còn bạn không cần chúng.

Các trường `user_context`:

| Trường | Kiểu | Chức năng |
| - | - | - |
| `wallet` | chuỗi, tối đa 128 ký tự | Địa chỉ của người dùng, để "ví của tôi" và "số dư của tôi" hoạt động. |
| `address_kind` | chuỗi, tối đa 32 ký tự | `"wallet"` hoặc `"token"`: cho biết `wallet` là gì. Yêu cầu `wallet`. |
| `time_zone` | chuỗi, tối đa 64 ký tự | Múi giờ IANA, chẳng hạn như `"America/New_York"`, để "hôm nay" hoạt động. |
| `network` | `"mainnet"` \| `"devnet"` | Mạng cần tra cứu. Mặc định là mainnet. |

## Sự kiện truyền phát

Với `"stream": true`, bạn nhận được trạng thái `200` và `Content-Type: text/event-stream`. Mỗi sự kiện có dạng như sau:

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

```

`data` là một dòng JSON. `type` của dòng này khớp với tên `event`.

`200` và các sự kiện đầu tiên đến khi Lana phản hồi lần đầu (phần suy luận, văn bản câu trả lời, một lượt tra cứu hoặc một tệp), hoặc chậm nhất sau 10 giây. Cho đến lúc đó, không có gì được gửi, vì vậy yêu cầu thất bại trong khoảng thời gian này sẽ nhận [phản hồi lỗi](#trước-khi-luồng-bắt-đầu) thông thường và không bị tính phí. Sau đó, một `ping` sẽ đến mỗi 10 giây trong khi Lana làm việc.

Đặt thời gian chờ đọc của máy khách HTTP thành 30 giây trở lên. Giá trị mặc định 5 giây như trong `httpx` là quá ngắn: thời gian chờ có thể hết trước byte đầu tiên hoặc giữa hai sự kiện.

Các sự kiện đến theo thứ tự sau:

1. `message_start`, luôn đến đầu tiên.
2. Bất kỳ tổ hợp nào của `content_block_delta`, `tool_use`, `tool_result`, `source`, `ui_block`, `document`, `progress_update` và `ping`.
3. `ui_schema`, tối đa một lần.
4. `follow_up`, tối đa một lần.
5. `message_end` nếu lượt hoàn tất hoặc `error` nếu lượt thất bại. Đây luôn là sự kiện cuối cùng.

Các loại sự kiện và trường mới có thể được thêm vào. Hãy bỏ qua những loại hoặc trường bạn không nhận ra.

| Sự kiện | Ý nghĩa | `data` mẫu |
| - | - | - |
| `message_start` | Lượt đã bắt đầu. | `{"type":"message_start","message":{"id":"msg_3f9c...","model":"lana-thinking"}}` |
| `content_block_delta` (`text_delta`) | Một đoạn của câu trả lời. | `{"type":"content_block_delta","delta":{"type":"text_delta","text":"SOL is trading at"}}` |
| `content_block_delta` (`thinking_delta`) | Một đoạn suy luận. Chỉ dành cho `lana-thinking` khi Lana suy luận. | `{"type":"content_block_delta","delta":{"type":"thinking_delta","thinking":"I should check..."}}` |
| `tool_use` | Lana đã bắt đầu một lượt tra cứu. | `{"type":"tool_use","tool_use_id":"toolu_01...","name":"...","input":{"address":"..."}}` |
| `tool_result` | Một lượt tra cứu đã hoàn tất. `content` là bản xem trước dài tối đa 500 ký tự. `is_error: true` nghĩa là lượt tra cứu thất bại; xem [Lỗi công cụ](#lỗi-công-cụ). | `{"type":"tool_result","tool_use_id":"toolu_01...","content":"{\"balance\":..."}` |
| `source` | Một trang web mà Lana đã sử dụng. `index` khớp với các dấu `{{cite:N}}` trong câu trả lời. `snippet` là tùy chọn. | `{"type":"source","index":0,"url":"https://...","title":"...","snippet":"..."}` |
| `progress_update` | Một dòng trạng thái ngắn trong một lượt dài. Hiển thị riêng với câu trả lời. `created_at` là thời gian Unix tính bằng mili giây. | `{"type":"progress_update","id":"progress_8a1b...","message":"I'll check this wallet's recent swaps.","created_at":1760436000000}` |
| `ui_block` | Một thành phần UI. Yêu cầu `include_ui_schema`. `tool_use_id` là tùy chọn. | `{"type":"ui_block","tool_use_id":"toolu_01...","component":"...","schema":{...}}` |
| `document` | Một tệp có thể tải xuống. Yêu cầu `include_documents`. `format` là `csv`, `json` hoặc `txt`. `tool_use_id` và `description` là tùy chọn. | `{"type":"document","filename":"usdc-holders","format":"csv","content":"owner,amount\n...","description":"..."}` |
| `ui_schema` | Tất cả thành phần UI dưới dạng một cây. Yêu cầu `include_ui_schema`. | `{"type":"ui_schema","schema":{...}}` |
| `follow_up` | Các câu hỏi tiếp theo được đề xuất. Yêu cầu `include_followups`. | `{"type":"follow_up","suggestions":["Show the top 10 holders' recent transfers"]}` |
| `message_end` | Lượt đã hoàn tất. Xem [Lý do dừng](#lý-do-dừng) và [Mức sử dụng](#mức-sử-dụng). | `{"type":"message_end","stop_reason":"end_turn","usage":{"input_tokens":91200,"output_tokens":212,"tool_calls":1,"prompt_tokens":46100,"context_window":200000}}` |
| `error` | Lượt đã thất bại. Xem [Lỗi](#lỗi). | `{"type":"error","error":{"type":"overloaded_error","message":"Lana is temporarily overloaded. Retry the request shortly."}}` |
| `ping` | Một tín hiệu duy trì kết nối mỗi 10 giây. Hãy bỏ qua. | `{"type":"ping"}` |

Mẹo hiển thị luồng:

* Chỉ sử dụng `tool_use` cho chỉ báo tiến trình. Tên công cụ và dữ liệu đầu vào có thể thay đổi.
* Với đầu ra `"markdown"`, hãy chuyển mỗi `{{cite:N}}` thành liên kết đến `source` có `index` tương ứng hoặc loại bỏ nó.
* `ui_block` và `ui_schema` chứa cùng các thành phần. Lana có thể chỉ gửi `ui_schema`, vì vậy hãy hiển thị các sự kiện `ui_block` nếu chúng đến; nếu không, hãy kết xuất `ui_schema`.
* Các lượt tìm kiếm web gửi một `tool_result` với văn bản `Web search completed.` hoặc `Web fetch completed.`. Các trang được gửi đến dưới dạng sự kiện `source`.

### Lỗi công cụ

Một lượt tra cứu thất bại không làm cả lượt xử lý thất bại. Lana sẽ xử lý theo cách khác và bạn không cần thử lại. `tool_result` có `is_error: true`, còn `content` là JSON chứa một thông báo ngắn và một `code`:

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

> [accordion] Tool error codes
>
> | `code` | Ý nghĩa |
> | - | - |
> | `invalid_input` | Các đối số của lượt tra cứu không hợp lệ. |
> | `not_found` | Không có dữ liệu cho lượt tra cứu này. Một số lượt tra cứu báo cáo mục bị thiếu như một kết quả bình thường, chẳng hạn như `{"found": false}`. |
> | `rejected` | Dịch vụ dữ liệu đã từ chối lượt tra cứu. |
> | `rate_limited` | Dịch vụ dữ liệu đang giới hạn tốc độ. |
> | `upstream_timeout` | Dịch vụ dữ liệu đã hết thời gian chờ. |
> | `upstream_unavailable` | Dịch vụ dữ liệu đã gặp lỗi. |
> | `upstream_error` | Một công cụ dữ liệu Helius đã gặp lỗi. |
> | `timeout` | Lượt tra cứu đã hết thời gian. |
> | `tool_failed` | Lượt tra cứu không thể trả lời. `error` cho biết lý do. |
> | `internal` | Đã xảy ra lỗi ngoài dự kiến. |
>
> Các mã mới có thể được thêm vào. Hãy xử lý mã không xác định như `internal`.

### Lý do dừng

`stop_reason` nằm trong `message_end` và phản hồi JSON:

| Giá trị | Ý nghĩa |
| - | - |
| `end_turn` | Lana đã hoàn tất câu trả lời. |
| `max_tokens` | Câu trả lời đã đạt `max_tokens` và có thể bị cắt. |
| `tool_use` | Lượt kết thúc tại một bước tra cứu, thường là khi đạt giới hạn bước. |
| `error` | Lượt đã thất bại. Câu trả lời chưa hoàn chỉnh. |

### Mức sử dụng

| Trường | Ý nghĩa |
| - | - |
| `input_tokens` | Token đầu vào cho toàn bộ lượt. |
| `output_tokens` | Token đầu ra cho toàn bộ lượt. |
| `tool_calls` | Các lượt tra cứu đã chạy trong lượt, bao gồm một số lượt không bao giờ xuất hiện dưới dạng `tool_use`. |
| `prompt_tokens` | Token đầu vào trong bước mô hình cuối cùng. Dùng giá trị này để xem ngữ cảnh đã đầy đến mức nào. |
| `context_window` | Cửa sổ ngữ cảnh của mô hình, hiện là `200000`. |

Các chỉ dẫn và công cụ tra cứu riêng của Lana sử dụng khoảng 45.000 token trong mỗi bước mô hình, vì vậy `input_tokens` vẫn cao ngay cả với câu hỏi ngắn. Giá được tính theo yêu cầu nên số lượng token không làm thay đổi số tiền bạn trả.

## Phản hồi không truyền phát

Với `"stream": false`, bạn nhận được một đối tượng JSON khi lượt kết thúc:

```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 }
}
```

Câu trả lời là các khối `text` được nối theo thứ tự. Phần suy luận và `progress_update` chỉ có khi truyền phát.

Các trường này chỉ xuất hiện khi có giá trị:

| Trường | Khi nào |
| - | - |
| `ui_schema` | `include_ui_schema` được bật và có nội dung để hiển thị. |
| `documents` | `include_documents` được bật và Lana đã tạo tệp. Có cùng các trường như sự kiện `document` nhưng không có `type`. |
| `follow_up` | `include_followups` được bật và Lana đã đề xuất câu hỏi. Một mảng chuỗi. |
| `sources` | Lana đã sử dụng các trang web. Có cùng các trường như sự kiện `source` nhưng không có `type`. |
| `error` | `stop_reason` là `"error"`. Một đối tượng có `type` và `message`. |

## Lỗi

### Trước khi luồng bắt đầu

Yêu cầu thất bại trước khi phản hồi bắt đầu sẽ trả về trạng thái không phải `200` cùng phần thân lỗi thông thường, ngay cả khi dùng `"stream": true`. Không có sự kiện nào được gửi và bạn không bị tính phí. Hãy kiểm tra trạng thái HTTP trước khi đọc phần thân dưới dạng luồng.

Với `"stream": true`, phản hồi bắt đầu khi Lana phản hồi lần đầu hoặc chậm nhất sau 10 giây. Một lượt thất bại trước thời điểm đó, chẳng hạn do mô hình quá tải hoặc cuộc trò chuyện quá dài, cũng thuộc trường hợp này.

| Trạng thái | Nguyên nhân | Cách xử lý |
| - | - | - |
| `400` | Phần thân không hợp lệ, chẳng hạn như mô hình không xác định hoặc `max_tokens` lớn hơn 8.192. `message` nêu tên từng trường không hợp lệ. | Sửa yêu cầu. |
| `401` | Khóa API bị thiếu, không hợp lệ hoặc được gửi dưới dạng `Authorization: Bearer`. | Gửi khóa trong `X-Api-Key` hoặc `?api-key=`. |
| `403` | Gói của bạn không bao gồm Lana (gói Free) hoặc cài đặt quyền truy cập của khóa chặn dịch vụ này. | Nâng cấp lên Developer trở lên hoặc kiểm tra cài đặt quyền truy cập của khóa trong [Helius Dashboard](https://dashboard.helius.dev). |
| `400`, phần thân `Bad Request` | Phần thân lớn hơn 10 MB. Gatekeeper từ chối trước khi Lana nhận được. | Gửi yêu cầu nhỏ hơn, chẳng hạn như ít tin nhắn hơn hoặc tin nhắn ngắn hơn. |
| `429`, phần thân `Too Many Requests` | Bạn đã vượt quá [giới hạn tốc độ](https://www.helius.dev/docs/vi/billing/rate-limits.md) của gói. | Chờ theo header `Retry-After` (1 giây), sau đó thử lại. |
| `429`, phần thân `max usage reached` | Dự án đã hết tín dụng. | Thêm tín dụng hoặc nâng cấp gói. Không có `Retry-After`; việc thử lại sẽ tiếp tục thất bại cho đến khi bạn thực hiện một trong các thao tác này. |
| `429`, `error.type` `rate_limit_error` | Dự án đã có khoảng 3 yêu cầu Lana đang chạy. | Chờ theo header `Retry-After` (5 giây), sau đó thử lại. |
| `503` | Lana đã hết công suất hoặc đang khởi động lại. | Chờ theo header `Retry-After` (5 giây khi hết công suất, 30 giây khi đang khởi động lại), sau đó thử lại. |
| `400`, `error.type` `context_overflow` | Cuộc trò chuyện không vừa với cửa sổ ngữ cảnh. | Loại bỏ các tin nhắn cũ hơn hoặc đặt câu hỏi có phạm vi hẹp hơn. |
| `529`, `error.type` `overloaded_error` | Mô hình bị quá tải. `529` là trạng thái Anthropic sử dụng cho trường hợp này; một số máy khách HTTP không nhận ra, vì vậy hãy xử lý như `503`. | Thử lại với thời gian chờ tăng theo cấp số nhân. |
| `500`, `502`, `504` | Lượt thất bại trước đầu ra đầu tiên với `api_error`, `tool_error` hoặc `timeout_error`. | Xử lý như trong [Loại lỗi](#loại-lỗi). |

Hai `429` đầu tiên đến từ gói của bạn và phần thân phản hồi cho biết bạn gặp trường hợp nào. Trường hợp thứ ba đến từ Lana và có phần thân JSON.

Nếu nhận được `429` hoặc `503` mà không có header `Retry-After`, hãy chờ vài giây trước khi thử lại.

Các lỗi riêng của Lana (`400` cho phần thân không hợp lệ hoặc `context_overflow`, `429` với `rate_limit_error`, `500`, `502`, `503`, `504` và `529`) có phần thân JSON. Lỗi từ Gatekeeper (`401`, `403`, `400` do phần thân quá lớn và các `429` của gói) là văn bản thuần. Hãy phân nhánh theo `error.type`, không phải `message`:

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

### Sau khi luồng bắt đầu

Trạng thái đã là `200`, vì vậy lỗi sẽ kết thúc luồng bằng sự kiện `error` cuối cùng hoặc bằng `message_end` và `stop_reason: "error"`. `message_end` đó không có đối tượng `error`; hãy xử lý như `api_error`. Mọi văn bản câu trả lời trước đó đều chưa hoàn chỉnh. Hãy hiển thị là chưa hoàn chỉnh hoặc loại bỏ.

### Không truyền phát

Với `"stream": false`, một lượt thất bại trả về một trong hai dạng:

* `200` với `stop_reason: "error"` và một đối tượng `error` khi lượt đã tạo bất kỳ nội dung nào, bao gồm cả lượt tra cứu. Luôn kiểm tra `stop_reason`.
* Phần thân lỗi JSON khi lượt không tạo nội dung nào. Trạng thái khớp với `error.type`: `400` cho `context_overflow`, `500` cho `api_error`, `502` cho `tool_error`, `504` cho `timeout_error` hoặc `529` cho `overloaded_error` (trạng thái Anthropic sử dụng cho mô hình quá tải; một số máy khách HTTP không nhận ra, vì vậy hãy xử lý như `503`). Những trường hợp này không bị tính phí. Xử lý như trong [Loại lỗi](#loại-lỗi).

### Loại lỗi

| `error.type` | Ý nghĩa | Cách xử lý |
| - | - | - |
| `invalid_request_error` | Yêu cầu không hợp lệ. | Sửa yêu cầu. |
| `context_overflow` | Cuộc trò chuyện và kết quả tra cứu không vừa với cửa sổ ngữ cảnh. | Loại bỏ các tin nhắn cũ hơn hoặc đặt câu hỏi có phạm vi hẹp hơn. |
| `overloaded_error` | Mô hình bị quá tải. | Thử lại với thời gian chờ tăng theo cấp số nhân. |
| `timeout_error` | Lượt đã hết thời gian. | Đặt câu hỏi có phạm vi hẹp hơn hoặc sử dụng `lana-fast`. |
| `tool_error` | Một dịch vụ tra cứu mà Lana phụ thuộc vào đã gặp lỗi. | Thử lại với thời gian chờ tăng dần. |
| `rate_limit_error` | Dự án có khoảng 3 yêu cầu đang chạy. | Thử lại sau khoảng thời gian trong header `Retry-After`. |
| `api_error` | Lana gặp lỗi ở phía Helius hoặc đã hết công suất. | Thử lại với thời gian chờ tăng dần. |

Xử lý mọi loại khác như `api_error`.

## Giới hạn

| Giới hạn | Giá trị |
| - | - |
| `max_tokens` | 1 đến 8.192 (mặc định 8.192) |
| `system` | Tối đa 10.000 ký tự |
| `extensions.attachments` | Tối đa 8 hình ảnh |
| Phần thân yêu cầu | 10 MB |
| Cửa sổ ngữ cảnh | 200.000 token, trong đó khoảng 80% (sau `max_tokens`) dành cho cuộc trò chuyện và kết quả tra cứu |
| Thời lượng lượt | 5 phút |
| Giới hạn tốc độ | Giới hạn tốc độ DAS & Enhanced APIs của gói. Xem [Giới hạn tốc độ](https://www.helius.dev/docs/vi/billing/rate-limits.md#lana-api). |
| Yêu cầu đồng thời | Khoảng 3 yêu cầu mỗi dự án. Các yêu cầu bổ sung có thể nhận `429` cho đến khi một yêu cầu hoàn tất. |

Khi một lượt gần đạt 5 phút, Lana dừng tra cứu và trả lời bằng thông tin hiện có. Các lượt dài thường kết thúc bằng câu trả lời một phần nêu rõ nội dung còn thiếu, thay vì hết thời gian chờ.

Khi truyền phát, hãy đặt thời gian chờ đọc của máy khách HTTP thành 30 giây trở lên. Byte đầu tiên có thể mất tối đa 10 giây mới đến, sau đó một `ping` đến mỗi 10 giây, vì vậy khoảng ngắt dài hơn nhiều nghĩa là kết nối đã bị gián đoạn. Giá trị mặc định 5 giây như trong `httpx` là quá ngắn. Khi không truyền phát, không có dữ liệu nào đến cho đến khi lượt kết thúc, vì vậy hãy đặt thời gian chờ đọc trên 5 phút.

Nếu bạn ngắt kết nối, Lana sẽ dừng lượt. Yêu cầu có luồng đã bắt đầu vẫn bị tính phí.

Khi Lana đã hết công suất, các yêu cầu mới nhận `503` trước khi có dữ liệu truyền phát. Các yêu cầu này không bị tính phí. Hãy thử lại sau khoảng thời gian trong header `Retry-After`.

## Giá

Mỗi yêu cầu có mức giá cố định tùy theo mô hình:

| Mô hình | Tín dụng mỗi yêu cầu |
| - | - |
| `lana-thinking` | **10.000** |
| `lana-fast` | **2.000** |

Giá giống nhau cho yêu cầu truyền phát và không truyền phát, cũng như trên mọi gói trả phí (Developer trở lên). Lana không có trên gói Free.

Tín dụng được lấy từ gói của bạn. Xem [Tín dụng](https://www.helius.dev/docs/vi/billing/credits.md#credit-lana-api).

### Trường hợp bị tính phí

Bạn bị tính phí cho mọi yêu cầu nhận HTTP `200`, dù có truyền phát hay không và bất kể lượt kết thúc như thế nào. Yêu cầu thất bại trước khi phản hồi bắt đầu sẽ nhận trạng thái khác và không bị tính phí.

* Một lượt truyền phát thất bại với sự kiện `error` hoặc bị bạn ngắt kết nối sau khi bắt đầu vẫn bị tính phí: trạng thái đã là `200`.
* Yêu cầu bị từ chối trước khi lượt bắt đầu (`400`, `401`, `403`, `429`, `503`) không bị tính phí.
* Một lượt thất bại trước khi phản hồi bắt đầu (`400`, `5xx`), dù có truyền phát hay không, đều không bị tính phí.

## Ví dụ khác

### Thiết lập giọng điệu và ví của người dùng

```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"
      }
    }
  }'
```

### Quét toàn bộ lịch sử của ví

```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 }
  }'
```

### Nhận thành phần UI, câu hỏi tiếp theo và tệp 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
    }
  }'
```

## Bước tiếp theo

> [card] [API Reference](https://www.helius.dev/docs/vi/api-reference/lana/messages.md)
>
> Lược đồ yêu cầu và phản hồi, kèm môi trường thử nghiệm.

> [card] [Rate Limits](https://www.helius.dev/docs/vi/billing/rate-limits.md#lana-api)
>
> Giới hạn tốc độ của Lana theo từng gói.

> [card] [Credits](https://www.helius.dev/docs/vi/billing/credits.md#credit-lana-api)
>
> Cách các yêu cầu Lana sử dụng tín dụng trong gói của bạn.

> [card] [Contact Support](https://www.helius.dev/docs/vi/support/contact-support)
>
> Nhận trợ giúp qua Discord, trò chuyện hoặc email.


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