alapi

ALAPI interface integration assistant

Overview

Use this skill to handle interface retrieval, documentation reading, parameter extraction, code generation, and on-demand real calls for the ALAPI platform.

Key platform conventions for ALAPI:

{
  "success": true,
  "code": 200,
  "message": "success",
  "data": { ... },
  "request_id": "xxx",
  "time": 1700000000
}

Base URL: https://v3.alapi.cn
Documentation page: https://www.alapi.cn/api/{id}/introduction
Token creation: https://www.alapi.cn/dashboard/data/token
All interfaces must pass the token parameter, usually placed in the GET query or POST body
token priority: explicit --token takes precedence over the environment variable ALAPI_TOKEN

All interface data retrieval is done through alapi.py . The script has zero dependencies; prefer using it, and do not manually construct ALAPI's internal documentation interfaces.

Do not assume the current working directory is definitely the skill repository root, and do not hardcode old relative paths within the repository. Prefer deriving the script path from the current skill directory:

SKILL_DIR=/absolute/path/to/alapi
SCRIPT="$SKILL_DIR/scripts/alapi.py"
python3 "$SCRIPT" --json search "IP查询"

Quick Workflow

The user provided an ALAPI documentation URL

Extract from the URL api/{id}, then directly read the OpenAPI:

python3 "$SCRIPT" --json openapi {id}

The user only described the functionality

Search first, then decide whether to continue:

python3 "$SCRIPT" --json search "用户描述的关键词"

If the search results are empty, do not give up immediately. Perform keyword fallback in this order:

Remove modifiers and keep only the core noun
Search again using a shorter synonym or hypernym
Split compound words and search separately, for example search "video" first, then "parse", then "short video"

Only after 2 to 3 rounds of fallback still yield no results should you tell the user that there is currently no matching interface.

If multiple results are matched, list 2 to 5 candidates first; do not choose one on your own. After the user confirms, then read the OpenAPI:

python3 "$SCRIPT" --json openapi {id}

The user wants to browse all interfaces

python3 "$SCRIPT" --json explore

The user wants code, not a real request

Prefer to read openapi, then extract from the results:

Request path
Request method
Required parameters
Optional parameters
Response structure
Documentation link https://www.alapi.cn/api/{id}/introduction

If this is still only the candidate stage, do not directly provide the "final confirmed version of the code". At most provide only:

Candidate list
Candidate differences
Which language's code will be generated after confirmation

Unless there is only a single clear match, or the user has already confirmed a specific interface.

The user explicitly requests a real call

Execute only when the user explicitly requests to "directly call/test the interface" and has provided a token:

python3 "$SCRIPT" --json call {path} --token {用户的token} --param key=value

If the user does not have a token, guide them to create one:

Please first create an API Token at https://www.alapi.cn/dashboard/data/token .

If the user has not explicitly provided a token, but the environment already has ALAPI_TOKEN, it can be used directly; if both exist, always prioritize the explicit token.

Critical Rules

By default, prioritize read-only operations:search、detail、openapi、explore
Prefer to use --json, then generate a natural language explanation based on the JSON result
Do not manually guess ALAPI documentation interface paths; prefer to use scripts/alapi.py
Do not assume cwd is definitely in the skill root directory
Do not echo the user's real token in the final reply
Support from the environment variable ALAPI_TOKEN Read the token, but explicitly --token takes highest priority
When search results are not unique, list the candidates first; do not decide on the endpoint on your own
When a search returns 0 results, do a keyword fallback first; do not conclude it does not exist as the first step
When the user only wants "documentation" or "code examples", do not actually call the endpoint
Before the candidates are confirmed, do not output "final finalized code"; output the candidates and differences first
If the user has not provided enough parameters, do not guess values; clearly point out the missing parameters
If the OpenAPI does not state it clearly, do not fill in the gaps by generating parameter names, default values, or response fields that do not exist
call On failure, prefer preserving the platform's original error structure, then give next-step suggestions based on the error code
For endpoints that require real parameters to call, if the user has not provided enough parameters, first explain what is missing; do not guess values

Command Reference

Command	Purpose
`search <keyword>`	Search endpoints
`explore`	Browse all endpoints
`detail <id>`	Read basic endpoint information
`openapi <id>`	Read the OpenAPI spec
`call <path>`	Make a real request
`--json`	Output stable JSON for the agent to continue processing

Code Generation Rules

Use this uniformly for token placeholders: ALAPI_TOKEN
By default, generate a minimal runnable version; do not over-abstract
Keep the response parsing and error handling logic, covering success/code/message/data/request_id/time
For Python use requests; for JS/TS use fetch; for PHP use curl; for Go use net/http
Do not introduce unnecessary dependencies
If the user is integrating into a server-side project, prefer suggesting that the token be placed in an environment variable or server-side configuration, not on the frontend
If the parameters or methods come from the OpenAPI, generate according to the OpenAPI; if the OpenAPI is missing, do not fabricate
For detailed templates see code-examples.md

Frontend/backend layering rules:

By default, browser-side or Next.js Client Components should not connect directly to ALAPI
Node.js server-side, PHP backend, and Python backend can directly read ALAPI_TOKEN
If the user says "integrate into a frontend project", prefer providing a server-side proxy solution, unless the user clearly states that it runs in a pure backend environment

Reporting Template

When the documentation is incomplete, candidates exist, or there are uncertain fields, prefer outputting in this structure:

Confirmed

Endpoint paths, methods, parameters, and return fields clearly confirmed from the OpenAPI or real calls

To be confirmed

Candidate endpoints or business choices that still need user confirmation

Do not assume

Parameters, default values, return fields, or platform behaviors that are not clearly stated in the documentation and therefore must not be actively fabricated

Live Call Rules

After making a real call, prefer preserving this information:

Endpoint name and path
Token source: explicit --token or environment variable ALAPI_TOKEN
The business parameters actually passed in the request
Key fields in the raw response:success、code、request_id、data summary

Do not preserve this information:

The token itself
Unnecessary sensitive context
Command history that would leak credentials

Real Usage Examples

帮我查一下 IP: 8.8.8.8 First locate the IP lookup endpoint, then perform the lookup when the user explicitly requests a real call and the token is available, or provide the lookup code first.
帮我生成视频解析的代码 First search for "video parsing" related interfaces. If multiple candidates are found, list them for the user to confirm first, then generate minimal runnable code based on the corresponding OpenAPI.

Failure Handling

code	Meaning	Suggestion
200	Success	—
401	Token invalid or not provided	Check the token
403	The plan does not include this interface	Upgrade the plan
422	Parameter validation failed	Point out missing or incorrectly formatted parameters first
429	Rate limit exceeded	Reduce frequency, add caching, and retry with delay if necessary
500	Server error	Keep the original error and recommend retrying

If the search results are empty, directly state that there is no matching interface and suggest using more specific keywords.

If openapi is missing but detail or the documentation page exists, clearly tell the user that the specification is incomplete and fall back to basic information + the documentation link.