External · API Quickstart

API 快速入门

Xisound Public API · CLI / C / REST / RPC

API 快速入门

API 快速入门摘要

本页介绍 Xisound 4 类对外公开 API —— XiForge CLI（命令行）、XiAlgo C API（嵌入式）、XiTest REST（测试数据）、XiCore RPC（运行时控制）。10 分钟跑通第一个调用。

1. API 分类总览

graph LR
    User[开发者 / 集成商]:::xyL4

    CLI[XiForge CLI<br/>命令行构建]:::xyL4
    CAPI[XiAlgo C API<br/>嵌入式算法]:::xyL3
    REST[XiTest REST<br/>测试报告 / SPC]:::xyL2
    RPC[XiCore RPC<br/>运行时调参]:::xyL0

    User --> CLI
    User --> CAPI
    User --> REST
    User --> RPC

    classDef xyL0 fill:#0B1C2E,color:#5DDECF,stroke:#5DDECF
    classDef xyL2 fill:#0B1C2E,color:#D4A574,stroke:#D4A574
    classDef xyL3 fill:#0B1C2E,color:#D4A574,stroke:#D4A574
    classDef xyL4 fill:#0B1C2E,color:#D4A574,stroke:#D4A574

2. XiForge CLI · 命令行构建

# 安装（订阅 Pro / Enterprise 后从官网获取）
xiforge --version

# 构建一个流图
xiforge build myflow.flow -target xidsp-d2 -o build/firmware.bin

# 位精确仿真
xiforge simulate myflow.flow --input input.wav --output sim.wav

# 位精确比对（仿真 vs 实机）
xiforge verify --bit-exact sim.wav hw.wav

CI/CD 集成

详见集成指南 · 第 5 节。

3. XiAlgo C API · 嵌入式算法

#include <xialgo/peq.h>

int main(void) {
    xa_peq_t peq;
    xa_peq_init(&peq, 48000.0f);
    xa_peq_set_band(&peq, 0, XA_PEQ_PEAKING, 1000.0f, 1.0f, 3.0f);

    float in[256], out[256];
    // ... 填充 in[] ...
    xa_peq_process(&peq, in, out, 256);
    return 0;
}

编译链接：

gcc main.c -lxialgo -lm -o demo

头文件来源

XiAlgo Community / Commercial / Source 许可证都包含完整头文件 + 文档。

4. XiTest REST · 测试报告 / SPC

# 上传一份测试报告
curl -X POST https://api.xisound.com/v1/xitest/reports \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d @report.json

# 查询 SPC Cpk
curl https://api.xisound.com/v1/xitest/spc?line=A1&metric=thd \
     -H "Authorization: Bearer YOUR_TOKEN"

符合 OpenAPI 3.0 规范 · 配套 Swagger UI。

认证

生产 API 需要 Bearer Token，联系 support@xisound.com 申请。

5. XiCore RPC · 运行时调参

# Python 客户端示例
from xicore import Client

c = Client("tcp://192.168.1.100:9090")
c.set_param("peq.band0.gain_db", 2.5)   # 实时调参
val = c.get_param("peq.band0.gain_db")  # 回读
c.snapshot_save("profile_a")            # 保存快照

RPC 协议基于 JSON-RPC 2.0 over TCP / WebSocket · 延迟 < 1 ms（局域网）。

6. 错误码与重试

错误码	说明	建议
`401`	认证失败	检查 Token 有效性
`429`	限流	指数退避重试
`503`	服务暂不可用	重试 ≤ 3 次
`XIFORGE_E_CHECKSUM`	位精确校验失败	重新构建

7. 资源链接

资源	链接
XiForge Dev Kit 下载	external/downloads/xiforge-dev-kit
XiAlgo 样例下载	external/downloads/xialgo-sample
XiDSP SDK	external/downloads/xidsp-sdk
集成指南	integration-guide
FAQ	faq
技术支持	support@xisound.com

8. 版本历史

版本	日期	变更摘要
v1.0	2026-05-06	首次对外发布（4 类 API 快速入门）