1 line
12 KiB
JSON
1 line
12 KiB
JSON
{"repo": "bigthap/bigthap-skill", "files": {"skills/maxplus-ai/SKILL.md": {"47bb4e868e61c871dbd5ff548c8e9cc2251f1cfc": {"t": 1785747483.371627, "n": 5773, "h": "796bb9b422f205ea", "c": "---\nname: maxplus-ai\ndescription: Detailed guide to configure, route, call, and handle limitations of the MaxPlus AI proxy service. Use when integrating MaxPlus API keys (ccsk-...), configuring custom OpenAI/Anthropic api_base endpoints, or debugging 503/429 errors from MaxPlus.\n---\n\n# MaxPlus AI Integration & Reference Guide\n\nThis skill provides a reusable integration guide for connecting any application to the **MaxPlus AI Pay-as-you-go API Proxy Gateway**. It details authentication, routing protocols, payload limits, and billing monitoring.\n\n---\n\n## 1. API Authentication\n\nAll requests to the MaxPlus AI Gateway must include an API key (a 64-character hex string prefixed with `ccsk-` e.g., `ccsk-[a-f0-9]{64}`).\nAttach it in the request headers in one of the following formats:\n- **Authorization Header**: `Authorization: Bearer ccsk-...` (Standard for OpenAI SDKs & Claude Code)\n- **Anthropic-style Header**: `x-api-key: ccsk-...` (Standard for Anthropic SDKs)\n\n---\n\n## 2. API Routing & Protocol Architecture\n\nMaxPlus AI proxies requests to multiple downstream LLM endpoints. It splits routing protocols based on the model family. You **MUST** dynamically route your requests to the correct endpoint and provider type:\n\n### A. Routing Mapping\n| Model Family | Target Endpoint | Protocol Provider |\n|---|---|---|\n| **Claude Models** (e.g., `claude-sonnet-4-6`, `haiku`) | `https://api.maxplus-ai.cc` | Anthropic Messages (`/v1/messages`) |\n| **GPT / DeepSeek Models** (e.g., `gpt-5.5`, `gpt-5.4-mini`) | `https://api.maxplus-ai.cc/v1` | OpenAI Chat Completions (`/v1/chat/completions`) |\n\n### B. Python Routing Logic Example\n```python\ndef get_maxplus_config(model_name: str) -> tuple[str, str]:\n \"\"\"\n Returns (api_base, custom_llm_provider) for routing MaxPlus requests.\n \"\"\"\n model = model_name.strip().lower()\n if model.startswith(\"claude\") or \"haiku\" in model:\n # Route to Anthropic protocol gateway\n return \"https://api.maxplus-ai.cc\", \"anthropic\"\n else:\n # Route to OpenAI protocol gateway\n return \"https://api.maxplus-ai.cc/v1\", \"openai\"\n```\n\n### C. SDK Integration Guidelines\n\n#### OpenAI SDK Integration\n```python\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=\"ccsk-...\",\n base_url=\"https://api.maxplus-ai.cc/v1\"\n)\n\nresponse = client.chat.completions.create(\n model=\"gpt-5.5\",\n messages=[{\"role\": \"user\", \"content\": \"Hello\"}]\n)\n```\n\n#### Anthropic SDK Integration\n```python\nfrom anthropic import Anthropic\n\nclient = Anthropic(\n api_key=\"ccsk-...\",\n base_url=\"https://api.maxplus-ai.cc\"\n)\n\nresponse = client.messages.create(\n model=\"claude-sonnet-4-6\",\n max_tokens=100,\n messages=[{\"role\": \"user\", \"content\": \"Hello\"}]\n)\n```\n\n#### LiteLLM Integration Quirk\nLiteLLM automatically overrides custom `api_base` parameters if the model string includes a prefix (e.g. `openai/claude-sonnet-4-6` forces connection to official OpenAI servers, causing 401 Authentication errors).\n- **The Fix**: Strip prefixes, use the raw model name (e.g., `gpt-5.5` or `claude-sonnet-4-6`), pass the resolved `api_base`, and explicitly set `custom_llm_provider = \"openai\" | \"anthropic\"` in the `completion_kwargs` payload.\n\n---\n\n## 3. Strict Limits & Constraints (Troubleshooting 503 & 429)\n\n### A. The Multimodal 503 Timeout Limit\n- **Symptom**: Sending raw high-res images (e.g. 5MB+ JPEG/PNG scans) results in `503 Service Unavailable (timeout)` or `502 Bad Gateway` timeouts.\n- **Cause**: MaxPlus AI Gateway has strict HTTP body upload limits and connection timeouts on its load balancer.\n- **The Solution (Payload Compression)**: Downscale and compress all image payloads before Base64 encoding. Use the following algorithm:\n 1. Load raw image bytes using a library like PIL/Pillow.\n 2. Resize the image so its maximum dimension (width or height) is **800px**.\n 3. Save the image as **JPEG** with a compressed quality setting of **60**.\n 4. Convert the compressed bytes to Base64 for the API payload.\n - *This reduces image payloads from megabytes down to ~50-80KB*, preventing HTTP timeouts.\n\n### B. Rate Limits & Concurrency Spikes\n- **Symptom**: Batch API calls lead to `429 Key spend cap reached` or transient `503` errors.\n- **The Solution**:\n 1. Restrict active concurrent calls using a semaphore (e.g., limit concurrency to 2 on heavy pipelines).\n 2. Implement an auto-retry loop with exponential backoff for `503` and `429` status codes:\n```python\nimport asyncio\nimport time\n\nmax_retries = 3\nfor attempt in range(max_retries):\n try:\n # Call completion API\n response = call_api()\n break\n except Exception as e:\n err_str = str(e)\n if (\"503\" in err_str or \"429\" in err_str) and attempt < max_retries - 1:\n wait_time = 2.0 * (attempt + 1) # Exponential backoff: 2s, 4s...\n await asyncio.sleep(wait_time)\n continue\n raise e\n```\n\n---\n\n## 4. Programmatic Credit & Billing Tracking\n\nYou can monitor balance and usage programmatically without visiting the dashboard.\n\n### A. Credit Balance Query (`GET /v1/me`)\nRetrieves key state and absolute USD balance:\n- Endpoint: `https://api.maxplus-ai.cc/v1/me`\n- Key Fields:\n - `credit_usd`: Remaining account credit.\n - `key.used_usd`: Total cost spent by this key.\n - `key.limit_usd`: Daily or lifetime spend limit (`null` if unlimited).\n - `key.limit_used_usd`: Current period spend accumulator.\n\n### B. Usage Statistics Query (`GET /v1/usage`)\nRetrieves detailed token counters and cache utilization:\n- Endpoint: `https://api.maxplus-ai.cc/v1/usage`\n- Key Fields:\n - `totals.total_cost`: Total USD spent.\n - `totals.request_count`: Total API hits.\n - `totals.cache_read_tokens`: Input tokens retrieved from Claude prompt caching (cost-saving indicator).\n"}, "b03a1d0cedae6a6260e1cc8dad1cc63acba50485": {"t": 1785773542.1340132, "n": 5773, "h": "796bb9b422f205ea", "c": "---\nname: maxplus-ai\ndescription: Detailed guide to configure, route, call, and handle limitations of the MaxPlus AI proxy service. Use when integrating MaxPlus API keys (ccsk-...), configuring custom OpenAI/Anthropic api_base endpoints, or debugging 503/429 errors from MaxPlus.\n---\n\n# MaxPlus AI Integration & Reference Guide\n\nThis skill provides a reusable integration guide for connecting any application to the **MaxPlus AI Pay-as-you-go API Proxy Gateway**. It details authentication, routing protocols, payload limits, and billing monitoring.\n\n---\n\n## 1. API Authentication\n\nAll requests to the MaxPlus AI Gateway must include an API key (a 64-character hex string prefixed with `ccsk-` e.g., `ccsk-[a-f0-9]{64}`).\nAttach it in the request headers in one of the following formats:\n- **Authorization Header**: `Authorization: Bearer ccsk-...` (Standard for OpenAI SDKs & Claude Code)\n- **Anthropic-style Header**: `x-api-key: ccsk-...` (Standard for Anthropic SDKs)\n\n---\n\n## 2. API Routing & Protocol Architecture\n\nMaxPlus AI proxies requests to multiple downstream LLM endpoints. It splits routing protocols based on the model family. You **MUST** dynamically route your requests to the correct endpoint and provider type:\n\n### A. Routing Mapping\n| Model Family | Target Endpoint | Protocol Provider |\n|---|---|---|\n| **Claude Models** (e.g., `claude-sonnet-4-6`, `haiku`) | `https://api.maxplus-ai.cc` | Anthropic Messages (`/v1/messages`) |\n| **GPT / DeepSeek Models** (e.g., `gpt-5.5`, `gpt-5.4-mini`) | `https://api.maxplus-ai.cc/v1` | OpenAI Chat Completions (`/v1/chat/completions`) |\n\n### B. Python Routing Logic Example\n```python\ndef get_maxplus_config(model_name: str) -> tuple[str, str]:\n \"\"\"\n Returns (api_base, custom_llm_provider) for routing MaxPlus requests.\n \"\"\"\n model = model_name.strip().lower()\n if model.startswith(\"claude\") or \"haiku\" in model:\n # Route to Anthropic protocol gateway\n return \"https://api.maxplus-ai.cc\", \"anthropic\"\n else:\n # Route to OpenAI protocol gateway\n return \"https://api.maxplus-ai.cc/v1\", \"openai\"\n```\n\n### C. SDK Integration Guidelines\n\n#### OpenAI SDK Integration\n```python\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=\"ccsk-...\",\n base_url=\"https://api.maxplus-ai.cc/v1\"\n)\n\nresponse = client.chat.completions.create(\n model=\"gpt-5.5\",\n messages=[{\"role\": \"user\", \"content\": \"Hello\"}]\n)\n```\n\n#### Anthropic SDK Integration\n```python\nfrom anthropic import Anthropic\n\nclient = Anthropic(\n api_key=\"ccsk-...\",\n base_url=\"https://api.maxplus-ai.cc\"\n)\n\nresponse = client.messages.create(\n model=\"claude-sonnet-4-6\",\n max_tokens=100,\n messages=[{\"role\": \"user\", \"content\": \"Hello\"}]\n)\n```\n\n#### LiteLLM Integration Quirk\nLiteLLM automatically overrides custom `api_base` parameters if the model string includes a prefix (e.g. `openai/claude-sonnet-4-6` forces connection to official OpenAI servers, causing 401 Authentication errors).\n- **The Fix**: Strip prefixes, use the raw model name (e.g., `gpt-5.5` or `claude-sonnet-4-6`), pass the resolved `api_base`, and explicitly set `custom_llm_provider = \"openai\" | \"anthropic\"` in the `completion_kwargs` payload.\n\n---\n\n## 3. Strict Limits & Constraints (Troubleshooting 503 & 429)\n\n### A. The Multimodal 503 Timeout Limit\n- **Symptom**: Sending raw high-res images (e.g. 5MB+ JPEG/PNG scans) results in `503 Service Unavailable (timeout)` or `502 Bad Gateway` timeouts.\n- **Cause**: MaxPlus AI Gateway has strict HTTP body upload limits and connection timeouts on its load balancer.\n- **The Solution (Payload Compression)**: Downscale and compress all image payloads before Base64 encoding. Use the following algorithm:\n 1. Load raw image bytes using a library like PIL/Pillow.\n 2. Resize the image so its maximum dimension (width or height) is **800px**.\n 3. Save the image as **JPEG** with a compressed quality setting of **60**.\n 4. Convert the compressed bytes to Base64 for the API payload.\n - *This reduces image payloads from megabytes down to ~50-80KB*, preventing HTTP timeouts.\n\n### B. Rate Limits & Concurrency Spikes\n- **Symptom**: Batch API calls lead to `429 Key spend cap reached` or transient `503` errors.\n- **The Solution**:\n 1. Restrict active concurrent calls using a semaphore (e.g., limit concurrency to 2 on heavy pipelines).\n 2. Implement an auto-retry loop with exponential backoff for `503` and `429` status codes:\n```python\nimport asyncio\nimport time\n\nmax_retries = 3\nfor attempt in range(max_retries):\n try:\n # Call completion API\n response = call_api()\n break\n except Exception as e:\n err_str = str(e)\n if (\"503\" in err_str or \"429\" in err_str) and attempt < max_retries - 1:\n wait_time = 2.0 * (attempt + 1) # Exponential backoff: 2s, 4s...\n await asyncio.sleep(wait_time)\n continue\n raise e\n```\n\n---\n\n## 4. Programmatic Credit & Billing Tracking\n\nYou can monitor balance and usage programmatically without visiting the dashboard.\n\n### A. Credit Balance Query (`GET /v1/me`)\nRetrieves key state and absolute USD balance:\n- Endpoint: `https://api.maxplus-ai.cc/v1/me`\n- Key Fields:\n - `credit_usd`: Remaining account credit.\n - `key.used_usd`: Total cost spent by this key.\n - `key.limit_usd`: Daily or lifetime spend limit (`null` if unlimited).\n - `key.limit_used_usd`: Current period spend accumulator.\n\n### B. Usage Statistics Query (`GET /v1/usage`)\nRetrieves detailed token counters and cache utilization:\n- Endpoint: `https://api.maxplus-ai.cc/v1/usage`\n- Key Fields:\n - `totals.total_cost`: Total USD spent.\n - `totals.request_count`: Total API hits.\n - `totals.cache_read_tokens`: Input tokens retrieved from Claude prompt caching (cost-saving indicator).\n"}}}} |