---
document_id: agent.paths.api.calling
schema_version: 2
parent_document_id: agent.paths.api
section: querying
---

<!-- Generated by scripts.build_agent_guide; do not edit. -->

# API calling rules / API 调用规则

## Use the endpoint contract / 先读取对应入口的契约

在 [API 参考](https://docs.asklear.cn/api/reference) 中读取具体 method/path、schema、字段和版本。接口列入公开目录不等于当前账号有执行权限；合成示例也不代表实时结果或生产可用性。

Read the specific method/path, schema, fields and version in the [API reference](https://docs.asklear.cn/en/api/reference). Public listing is not execution permission, and synthetic examples do not prove live results or production availability.

## Pagination and bulk work / 分页与批量

按该入口公开的页码、游标或 next_input 继续。出现 meta.next_input 时复制其完整非空对象，不拿原始响应里的任意 token 自造游标；没有该字段时按接口文档处理。不要假定所有平台支持同一筛选或分页方式。

Continue using the endpoint’s page, cursor or next_input contract. When meta.next_input is provided, copy the complete non-null object; do not invent a cursor from a raw token. Otherwise follow the endpoint documentation. Platforms need not share filters or pagination.

批量范围、数据上限和费用按所选接口确定。先小范围验证，再按需要获取约定范围；保留成功结果与进度，避免中断后从头执行。

Determine bulk scope, limits and cost from the endpoint. Validate a small scope, then retrieve the agreed range as needed; persist results and progress so interruptions do not require a fresh run.

## Asynchronous work, idempotency and recovery / 异步、幂等与恢复

异步接口提交后按响应返回的任务标识读取状态和结果，遵守等待提示及终态；取消按对应合同处理。高层 Task HTTP 也是 API，仍应使用其真实请求参数，不复制 MCP run 的外层工具参数。

After asynchronous submission, use the returned task identifier to read state and results, following waiting hints and terminal states. Cancellation follows the endpoint contract. Task HTTP is also an API; use its request schema rather than copying the outer MCP run arguments.

在契约要求时发送幂等键，并按该合同保持同一请求的身份。超时或结果未知时先查原任务或已保存结果，不盲目提交新任务。幂等冲突不能通过改一个新键绕过。

Send idempotency keys where required and preserve the identity of the same request as specified. For timeouts or unknown outcomes, inspect the original task or saved result before submitting again. Do not bypass an idempotency conflict by simply choosing a new key.

响应头 X-Asklear-Request-ID 标识本次 HTTP 调用，每次重试各有一个；job_id 标识业务任务，幂等重放会复用。联系支持时保留两者，旧版本可能尚未返回此响应头。

The X-Asklear-Request-ID response header identifies one HTTP attempt; each retry has its own ID. A job_id identifies the business task and is reused on an idempotent replay. Keep both when contacting support; older releases may not return this header.

## Charges, limits and errors / 费用、限额与错误

不同接口的预估、批准、执行及结算可能不同；以具体入口的公开计费说明和实际响应 metadata 为准，不把请求次数统一当作计费条数。

Estimation, approval, execution and settlement vary by endpoint. Use the published billing contract and actual response metadata, rather than treating request count as billed item count.

遇到错误先读取 code、retryable 与恢复信息，按[错误处理](https://docs.asklear.cn/api/errors)行动。不要对所有失败统一重试，也不要将解析失败当作空结果。

Read code, retryable and recovery information before acting; see [error handling](https://docs.asklear.cn/en/api/errors). Do not retry every failure or interpret a parse failure as empty data.

## Rate limits, results and exports / 限流、结果与导出

429 使用返回的 code、metric 和 Retry-After 判断触发的是速率、次数还是并发限制；不要把请求配额与 Credits 混为一谈。异步提交结束不等于后台任务完成。

For 429, use the returned code, metric and Retry-After to identify rate, count or concurrency limits. Request quotas and Credits are separate; the end of submission does not mean background work completed.

读取返回的任务／结果地址，保存成功数据。用户需要文件时使用该接口实际提供的导出或下载入口；结果未知先核对原请求，不重新提交成功任务。

Read the returned task or result location and save successful data. Use the endpoint’s published export or download facility for files. Check the original request for unknown outcomes instead of resubmitting successful work.

## Versions and saved results / 版本与已保存结果

按公开的 method、path 和版本调用，不能根据 operation ID 拼接 URL。不同版本参数、返回结构和默认值可能不同，不自动切换。

Use the published method, path and version, not a URL constructed from an operation ID. Parameters, result layouts and defaults can differ across versions; do not switch automatically.

HTTP pending 沿 status_url 读取；Task 用原 task_ref 和 poll_after_seconds。已保存结果按原版本和快照续读，不重新取数；长结果按返回的 next_result_ref 继续。

For HTTP pending use status_url; for Tasks use the original task_ref and poll_after_seconds. Read saved results under their original version and snapshot without executing again; continue long results with the returned next_result_ref.
