# SnipHunter API 调用指南

生产业务入口为 `https://api.sniphunter.com`，所有业务接口使用 `/api/v1` 前缀。文档和 OpenAPI 文件可公开读取，具体接口的鉴权要求见 OpenAPI 中的 `security` 字段。

## 服务能力

| 接口前缀 | 功能 |
| --- | --- |
| `/api/v1/audio` | 音频剪辑、转换、混音、ASR、语音合成、克隆、音色设计、变声、人声分离 |
| `/api/v1/video` | 视频剪辑、压缩、转码、抽帧、镜头提取、字幕、水印、增强、超分、抠像 |
| `/api/v1/image` | 图片处理、OCR、去水印、AI 生图 |
| `/api/v1/document`、`/api/v1/web` | 文档转文本或 Markdown、网页正文提取 |
| `/api/v1/resolve`、`/api/v1/download`、`/api/v1/extraction` | 链接解析、下载、内容提取 |
| `/api/v1/copywriting`、`/api/v1/studio` | 文案生成、创作工具 |
| `/api/v1/agent`、`/api/v1/project` | Agent 任务、事件流、项目管理 |
| `/api/v1/upload`、`/api/v1/storage`、`/api/v1/tasks` | 文件上传、对象存储、异步任务 |
| `/api/v1/health` | 健康和依赖就绪检查 |

接口清单按 HTTP 方法计数。请求参数、文件字段、枚举和响应结构以各服务的 OpenAPI 为准。

## 调用凭据

受保护的业务请求携带 `Authorization: Bearer <access_token>`。调用凭据由服务管理员提供，生产后端校验权限和接口限流。

```bash
curl https://api.sniphunter.com/api/v1/audio/ai/status \
  -H "Authorization: Bearer $SNIPHUNTER_TOKEN"
```

## OCR 调用示例

```bash
curl -X POST https://api.sniphunter.com/api/v1/image/ai/ocr \
  -H "Authorization: Bearer $SNIPHUNTER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"image_url":"https://sniphunter.com/logo.png","model":"pp-ocrv5","task":"text","return_layout":true}'
```

`model` 支持 `glm-ocr` 和 `pp-ocrv5`，`task` 支持 `text`、`table`、`formula`、`document`。

## 音频与文档

语音转文字提交到 `POST /api/v1/audio/ai/transcribe`，JSON 至少包含 `audio_url`。文字转语音提交到 `POST /api/v1/audio/ai/tts`，至少包含 `text`，可通过 `engine` 选择 `qwen3` 或 `edge`。

文档解析使用 `POST /api/v1/document/parse`，请求为 `{"file_url":"https://example.com/document.pdf","output":"markdown"}`。文件上传方式见 `/api/v1/document/parse/upload` 的 multipart 定义。网页正文提取使用 `POST /api/v1/web/scrape`，至少提供 `url`，`fetch` 可选 `auto`、`http`、`browser`。

## 异步任务和流式响应

各类任务提交接口的返回结构不同。按照该操作的响应取得 `task_id`，再使用对应的任务查询接口。业务层 `/api/v1/tasks/{task_id}` 的 ID 为整数，Media `/api/v1/tasks/{task_id}` 使用字符串 ID。

HTTP 200 后继续检查响应中的 `success`、`status`、`error` 和任务状态。只有任务完成后才读取结果 URL。任务查询可每 5 秒进行一次，网络错误重试前先查询原任务，避免重复生成和重复扣费。

SSE 接口以 `text/event-stream` 返回事件，客户端逐条读取事件。音频字节流接口需要服务端功能开关，并受引擎部署状态影响。源码与生产注册路由的差异记录在 `/deployment.json`。

## Media 和 GPU Infer

业务客户端使用 Backend 接口。Media 承担 FFmpeg、音频 AI、图片 OCR、文档和网页解析，GPU Infer 承担视频超分和抠像。它们的 OpenAPI 同时作为服务间集成参考提供。

Media 的网关前缀为 `https://sniphunter.com/media`，Infer 的网关前缀为 `https://sniphunter.com/ai`，后接其 OpenAPI 中的 `/api/v1/...` 路径。服务间鉴权使用管理员配置的 `X-API-Key`，生效要求由实际部署决定。业务令牌和服务间密钥分别由各自服务校验。

## 存储、错误与能力状态

工具输入输出采用临时对象存储，当前部署策略为约 24 小时有效。任务完成后及时下载结果，预签名 URL 可能有更短的有效期。

常见错误包括 401 凭据失效、403 权限不足、422 参数校验失败、429 限流或资源繁忙、503 依赖未就绪。业务错误以具体响应为准。

模型权重、依赖和引擎开关影响每个功能的可用性。调用前可查询业务 `/api/v1/audio/ai/status`、`/api/v1/image/ai/status` 及对应模型状态。上一轮运行检查发现图片去水印权重、词级对齐程序和 Resemble 依赖缺失，视频增强可降级到 FFmpeg 滤镜。状态接口中的配置标志应结合实际任务结果判断。

## AI 读取入口

从 `https://docs.sniphunter.com/llms.txt` 获取文档索引，再按业务读取 `/agent.md`、`/audio.md`、`/image.md`、`/video.md`。各分组提供同名 `.json` OpenAPI。`/openapi.json` 汇总当前生产业务接口，`/backend-source.json` 提供源码业务定义，`/media.json` 和 `/infer.json` 提供服务间定义。