接入说明

Cran 开放 API 用于通过接口提交图片与文本处理任务，并异步查询任务状态和结果。所有接口都复用 Cran 账号体系，用户需要先在账号管理中创建 API Key，再使用 API Key 调用开放接口。

调用流程

创建 API Key。

选择对应功能接口提交任务。

创建任务接口立即返回 task_id。

使用 task_id 轮询查询任务状态。

任务完成后查询任务结果。

如创建任务时传入 callback_url，Cran 会在任务进入终态后异步推送回调；轮询仍建议作为兜底。

公开 API 的 baseUrl 为：

https://cranpod.com

请求示例里的路径都需要拼接 baseUrl 使用，例如：

https://cranpod.com/openapi/v1/tasks/idetect

所有开放 API 请求都需要携带 X-Api-Key：

创建任务建议同时携带 X-Idempotency-Key：

同一个 API Key、同一个接口、同一个幂等键重复提交时，会返回首次创建的同一个 task_id。不同 API Key 的幂等空间互相隔离。

所有需要图片的接口只支持公网可访问图片 URL。

不支持文件上传。

不支持 base64、b_64、data:image/...;base64。

不支持 asset_id、object_key 等内部资源引用。

一次请求只创建一个任务，不支持一次提交多个任务。

创建任务前会校验当前账号积分余额。余额不足时不会创建任务，响应体 code 为 40201。

创建任务时还会校验当前账号在当前功能下的运行中并发数。超过并发上限时不会创建任务，响应体 code 为 42901。

创建任务时可以传入 callback_url。任务成功、失败等终态产生后，Cran 会向该地址推送任务结果。

回调是异步推送，可能因为网络或对方服务不可用而延迟。接入方应保留轮询查询作为兜底，不应只依赖 webhook。

所有响应体都包含 code、message、data：

{
  "code": "0",
  "message": "success",
  "data": {}
}

code 为 0 表示成功；非 0 表示失败，具体含义见「错误码说明」。