メインコンテンツへスキップ

​
概要

LemonDataのAgent-First APIは、AIエージェントが即座に解析して対応できる構造化されたヒントでエラーレスポンスを強化します。ウェブ検索、ドキュメントの確認、推測は不要です。 すべてのエラーレスポンスには、標準の error オブジェクト内に did_you_mean、suggestions、hint、retryable、retry_after などのオプションフィールドが含まれます。これらのフィールドは後方互換性があり、これらを使用しないクライアントには影響を与えません。

​
エラーヒントフィールド

すべてのヒントフィールドは、error オブジェクト内のオプションの拡張です：
フィールド型説明
did_you_meanstring最も近い一致するモデル名
suggestionsarrayメタデータ付きの推奨モデル
alternativesarray現在利用可能な代替モデル
hintstring人間またはエージェントが読み取り可能な次のステップのガイダンス
retryableboolean同じリクエストを再試行して成功する可能性があるかどうか
retry_afternumber再試行するまでの待機秒数
balance_usdnumber現在の米ドル建てアカウント残高
estimated_cost_usdnumber失敗したリクエストの推定コスト

​
エラーコードの例

​
model_not_found (400)

モデル名がアクティブなモデルと一致しない場合： 
{
  "error": {
    "message": "Model 'gpt5' not found",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-4o",
    "suggestions": [
      {"id": "gpt-4o"},
      {"id": "gpt-4o-mini"},
      {"id": "claude-sonnet-4-5"}
    ],
    "hint": "Did you mean 'gpt-4o'? Use GET /v1/models to list all available models."
  }
}
did_you_mean の解決には以下が使用されます：
  1. 静的エイリアスマッピング（本番環境のエラーデータから）
  2. 正規化された文字列マッチング（ハイフンの除去、大文字小文字を区別しない）
  3. 編集距離マッチング（しきい値 ≤ 3）

​
insufficient_balance (402)

アカウント残高が推定コストに対して低すぎる場合： 
{
  "error": {
    "message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-5, but balance is $0.1200.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gpt-4o-mini"},
      {"id": "deepseek-chat"}
    ],
    "hint": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-5, but balance is $0.1200. Try a cheaper model, or top up at https://lemondata.cc/dashboard/billing."
  }
}
suggestions には、エージェントが切り替え可能な、推定コストよりも安価なモデルが含まれます。

​
all_channels_failed (503)

モデルのすべてのアップストリームチャネルが利用できない場合： 
{
  "error": {
    "message": "Model claude-opus-4-6 temporarily unavailable",
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-5", "status": "available", "tags": []},
      {"id": "gpt-4o", "status": "available", "tags": []}
    ],
    "hint": "All channels for 'claude-opus-4-6' are temporarily unavailable. Retry in 30s or try an alternative model."
  }
}
retryable は、理由が no_channels（このモデルに設定されたチャネルがない）の場合は false になります。サーキットブレーカーの作動やクォータ不足などの一時的な失敗の場合のみ true になります。

​
rate_limit_exceeded (429)

{
  "error": {
    "message": "Rate limit: 60 rpm exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 60/min for user role."
  }
}
retry_after の値は、実際のレート制限ウィンドウのリセット時間から計算されます。

​
context_length_exceeded (400)

入力がモデルのコンテキストウィンドウを超えた場合（アップストリームエラー、ヒントで強化）： 
{
  "error": {
    "message": "This model's maximum context length is 128000 tokens...",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "retryable": false,
    "suggestions": [
      {"id": "gemini-2.5-pro"},
      {"id": "claude-sonnet-4-5"}
    ],
    "hint": "Reduce your input or switch to a model with a larger context window."
  }
}

​
ネイティブエンドポイントヘッダー

ネイティブエンドポイント（AnthropicまたはGemini）を持つモデルで /v1/chat/completions を呼び出すと、成功レスポンスに最適化ヘッダーが含まれます： 
X-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance (no format conversion).
X-LemonData-Native-Endpoint: /v1/messages
モデルプロバイダー推奨エンドポイントメリット
Anthropic (Claude)/v1/messagesフォーマット変換なし、拡張思考、プロンプトキャッシュ
Google (Gemini)/v1beta/geminiフォーマット変換なし、グラウンディング、安全設定
OpenAI—Chat completionsはすでにネイティブフォーマットです
これらのヘッダーは、ストリーミングと非ストリーミングの両方のレスポンスに表示されます。

​
/v1/models の強化

各モデルオブジェクトの lemondata 拡張にある3つの新しいフィールド： 
{
  "id": "gpt-4o",
  "lemondata": {
    "category": "chat",
    "pricing_unit": "per_token",
    "cache_pricing": {
      "cache_read_per_1m": "1.25",
      "cache_write_per_1m": "2.50",
      "platform_cache_discount": 0.9
    }
  }
}
フィールド値説明
categorychat, image, video, audio, tts, stt, 3d, embedding, rerankモデルのタイプ
pricing_unitper_token, per_image, per_second, per_requestモデルの課金方法
cache_pricingオブジェクトまたは nullアップストリームのプロンプトキャッシュ価格 + プラットフォームのセマンティックキャッシュ割引

​
カテゴリフィルタリング

GET /v1/models?category=chat          # チャットモデルのみ
GET /v1/models?category=image         # 画像生成モデル
GET /v1/models?tag=coding&category=chat  # コーディングに最適化されたチャットモデル

​
llms.txt

マシンリーダブルなAPI概要は以下で入手可能です： 
GET https://api.lemondata.cc/llms.txt
以下が含まれます：
  • 動作例を含む初回呼び出しテンプレート
  • 一般的なモデル名（使用状況データから動的に生成）
  • 全12個のAPIエンドポイント
  • モデル発見のためのフィルターパラメータ
  • エラーハンドリングのガイダンス
最初のAPI呼び出しの前に llms.txt を読み取るAIエージェントは、通常、最初の試行で成功できます。

​
エージェントコードでの使用

​
Python (OpenAI SDK)

from openai import OpenAI, BadRequestError

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://api.lemondata.cc/v1"
)

def smart_chat(messages, model="gpt-4o"):
    try:
        return client.chat.completions.create(
            model=model, messages=messages
        )
    except BadRequestError as e:
        error = e.body.get("error", {}) if isinstance(e.body, dict) else {}
        # 自動修正に did_you_mean を使用する
        if error.get("code") == "model_not_found" and error.get("did_you_mean"):
            return client.chat.completions.create(
                model=error["did_you_mean"], messages=messages
            )
        raise

​
JavaScript (OpenAI SDK)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-key',
  baseURL: 'https://api.lemondata.cc/v1'
});

async function smartChat(messages, model = 'gpt-4o') {
  try {
    return await client.chat.completions.create({ model, messages });
  } catch (error) {
    const err = error?.error;
    if (err?.code === 'model_not_found' && err?.did_you_mean) {
      return client.chat.completions.create({
        model: err.did_you_mean, messages
      });
    }
    throw error;
  }
}

​
設計原則

迅速に失敗し、有益な情報を返す

エージェントが自己修正するために必要なすべてのデータとともに、エラーが即座に返されます。

自動ルーティングなし

APIが勝手に別のモデルに置き換えることはありません。エージェントが決定します。

データ駆動型の推奨

すべての推奨事項は、ハードコードされたリストではなく、本番データに基づいています。

後方互換性

すべてのヒントフィールドはオプションです。既存のクライアントには影響ありません。