> ## 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 エージェント

> Solana AI エージェントの Lana を HTTP 経由で呼び出します。ウォレット、トークン、トランザクション、価格について質問し、回答をストリームで受信できます。クイックスタート、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/ja/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 オブジェクトです。`extensions` 内やコンテンツブロック内の不明なフィールドを含め、不明なフィールドは `400` で拒否されます。

**model** `string` *required*

`lana-thinking` または `lana-fast` です。[モデル](#モデル)を参照してください。

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

古いものから順に並べた会話です。少なくとも 1 件のメッセージが必要で、最後のメッセージには `role: "user"` が必要です。[メッセージ](#メッセージ)を参照してください。

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

Lana が 1 回のモデルステップで出力できるトークンの最大数です。範囲は `1` から `8192` です。検索を伴うターンは複数のステップを使用するため、ターン全体の `output_tokens` が `max_tokens` を上回る場合があります。2,048 未満では、`lana-thinking` は推論しません。

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

`true` は[イベント](#ストリーミングイベント)をストリームします。`false` はターンの終了時に 1 件の [JSON レスポンス](#非ストリーミングレスポンス)を返します。

**system** `string`

1～10,000 文字の追加指示です。たとえば「3 つの箇条書きで回答してください。」と指定できます。これは Lana 独自の指示に追加され、その代わりに使用されるわけではありません。

**extensions** `object`

Lana 専用のオプションです。[拡張機能](#拡張機能)を参照してください。

### モデル

| | `lana-thinking` | `lana-fast` |
| - | - | - |
| 最適な用途 | 複数ステップの分析 | 簡単な検索と単一の事実確認 |
| ターンごとの検索ステップ | 最大 20 | 最大 4 |
| ターンごとの Web 検索 | 最大 3 | 最大 2 |
| ターンごとの Web ページ取得 | 最大 2 | 最大 2 |
| 推論のストリーム | `thinking_delta` として送信される場合があります。推論するかどうかは Lana が決定します。 | いいえ |

`lana-thinking` は、`max_tokens` が 2048 以上の場合にのみ推論します。

### メッセージ

各メッセージには `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 が以前のターンで返した検索を再現し、その結果を再利用できます。`tool_result` は、任意のブール値 `is_error` も受け取ります。

### 拡張機能

すべての拡張機能は任意です。

| フィールド | 型 | デフォルト | 機能 |
| - | - | - | - |
| `read_only` | boolean | `true` | 送金、スワップ、トークン発行のツールを削除します。`true` のままにしてください。この API では、ウォレット操作の表示と署名のフローは文書化されていません。 |
| `output_format` | `"markdown"` \| `"plain"` | `"markdown"` | `plain` は、Markdown を使用せず、`{{cite:N}}` マーカーを削除するよう Lana に指示します。`source` イベントは引き続き到着します。 |
| `include_ui_schema` | boolean | `false` | `ui_block` および `ui_schema` イベントとして UI コンポーネントを許可します。 |
| `include_followups` | boolean | `false` | 最大 3 件の追加質問候補を許可します。 |
| `include_documents` | boolean | `false` | `document` イベントとして、ダウンロード可能な CSV、JSON、またはテキストファイルを許可します。 |
| `enable_deep_scan` | boolean | `false` | Lana がアドレス履歴から最大 10,000 件のトランザクション（件数と合計値の場合は 50,000 件）を読み取れるようにします。ターンごとに最大 3 回スキャンできます。メインネット専用です。これを使用しない場合、Lana は 1 回の検索につき最大 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/ja/orb.md) エクスプローラーで使用されていますが、これらは不要です。

`user_context` のフィールド：

| フィールド | 型 | 機能 |
| - | - | - |
| `wallet` | 最大 128 文字の string | ユーザーのアドレスです。「自分のウォレット」や「自分の残高」が機能するようになります。 |
| `address_kind` | 最大 32 文字の string | `"wallet"` または `"token"` で、`wallet` が何であるかを示します。`wallet` が必要です。 |
| `time_zone` | 最大 64 文字の string | `"America/New_York"` などの IANA タイムゾーンです。「今日」が機能するようになります。 |
| `network` | `"mainnet"` \| `"devnet"` | 検索するネットワークです。デフォルトはメインネットです。 |

## ストリーミングイベント

`"stream": true` を使用すると、ステータス `200` と `Content-Type: text/event-stream` を受け取ります。各イベントは次の形式です。

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

```

`data` は 1 行の JSON です。その `type` は `event` 名と一致します。

`200` と最初のイベントは、Lana が最初に応答したとき（推論、回答テキスト、検索、またはファイル）、遅くとも 10 秒後に到着します。それまでは何も送信されないため、その間に失敗したリクエストは通常の[エラーレスポンス](#ストリーム開始前)を受け取り、課金されません。その後、Lana の処理中は 10 秒ごとに `ping` が到着します。

HTTP クライアントの読み取りタイムアウトを 30 秒以上に設定してください。`httpx` のようなデフォルトの 5 秒では短すぎます。最初のバイトが届く前や、2 つのイベントの間に期限切れになる可能性があります。

イベントは次の順序で到着します。

1. `message_start`。常に最初です。
2. `content_block_delta`、`tool_use`、`tool_result`、`source`、`ui_block`、`document`、`progress_update`、`ping` の任意の組み合わせ。
3. `ui_schema`。最大 1 回です。
4. `follow_up`。最大 1 回です。
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 が推論する場合の `lana-thinking` 専用です。 | `{"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 が使用した Web ページです。`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` | 1 つの 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 コンポーネントを 1 つのツリーにまとめたものです。`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` は短いメッセージと `code` を含む JSON です。

```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` | ターン全体の入力トークンです。 |
| `output_tokens` | ターン全体の出力トークンです。 |
| `tool_calls` | ターン中に実行された検索です。`tool_use` として表示されないものも含まれます。 |
| `prompt_tokens` | 最後のモデルステップの入力トークンです。コンテキストの使用量を確認するために使用します。 |
| `context_window` | モデルのコンテキストウィンドウです。現在は `200000` です。 |

Lana 独自の指示と検索ツールは、各モデルステップで約 45,000 トークンを使用するため、短い質問でも `input_tokens` は大きくなります。料金はリクエスト単位なので、トークン数によって支払額は変わりません。

## 非ストリーミングレスポンス

`"stream": false` を使用すると、ターン終了時に 1 つの 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 がファイルを作成した場合。`type` を除き、`document` イベントと同じフィールドです。 |
| `follow_up` | `include_followups` が有効で、Lana が質問を提案した場合。文字列の配列です。 |
| `sources` | Lana が Web ページを使用した場合。`type` を除き、`source` イベントと同じフィールドです。 |
| `error` | `stop_reason` が `"error"` の場合。`type` と `message` を含むオブジェクトです。 |

## エラー

### ストリーム開始前

レスポンス開始前に失敗したリクエストは、`"stream": true` を指定していても、`200` 以外のステータスと通常のエラー本文を返します。イベントは送信されず、課金もされません。本文をストリームとして読み取る前に HTTP ステータスを確認してください。

`"stream": true` を使用すると、Lana が最初に応答した時点、遅くとも 10 秒後にレスポンスが開始します。モデルの過負荷や会話が長すぎるなどの理由で、それ以前に失敗したターンもここに該当します。

| ステータス | 原因 | 対処方法 |
| - | - | - |
| `400` | 不明なモデルや 8,192 を超える `max_tokens` など、本文が無効です。`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 を超えています。Lana が受け取る前に Gatekeeper が拒否します。 | メッセージの数や長さを減らすなど、より小さいリクエストを送信してください。 |
| `429`、本文 `Too Many Requests` | プランの[レート制限](https://www.helius.dev/docs/ja/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` でターンが失敗しました。 | [エラータイプ](#エラータイプ)の説明に従って処理してください。 |

最初の 2 種類の `429` はプランに由来し、レスポンス本文にどちらに該当したかが示されます。3 つ目は Lana に由来し、JSON 本文を持ちます。

`429` または `503` に `Retry-After` ヘッダーがない場合は、数秒待ってから再試行してください。

Lana 独自のエラー（無効な本文または `context_overflow` に対する `400`、`rate_limit_error` を伴う `429`、`500`、`502`、`503`、`504`、`529`）には JSON 本文があります。Gatekeeper からのエラー（`401`、`403`、本文超過の `400`、プラン由来の `429`）はプレーンテキストです。`message` ではなく `error.type` で分岐してください。

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

### ストリーム開始後

ステータスはすでに `200` であるため、失敗時には最後の `error` イベント、または `stop_reason: "error"` を伴う `message_end` でストリームが終了します。この `message_end` には `error` オブジェクトがありません。`api_error` と同様に扱ってください。それ以前の回答テキストは部分的なものです。不完全な回答として表示するか、破棄してください。

### ストリーミングを使用しない場合

`"stream": false` を使用した場合、失敗したターンは次のいずれかを返します。

* ターンが検索を含む何らかのコンテンツを生成した場合は、`stop_reason: "error"` と `error` オブジェクトを伴う `200`。必ず `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` | Helius 側で Lana が失敗したか、処理上限に達しています。 | バックオフを使用して再試行してください。 |

その他のタイプはすべて `api_error` と同様に扱ってください。

## 制限

| 制限 | 値 |
| - | - |
| `max_tokens` | 1～8,192（デフォルトは 8,192） |
| `system` | 最大 10,000 文字 |
| `extensions.attachments` | 最大 8 枚の画像 |
| リクエスト本文 | 10 MB |
| コンテキストウィンドウ | 200,000 トークン。その約 80%（`max_tokens` を差し引いた後）を会話と検索結果に使用できます |
| ターンの長さ | 5 分 |
| レート制限 | プランの DAS & Enhanced APIs レート制限。[レート制限](https://www.helius.dev/docs/ja/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/ja/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/ja/api-reference/lana/messages.md)
>
> プレイグラウンド付きのリクエストおよびレスポンススキーマです。

> [card] [Rate Limits](https://www.helius.dev/docs/ja/billing/rate-limits.md#lana-api)
>
> Lana のプラン別レート制限です。

> [card] [Credits](https://www.helius.dev/docs/ja/billing/credits.md#lana-api-クレジット)
>
> Lana のリクエストがプランのクレジットをどのように使用するかを説明します。

> [card] [Contact Support](https://www.helius.dev/docs/ja/support/contact-support)
>
> Discord、チャット、またはメールでサポートを受けられます。


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