# LEAPERone (/zh/docs)
一个 API Key，调用主流 AI 模型和开发者服务。
```bash title="第一次 API 调用"
curl -X POST https://api.leaper.one/v1/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
```
LEAPERone 是什么？ [#leaperone-是什么]
LEAPERone 是统一的 AI API 网关。你可以用一个 API Key 调用对话补全、图片生成、音频转写等服务。
* **兼容 OpenAI** — 可直接替换现有接口，无需修改业务代码
* **按量计费** — 使用透明的点数计费
* **CLI 与控制台** — 管理 API Key、查询余额和查看用量
下一步 [#下一步]
获取 API Key，并在几分钟内完成第一次请求。
了解认证、模型和各个 API 端点。
查看所有端点的完整参数说明。
# 快速开始 (/zh/docs/quickstart)
1\. 创建账户 [#1-创建账户]
前往 [Dashboard](https://dashboard.leaper.one/signin)，使用 GitHub 或 Google 登录。
2\. 获取 API Key [#2-获取-api-key]
进入 **Dashboard → Settings → API Keys** 并创建新的 Key。API Key 以 `sk-` 开头。
请安全保存 API Key。完整 Key 只会显示一次。
3\. 发起第一次请求 [#3-发起第一次请求]
```bash title="Chat Completion"
curl -X POST https://api.leaper.one/v1/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
```
你会收到类似下面的响应：
```json title="响应"
{
"id": "chatcmpl-abc123",
"choices": [
{
"message": {
"role": "assistant",
"content": "Hello! How can I help you today?"
}
}
]
}
```
4\. 查询余额 [#4-查询余额]
先通过控制面 CLI 登录，获取具有明确权限范围的控制令牌：
```bash
npx @leaperone/cli auth login
npx @leaperone/cli credit balance
```
服务集成可以使用带有 `credits:read` 权限的控制令牌：
```bash
curl https://api.leaper.one/api/v1/credits/balance \
-H "Authorization: Bearer lpc-your-control-token"
```
接下来 [#接下来]
* [身份认证](/zh/docs/guides/authentication) — 了解 API Key 管理
* [Chat Completions](/zh/docs/guides/chat-completions) — 流式响应、工具调用和 JSON 模式
* [图片生成](/zh/docs/guides/image-generation) — 异步图片生成流程
* [Seedance 2.0](/zh/docs/api-reference/video-generation) — CDN 图片引用、状态轮询和 MP4 下载
# CLI (/zh/docs/advanced/cli)
LEAPERone CLI 让你可以直接在终端中管理 API 密钥、查询余额并浏览文档。
安装 [#安装]
无需安装，直接通过 `npx` 运行：
```bash
npx @leaperone/cli
```
也可以全局安装：
```bash
npm install -g @leaperone/cli
```
全局安装后，可以使用 `leaperone` 命令及其短别名 `lpr`。
身份验证 [#身份验证]
登录并将 CLI 连接到你的 LEAPERone 账户：
```bash
npx @leaperone/cli auth login
```
该命令会打开浏览器完成身份验证。如果你使用无界面服务器或远程机器，请使用设备授权流程：
```bash
npx @leaperone/cli auth login --device
```
查看当前身份验证状态：
```bash
npx @leaperone/cli auth status
```
退出登录并删除已保存的凭据：
```bash
npx @leaperone/cli auth logout
```
命令 [#命令]
API 密钥 [#api-密钥]
```bash
# List all API keys
npx @leaperone/cli apikey list
# Create a new API key
npx @leaperone/cli apikey create -n "my-app-key"
# Revoke an API key by name
npx @leaperone/cli apikey revoke -n "my-app-key"
```
新建的 API 密钥只会显示一次，请立即妥善保存。
余额 [#余额]
```bash
# Check your current credit balance
npx @leaperone/cli credit balance
# View recent usage history
npx @leaperone/cli credit usage
# Show last 50 records
npx @leaperone/cli credit usage -l 50
```
文档 [#文档]
无需离开终端即可浏览 API 端点、模型和价格：
```bash
# List all API endpoints
npx @leaperone/cli docs endpoints
# List available models and pricing
npx @leaperone/cli docs models
# Show the quick start guide
npx @leaperone/cli docs quickstart
```
升级 [#升级]
如果你全局安装了 CLI，可以直接在终端中升级：
```bash
# Upgrade the global install
leaperone upgrade
# Short alias also works
lpr upgrade
```
如果你使用 `npx`，直接运行最新版本的软件包：
```bash
npx @leaperone/cli@latest
```
JSON 输出 [#json-输出]
所有命令都支持 `--json` 参数，可输出机器可读格式，适合脚本和 CI 流程：
```bash
npx @leaperone/cli credit balance --json
lpr credit balance --json
```
```json title="JSON 输出示例"
{
"paid": 10.0,
"gift": 5.0,
"total": 15.0,
"giftExpiresAt": "2026-04-01T00:00:00.000Z"
}
```
Agent Skills [#agent-skills]
LEAPERone CLI 内置了 [Agent Skills](https://skills.sh/)。这是一组可复用的指令集，能帮助 AI 编程助手（Claude Code、Cursor、Codex、Windsurf 等）理解如何使用 LEAPERone。
快速安装 [#快速安装]
```bash
# View install guide
npx @leaperone/cli skills
# Auto-discover from node_modules (recommended)
npx skills-npm
# Or install via skills CLI
npx skills add $(npx @leaperone/cli skills path)
# Or manual copy (Claude Code)
cp -r $(npx @leaperone/cli skills path)/leaperone-cli ~/.claude/skills/
```
功能 [#功能]
安装后，你的 AI agent 将能够：
* 完成身份验证并管理 API 密钥
* 查询余额和用量
* 通过 OpenAI 兼容端点发送 API 请求
* 浏览文档并检查端点状态
支持的 Agent [#支持的-agent]
Skills 支持 40 多种 AI 编程助手，包括 Claude Code、Cursor、Codex、GitHub Copilot、Windsurf、Gemini CLI 等。
环境变量 [#环境变量]
除了使用 `auth login`，你也可以通过环境变量设置 API 密钥来完成身份验证：
```bash
export LEAPERONE_API_KEY=sk-your-api-key
npx @leaperone/cli credit balance
```
# 错误代码 (/zh/docs/advanced/error-codes)
所有 API 错误都会返回包含 `error` 对象的 JSON 响应体。请结合 HTTP 状态码和 `error.code` 字段判断错误原因。
错误响应格式 [#错误响应格式]
```json title="错误响应示例"
{
"error": {
"message": "Rate limit exceeded. Please slow down.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}
```
错误代码参考 [#错误代码参考]
| 状态码 | 含义 | 处理方法 |
| --- | ------ | ------------------------------------------------------ |
| 400 | 请求错误 | 检查请求体格式和必填字段。 |
| 401 | 未授权 | 检查 API 密钥是否有效，并确认已放入 `Authorization` 请求头。 |
| 402 | 余额不足 | 前往 [Dashboard](https://dashboard.leaper.one) 充值。 |
| 404 | 未找到 | 检查端点 URL 和相关资源 ID。 |
| 410 | 资源已失效 | 资源已经过期，例如超过 30 天的图像生成任务。 |
| 429 | 触发速率限制 | 降低请求速度并实现退避重试。参阅[速率限制](/zh/docs/advanced/rate-limits)。 |
| 500 | 服务器错误 | 稍后重试。如果问题持续存在，请联系支持团队。 |
重试策略 [#重试策略]
并非所有错误都适合重试。可以参考下表：
| 状态码 | 可重试？ | 说明 |
| --- | ---- | ---------------------------- |
| 400 | 否 | 修正请求后再重试。 |
| 401 | 否 | 修正 API 密钥或身份验证配置。 |
| 402 | 否 | 充值后再重试。 |
| 404 | 否 | 修正 URL 或资源 ID。 |
| 410 | 否 | 资源已经永久失效。 |
| 429 | 是 | 按照 `Retry-After` 请求头指定的时长等待。 |
| 500 | 是 | 使用指数退避。 |
指数退避 [#指数退避]
对于可重试错误，请使用指数退避，避免给 API 造成过大压力：
```javascript title="使用指数退避重试"
async function requestWithRetry(fn, maxRetries = 5) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const response = await fn();
if (response.ok) return response;
// Only retry on 429 or 5xx
if (response.status !== 429 && response.status < 500) {
throw new Error(`Request failed with status ${response.status}`);
}
if (attempt < maxRetries) {
const backoff = Math.min(1000 * 2 ** attempt, 30000);
const jitter = Math.random() * 1000;
await new Promise((r) => setTimeout(r, backoff + jitter));
}
}
throw new Error("Max retries exceeded");
}
```
退避等待时间应始终加入随机抖动，避免大量客户端在同一时刻同时重试。
# 速率限制 (/zh/docs/advanced/rate-limits)
LEAPERone 使用类似 OpenAI 的分级速率限制系统。你的等级决定了每个端点每分钟允许的最大请求数（RPM）。
用量等级 [#用量等级]
等级由累计消费金额和账户使用时长决定。随着 API 使用量增加，你会自动获得更高等级。
| 等级 | 达标条件 | 对话 RPM | 图像 RPM | 音频 RPM | 视频 RPM |
| ----- | ------------------ | ------ | ------ | ------ | ------ |
| 0（免费） | 默认等级 | 5 | 2 | 2 | 3 |
| 1（入门） | 累计消费 $5 | 20 | 5 | 5 | 10 |
| 2（标准） | 累计消费 $50 且满 7 天 | 40 | 10 | 10 | 20 |
| 3（专业） | 累计消费 $100 且满 7 天 | 60 | 20 | 10 | 30 |
| 4（商业） | 累计消费 $250 且满 14 天 | 100 | 30 | 20 | 50 |
| 5（企业） | 累计消费 $1000 且满 30 天 | 200 | 60 | 30 | 100 |
“天数”从首次付款开始计算，不是从账户创建日期开始计算。等级会自动升级，且不会降级。
你可以在 [Dashboard](https://dashboard.leaper.one/dashboard/settings/credit-and-usage) 中查看当前等级和限制。
自定义 API 密钥限制 [#自定义-api-密钥限制]
你可以为单个 API 密钥设置低于账户等级上限的自定义 RPM。这适合控制不同应用的用量。
前往 [API 密钥设置](https://dashboard.leaper.one/dashboard/settings/api-keys)，点击任意密钥的 RPM 标记即可设置。
速率限制响应头 [#速率限制响应头]
请求触发速率限制时，`429` 响应会包含以下请求头：
| 请求头 | 说明 |
| ----------------------- | ------------------------- |
| `X-RateLimit-Limit` | 当前时间窗口允许的最大请求数。 |
| `X-RateLimit-Remaining` | 当前时间窗口内剩余的请求数。 |
| `X-RateLimit-Reset` | 当前时间窗口重置时的 Unix 时间戳（秒）。 |
| `Retry-After` | 距离可以重试的秒数，仅在 `429` 响应中出现。 |
处理 429 响应 [#处理-429-响应]
超过速率限制时，API 会返回 `429` 状态码：
```json title="429 响应"
{
"error": {
"message": "Rate limit exceeded. Please slow down.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}
```
请根据 `Retry-After` 请求头判断发送下一次请求前需要等待多久。
指数退避 [#指数退避]
处理速率限制时，推荐使用带随机抖动的指数退避：
```javascript title="感知速率限制的 fetch"
async function fetchWithBackoff(url, options, maxRetries = 5) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const response = await fetch(url, options);
if (response.ok) return response;
if (response.status === 429) {
const retryAfter = response.headers.get("Retry-After");
const waitMs = retryAfter
? parseInt(retryAfter, 10) * 1000
: Math.min(1000 * 2 ** attempt, 30000);
const jitter = Math.random() * 1000;
console.warn(
`Rate limited. Retrying in ${Math.round((waitMs + jitter) / 1000)}s...`
);
await new Promise((r) => setTimeout(r, waitMs + jitter));
continue;
}
// Non-retryable error
throw new Error(`Request failed with status ${response.status}`);
}
throw new Error("Max retries exceeded");
}
```
最佳实践 [#最佳实践]
* **监控响应头。** 主动检查 `X-RateLimit-Remaining`，在剩余次数降为零之前降低请求速度。
* **请求排队。** 批量发送大量请求时，使用队列将请求均匀分散到整个时间窗口。
* **加入随机抖动。** 退避等待时间始终加入随机抖动，避免多个客户端同步重试。
* **缓存响应。** 使用相同参数重复调用同一端点时，缓存结果以减少不必要的请求。
# Webhook (/zh/docs/advanced/webhooks)
你无需持续轮询结果。异步任务（例如图像生成）完成后，可以让 LEAPERone 主动向你的服务器推送通知。
工作方式 [#工作方式]
在请求中加入 `callbackUrl`。任务完成或失败后，LEAPERone 会向该 URL 发送 JSON 格式的 `POST` 请求。
```json title="包含 callbackUrl 的请求"
{
"model": "gpt-4o-image",
"prompt": "A neon-lit cyberpunk cityscape",
"callbackUrl": "https://your-server.com/webhook/image"
}
```
`callbackUrl` 必须使用 HTTPS，且不能指向私有或内部网络地址。
Webhook 负载 [#webhook-负载]
任务结束后，LEAPERone 会发送一个带 JSON 请求体的 `POST` 请求：
```json title="成功负载"
{
"id": "img-abc123",
"status": "completed",
"images": [
{
"id": "img-file-1",
"url": "https://cdn.leaper.one/images/abc123.png"
}
]
}
```
```json title="失败负载"
{
"id": "img-abc123",
"status": "failed",
"error": "Content policy violation"
}
```
负载字段 [#负载字段]
| 字段 | 类型 | 说明 |
| -------- | ------ | -------------------------------------- |
| `id` | string | 生成任务 ID。 |
| `status` | string | 可取 `completed`、`uploading` 或 `failed`。 |
| `images` | array | 成功时出现，每项包含 `id` 和 `url`。 |
| `error` | string | 失败时出现，用于说明错误原因。 |
自动重试 [#自动重试]
如果你的端点返回非 2xx 状态码，或请求超过 10 秒后超时，LEAPERone 会使用指数退避重试，最多重试 **5 次**（从 2 秒开始，最长等待 30 秒）。
所有重试都失败后，回调会被标记为失败。你仍可以轮询 `GET /v1/images/generations/:id` 端点来获取结果。
验证 Webhook 来源 [#验证-webhook-来源]
Webhook 当前没有用于验证签名的请求头。你可以通过以下方式保护端点：
* 使用难以猜测的秘密路径，例如 `https://your-server.com/webhook/a8f3b2c1`。
* 调用 `GET /v1/images/generations/:id` 验证负载中的 `id`，确认任务存在且信息匹配。
* 如果基础设施支持，可以只允许已知 IP 范围访问。
最佳实践 [#最佳实践]
* **快速响应。** 收到负载后立即返回 `200` 状态码，并在服务端异步处理数据，避免请求超时。
* **处理重复通知。** 少数情况下，前一次请求成功后，重试请求仍可能到达。请使用 `id` 字段去重。
* **及时下载图像。** 图像 URL 是临时地址，会在 1 小时后过期。
# 语音合成 API (/zh/docs/api-reference/audio-speech)
把文本合成为语音音频。支持预设音色和自定义声音克隆。
端点 [#端点]
```
POST https://api.leaper.one/v1/audio/speech
```
模型 [#模型]
| 模型 | 价格 | 说明 |
| --------------- | ---------------- | -------------- |
| `moss-tts-nano` | 0.005 点数 / 1K 字符 | 支持声音克隆的多语言 TTS |
参数 [#参数]
JSON Body（预设音色） [#json-body预设音色]
| 参数 | 类型 | 必填 | 说明 |
| ---------------- | ------ | -- | -------------------------------------- |
| model | string | 否 | 使用的模型。默认：`"moss-tts-nano"` |
| input | string | 是 | 要合成的文本，最多 4096 个字符 |
| voice | string | 否 | 预设音色名称。默认：`"nova"`（中文）。参阅[可用音色](#可用音色) |
| response\_format | string | 否 | 输出格式：`"wav"` 或 `"pcm"`。默认：`"wav"` |
Multipart Form（声音克隆） [#multipart-form声音克隆]
| 参数 | 类型 | 必填 | 说明 |
| ---------------- | ------ | -- | --------------------------------------- |
| model | string | 否 | 使用的模型。默认：`"moss-tts-nano"` |
| input | string | 是 | 要合成的文本，最多 4096 个字符 |
| voice | string | 否 | 预设音色名称，作为克隆的基础音色 |
| prompt\_audio | file | 否 | 声音克隆参考音频，最大 1MB。支持 mp3、wav、flac、m4a、ogg |
| response\_format | string | 否 | 输出格式：`"wav"` 或 `"pcm"`。默认：`"wav"` |
请求 [#请求]
使用预设音色 [#使用预设音色]
```bash
curl -X POST https://api.leaper.one/v1/audio/speech \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "moss-tts-nano",
"input": "Hello, welcome to LEAPERone.",
"voice": "alloy"
}' \
--output speech.wav
```
使用自定义音频克隆声音 [#使用自定义音频克隆声音]
```bash
curl -X POST https://api.leaper.one/v1/audio/speech \
-H "Authorization: Bearer sk-your-api-key" \
-F model=moss-tts-nano \
-F input="This text will be spoken in the cloned voice." \
-F voice=alloy \
-F prompt_audio=@reference.mp3 \
--output cloned.wav
```
使用 OpenAI SDK [#使用-openai-sdk]
```python
from openai import OpenAI
client = OpenAI(
base_url="https://api.leaper.one/v1",
api_key="sk-your-api-key"
)
response = client.audio.speech.create(
model="moss-tts-nano",
input="Hello, welcome to LEAPERone.",
voice="alloy"
)
response.stream_to_file("speech.wav")
```
声音克隆必须使用 `multipart/form-data` 上传参考音频。OpenAI SDK 不支持这种请求，请使用 `curl` 或自定义 HTTP 请求。
响应 [#响应]
接口直接返回音频字节。`Content-Type` 响应头表示音频格式：
| 格式 | Content-Type |
| ----- | -------------------------- |
| `wav` | `audio/wav` |
| `pcm` | `application/octet-stream` |
PCM 是 48kHz、16-bit、双声道的原始音频。
可用音色 [#可用音色]
兼容 OpenAI 的别名 [#兼容-openai-的别名]
| 音色 | 语言 | 风格 |
| --------- | -- | ------- |
| `alloy` | 英语 | 欢迎 / 中性 |
| `echo` | 英语 | 新闻播报 |
| `fable` | 英语 | 温和提醒 |
| `onyx` | 英语 | 学术 / 讲座 |
| `nova` | 中文 | 欢迎 / 中性 |
| `shimmer` | 中文 | 轻柔 / 温和 |
中文音色 [#中文音色]
| 音色 | 风格 |
| ------------ | ------- |
| `zh-welcome` | 中性欢迎 |
| `zh-gentle` | 深夜轻柔 |
| `zh-taiwan` | 台湾口音 |
| `zh-beijing` | 北京方言 |
| `zh-culture` | 正式 / 文化 |
| `zh-yangmi` | 名人音色 |
英文音色 [#英文音色]
| 音色 | 风格 |
| ------------ | ------- |
| `en-welcome` | 中性欢迎 |
| `en-lesson` | 学术讲座 |
| `en-news` | 新闻播报 |
| `en-gentle` | 温和提醒 |
| `en-taylor` | 名人音色 |
| `en-quiet` | 平静 / 沉思 |
其他语言 [#其他语言]
| 音色 | 语言 |
| --------- | ---- |
| `ja-news` | 日语 |
| `ko-news` | 韩语 |
| `es-news` | 西班牙语 |
| `fr-news` | 法语 |
| `de-news` | 德语 |
| `it-news` | 意大利语 |
| `ru-news` | 俄语 |
还可以直接传入 `demo-1` 到 `demo-29`，使用全部 MOSS 预设音色。
注意事项 [#注意事项]
* 按字符数计费，每 1,000 个字符 0.005 点数。
* 声音克隆使用 CPU 推理，速度明显慢于预设音色。短文本通常需要 20-60 秒。
* `prompt_audio` 应使用清晰的人声样本，建议时长为 5-15 秒。
* 输入最多 4,096 个字符。
# 音频转写 API (/zh/docs/api-reference/audio-transcriptions)
把音频转写为文本。支持直接上传文件或传入 URL。
端点 [#端点]
```
POST https://api.leaper.one/v1/audio/transcriptions
```
模型 [#模型]
| 模型 | 价格 | 说明 |
| ----------- | ----------- | ----------------- |
| `rapid` | 0.006 点数/分钟 | 快速转写，支持 file\_uri |
| `whisper-1` | 0.006 点数/分钟 | 高精度转写，支持 prompt |
参数 [#参数]
| 参数 | 类型 | 必填 | 说明 |
| ---------------- | ------ | ---------------- | --------------------------------------------------------------------- |
| file | file | 与 `file_uri` 二选一 | 要转写的音频文件，以 multipart 方式上传 |
| file\_uri | string | 与 `file` 二选一 | 要转写的音频文件 URL |
| model | string | 否 | 使用的模型：`"rapid"` 或 `"whisper-1"`。默认：`"rapid"` |
| response\_format | string | 否 | 输出格式：`"text"`、`"json"`、`"verbose_json"`、`"srt"` 或 `"vtt"`。默认：`"json"` |
| language | string | 否 | ISO 639-1 语言代码，例如 `"en"`、`"zh"`。指定后可提升准确度 |
| prompt | string | 否 | 用于提升转写质量的提示文本 |
| temperature | number | 否 | 0 到 1 之间的采样温度，仅支持 `whisper-1` |
请求 [#请求]
上传文件 [#上传文件]
```bash
curl -X POST https://api.leaper.one/v1/audio/transcriptions \
-H "Authorization: Bearer sk-your-api-key" \
-F file=@recording.mp3 \
-F model=rapid \
-F response_format=json
```
传入 URL（大文件推荐） [#传入-url大文件推荐]
```bash
curl -X POST https://api.leaper.one/v1/audio/transcriptions \
-H "Authorization: Bearer sk-your-api-key" \
-F file_uri=https://example.com/audio.mp3 \
-F model=rapid \
-F language=zh \
-F response_format=verbose_json
```
使用 `file_uri` 可以避免通过你的网络上传大文件。服务端会直接拉取音频，`rapid` 和 `whisper-1` 都支持这种方式。
使用带 prompt 的 whisper-1 [#使用带-prompt-的-whisper-1]
```bash
curl -X POST https://api.leaper.one/v1/audio/transcriptions \
-H "Authorization: Bearer sk-your-api-key" \
-F file=@recording.mp3 \
-F model=whisper-1 \
-F response_format=json \
-F prompt="LEAPERone, GTC, NVIDIA"
```
请求字幕格式 [#请求字幕格式]
```bash
curl -X POST https://api.leaper.one/v1/audio/transcriptions \
-H "Authorization: Bearer sk-your-api-key" \
-F file=@recording.mp3 \
-F model=whisper-1 \
-F response_format=srt
```
响应 [#响应]
```json
{
"text": "Hello, this is a sample transcription of the audio file."
}
```
使用 `verbose_json` 时，响应会包含时间戳和分段：
```json
{
"task": "transcribe",
"language": "en",
"duration": 42.5,
"text": "Hello, this is a sample transcription of the audio file.",
"segments": [
{ "start": 0.0, "end": 2.4, "text": "Hello, this is a sample transcription." }
]
}
```
使用 `srt` 时，响应是纯文本字幕：
```text
1
00:00:00,000 --> 00:00:02,400
Hello, this is a sample transcription.
```
使用 `vtt` 时，响应采用 WebVTT 格式：
```text
WEBVTT
00:00:00.000 --> 00:00:02.400
Hello, this is a sample transcription.
```
支持的音频格式 [#支持的音频格式]
`mp3`、`mp4`、`mpeg`、`mpga`、`m4a`、`wav`、`webm`、`opus`
直接上传文件的大小上限为 25 MB。使用 `file_uri` 时没有大小限制。
注意事项 [#注意事项]
* 按音频时长和上表中的模型单价计费。
* 未指定 `model` 时，默认使用 `rapid`。
* 当前不支持流式转写（`stream=true`）。
# Chat Completions API (/zh/docs/api-reference/chat-completions)
创建对话补全。此端点兼容 OpenAI，并支持流式响应、工具调用和 JSON 模式。
端点 [#端点]
```
POST https://api.leaper.one/v1/chat/completions
```
参数 [#参数]
| 参数 | 类型 | 必填 | 说明 |
| ---------------- | ---------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| model | string | 是 | 模型 ID。内置模型：`"auto"`、`"gpt-5-nano"`、`"gpt-5.4"`、`"gpt-5.4-mini"`、`"gpt-5.5"`、`"claude-fable-5"`、`"claude-opus-4-{6,7,8}"`、`"claude-sonnet-{5,4-6}"`、`"claude-haiku-4-5"`、`"deepseek-v4-flash"`、`"deepseek-v4-pro"`。也可以使用 `"openrouter/{provider}/{model}"` 调用 OpenRouter 的 350 多个模型 |
| messages | array | 是 | 消息对象数组，每项包含 `"role"`（`system`/`user`/`assistant`）和 `"content"` |
| stream | boolean | 否 | 为 `true` 时通过 SSE 返回增量消息。默认：`false` |
| temperature | number | 否 | 0-2 之间的采样温度。默认：`0.7` |
| top\_p | number | 否 | 核采样参数。默认：`1` |
| max\_tokens | integer | 否 | 最多生成的 token 数 |
| stop | string \| array | 否 | 最多 4 个停止序列 |
| tools | array | 否 | 模型可以调用的工具定义列表 |
| tool\_choice | string \| object | 否 | `"none"`、`"auto"`，或指定某个函数 |
| response\_format | object | 否 | JSON 模式使用 `{ "type": "json_object" }` |
请求 [#请求]
```bash
curl -X POST https://api.leaper.one/v1/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [
{ "role": "system", "content": "You are a helpful assistant." },
{ "role": "user", "content": "What is LEAPERone?" }
],
"temperature": 0.7,
"max_tokens": 256
}'
```
响应 [#响应]
```json
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1700000000,
"model": "gpt-5-nano",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "LEAPERone is a unified AI API gateway that gives you access to multiple AI models through a single API key."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 25,
"completion_tokens": 22,
"total_tokens": 47
}
}
```
注意事项 [#注意事项]
* `"auto"` 默认路由到 `gpt-5-nano`。
* `stream` 为 `true` 时，接口通过 **Server-Sent Events**（SSE）返回增量内容，并以 `[DONE]` 消息结束。
* 按最终解析出的模型和实际 token 用量计费。
* **OpenRouter 模型**：使用 `"openrouter/{provider}/{model}"`（例如 `"openrouter/anthropic/claude-sonnet-4.6"`）调用 350 多个模型。价格透传自 OpenRouter。详情参阅 [Chat Completions 指南](/zh/docs/guides/chat-completions#openrouter-模型)。
# 图片生成（创建任务） (/zh/docs/api-reference/images-create)
提交异步图片生成请求。接口返回任务 ID，你可以通过[图片生成状态](/zh/docs/api-reference/images-status)端点轮询结果。
端点 [#端点]
```
POST https://api.leaper.one/v1/images/generations
```
参数 [#参数]
| 参数 | 类型 | 必填 | 说明 |
| --------------- | ------------------- | -- | ------------------------------------------------------------------------ |
| prompt | string | 是 | 要生成图片的文本描述 |
| model | string | 是 | 模型 ID。支持：`"gpt-4o-image"`、`"gpt-image-2"`、`"gemini-3-pro-image-preview"` |
| referenceImages | string \| string\[] | 否 | 用于风格或内容参考的图片 URL |
| number | number | 否 | 生成图片数量，范围 1-4。默认：`1` |
| size | string | 否 | 图片尺寸，例如 `"1024x1024"`；或宽高比，例如 `"9:16"`。具体支持情况取决于模型 |
| callbackUrl | string | 否 | 生成完成后接收 POST 请求的 Webhook URL |
支持的模型 [#支持的模型]
| 模型 | 说明 |
| ---------------------------- | ---------------------------------------------- |
| `gpt-4o-image` | OpenAI GPT-4o 图片生成，适合通用场景。 |
| `gpt-image-2` | OpenAI GPT Image 2，支持 `"9:16"` 等宽高比形式的 `size`。 |
| `gemini-3-pro-image-preview` | Google Gemini 3 Pro Image。 |
请求 [#请求]
```bash
curl -X POST https://api.leaper.one/v1/images/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-image",
"prompt": "A cat astronaut floating in space, digital art",
"number": 1,
"size": "1024x1024"
}'
```
响应 [#响应]
```json
{
"code": 0,
"msg": "success",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
```
注意事项 [#注意事项]
* 每张图片消耗 **0.5 点数**，创建任务时扣除。
* 余额不足时，API 返回 **402 Payment Required**。
* 使用返回的 `id` 通过[状态端点](/zh/docs/api-reference/images-status)轮询结果。
# 图片生成（查询状态） (/zh/docs/api-reference/images-status)
查询图片生成任务状态，并在任务完成后获取生成的图片。
端点 [#端点]
```
GET https://api.leaper.one/v1/images/generations/:id
```
参数 [#参数]
| 参数 | 类型 | 必填 | 说明 |
| -- | ------------ | -- | ------------------------------------------------------------- |
| id | string（路径参数） | 是 | 图片生成任务 UUID，由[创建任务端点](/zh/docs/api-reference/images-create)返回 |
请求 [#请求]
```bash
curl https://api.leaper.one/v1/images/generations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Authorization: Bearer sk-your-api-key"
```
响应 [#响应]
```json
{
"code": 0,
"msg": "success",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"images": [
{
"id": "image-abc123",
"url": "https://s3.bitiful.net/leaperone/images/generated/abc123?X-Amz-Expires=3600&..."
}
]
}
}
```
状态值 [#状态值]
| 状态 | 说明 |
| ------------ | ---------------- |
| `pending` | 任务已进入队列，等待开始 |
| `processing` | 正在生成图片 |
| `uploading` | 正在把生成的图片上传到存储 |
| `partial` | 部分图片已就绪，其他图片仍在处理 |
| `completed` | 所有图片都可以下载 |
| `failed` | 生成失败，请查看响应中的错误详情 |
注意事项 [#注意事项]
* 每次查询状态时都会重新签名图片 URL，URL 在 **1 小时**后过期。过期后再次轮询即可获取新 URL。
* 超过 **30 天**的任务会被删除。查询已删除的任务会返回 **410 Gone**。
# Messages API（Anthropic 原生） (/zh/docs/api-reference/messages)
使用 Anthropic 原生协议调用 Claude 或 DeepSeek V4 模型。兼容官方 [Anthropic Python / TypeScript SDK](https://docs.anthropic.com/en/api/getting-started)，只需把 `base_url` 指向 LEAPERone。
端点 [#端点]
```
POST https://api.leaper.one/v1/messages
```
身份认证 [#身份认证]
使用与兼容 OpenAI 端点相同的 LEAPERone API Key。以下两种请求头都可以使用：
* `Authorization: Bearer sk-your-leaperone-key`
* `x-api-key: sk-your-leaperone-key`（Anthropic 风格）
还必须提供：
* `anthropic-version: 2023-06-01`
参数 [#参数]
请求体遵循标准 Anthropic Messages 格式。完整结构参阅[官方文档](https://docs.anthropic.com/en/api/messages)。
| 参数 | 类型 | 必填 | 说明 |
| ------------ | --------------- | -- | ----------------------------------------------------- |
| model | string | 是 | 兼容 Anthropic 的模型 ID，见下表 |
| max\_tokens | integer | 是 | 最多生成的 token 数 |
| messages | array | 是 | `{ role, content }` 数组 |
| system | string \| array | 否 | 系统提示词或内容块 |
| stream | boolean | 否 | Anthropic 事件格式的 SSE 流 |
| temperature | number | 否 | 0-1 |
| tools | array | 否 | 工具定义 |
| tool\_choice | object | 否 | `auto` / `any` / `tool` |
| thinking | object | 否 | 使用 `{ "type": "enabled", "budget_tokens": N }` 开启扩展思考 |
支持的模型 [#支持的模型]
| 模型 ID | 说明 |
| ------------------- | ------------- |
| `claude-fable-5` | 旗舰模型 |
| `claude-opus-4-8` | |
| `claude-opus-4-7` | |
| `claude-opus-4-6` | |
| `claude-sonnet-5` | |
| `claude-sonnet-4-6` | 默认均衡模型 |
| `claude-haiku-4-5` | 最快 / 最便宜 |
| `deepseek-v4-flash` | DeepSeek 官方端点 |
| `deepseek-v4-pro` | DeepSeek 官方端点 |
价格与 Chat Completions 网关一致，单位为每 100 万 token 的美元价格。参阅[模型列表](/zh/docs/api-reference/models)。
请求（curl） [#请求curl]
```bash
curl -X POST https://api.leaper.one/v1/messages \
-H "Authorization: Bearer sk-your-leaperone-key" \
-H "Content-Type: application/json" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [
{ "role": "user", "content": "Hello!" }
]
}'
```
请求（Anthropic Python SDK） [#请求anthropic-python-sdk]
```python
import anthropic
client = anthropic.Anthropic(
api_key="sk-your-leaperone-key",
base_url="https://api.leaper.one",
)
message = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)
```
响应 [#响应]
```json
{
"id": "msg_01Abc...",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-6",
"content": [
{ "type": "text", "text": "Hi there!" }
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 12,
"output_tokens": 8,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}
```
流式响应 [#流式响应]
设置 `"stream": true` 后，接口会返回 Anthropic SSE 事件流，包括 `message_start`、`content_block_start`、`content_block_delta`、`message_delta`、`message_stop`。用量从 `message_start` 的 `input_tokens` 和 `message_delta` 的 `output_tokens` 中累计；LEAPERone 按最终合并的用量计费。
注意事项 [#注意事项]
* GPT 和 Auto 路由仍使用 [`/v1/chat/completions`](/zh/docs/api-reference/chat-completions)。
* Claude 的工具调用、视觉输入（图片内容块）和扩展思考会原样透传。DeepSeek 能力取决于其上游兼容 Anthropic 的 API。
* 扩展思考和大上下文等长请求目前共用 120 秒上游超时。接近限制时请拆分重任务。
# 模型列表 (/zh/docs/api-reference/models)
列出所有可用模型。此端点公开访问，不需要身份认证。
端点 [#端点]
```
GET https://api.leaper.one/v1/models
```
响应 [#响应]
返回模型对象列表，其中包括内置模型和通过 OpenRouter 提供的 350 多个模型。
```json
{
"object": "list",
"data": [
{
"id": "auto",
"object": "model",
"created": 0,
"owned_by": "leaperone",
"name": "Auto"
},
{
"id": "gpt-5-nano",
"object": "model",
"created": 0,
"owned_by": "leaperone",
"name": "GPT-5 Nano",
"pricing": {
"prompt_per_1m": 0.05,
"completion_per_1m": 0.4
}
},
{
"id": "openrouter/anthropic/claude-sonnet-4.6",
"object": "model",
"created": 1700000000,
"owned_by": "openrouter",
"name": "Anthropic: Claude Sonnet 4.6",
"context_length": 200000,
"pricing": {
"prompt_per_1m": 3.0,
"completion_per_1m": 15.0
}
}
]
}
```
模型字段 [#模型字段]
| 字段 | 类型 | 说明 |
| --------------- | ------ | ------------------------------------------------------------ |
| id | string | 在 `model` 参数中使用的模型 ID |
| object | string | 固定为 `"model"` |
| created | number | Unix 时间戳 |
| owned\_by | string | 内置模型为 `"leaperone"`，OpenRouter 模型为 `"openrouter"` |
| name | string | 便于阅读的模型名称 |
| context\_length | number | 最大上下文窗口，仅 OpenRouter 模型提供 |
| pricing | object | 每 100 万 token 的美元价格，包含 `prompt_per_1m` 和 `completion_per_1m` |
注意事项 [#注意事项]
* 内置模型（`owned_by: "leaperone"`）可以直接使用 ID，例如 `"gpt-5-nano"`、`"claude-sonnet-4-6"`、`"gpt-5.5"`。
* OpenRouter 模型（`owned_by: "openrouter"`）必须使用完整 ID，例如 `"openrouter/anthropic/claude-sonnet-4.6"`。
* Claude 系列和 `gpt-5.5` / `gpt-5.4-mini` 也可以通过 Anthropic 原生的 [`POST /v1/messages`](/zh/docs/api-reference/messages) 端点调用，以使用完整的工具、视觉和扩展思考能力。
* 模型列表会缓存，并每小时刷新一次。
* 此端点不需要身份认证。
# Responses (/zh/docs/api-reference/responses)
创建模型响应。Responses API 是 Chat Completions 的替代方案，采用更简单的输入格式。
端点 [#端点]
```
POST https://api.leaper.one/v1/responses
```
参数 [#参数]
| 参数 | 类型 | 必填 | 说明 |
| ------ | --------------- | -- | ----------------------------------- |
| model | string | 是 | 模型 ID。支持：`"gpt-5-nano"`、`"gpt-5.4"` |
| input | string \| array | 是 | 用于生成响应的文本字符串或输入对象数组 |
| stream | boolean | 否 | 为 `true` 时通过 SSE 返回增量内容。默认：`false` |
请求 [#请求]
```bash
curl -X POST https://api.leaper.one/v1/responses \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5-nano",
"input": "What is LEAPERone?"
}'
```
响应 [#响应]
```json
{
"id": "resp-abc123",
"object": "response",
"created_at": 1700000000,
"model": "gpt-5-nano",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "LEAPERone is a unified AI API gateway that gives you access to multiple AI models through a single API key."
}
]
}
],
"usage": {
"input_tokens": 12,
"output_tokens": 22,
"total_tokens": 34
}
}
```
# Seedance 2.0 (/zh/docs/api-reference/video-generation)
通过国际即梦渠道异步生成 Seedance 2.0 视频。先提交任务，轮询状态，再从 LEAPERone 下载完成的 MP4 文件。
通过 CLI 查阅 [#通过-cli-查阅]
CLI 和网站展示同一份文档。文档可以公开阅读；`endpoints` 命令需要先执行 `auth login` 或设置 `LEAPERONE_API_KEY`。
```bash
npx @leaperone/cli@latest endpoints
npx @leaperone/cli@latest docs read api-reference/video-generation
```
创建任务 [#创建任务]
```bash
curl -X POST https://api.leaper.one/v1/videos \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.0",
"prompt": "A cinematic 9:16 video of a cat running through warm sunlight.",
"seconds": 15,
"aspect_ratio": "9:16"
}'
```
```json
{
"id": "video_01234567-89ab-cdef-0123-456789abcdef",
"object": "video",
"model": "seedance-2.0",
"status": "queued",
"progress": 0
}
```
参数 [#参数]
| 参数 | 类型 | 必填 | 说明 |
| -------------- | ---------------- | -- | ------------------------------- |
| `model` | string | 是 | 当前固定为 `seedance-2.0` |
| `prompt` | string | 是 | 描述主体、动作、镜头、风格和输出限制 |
| `seconds` | integer 或 string | 否 | `5`、`10` 或 `15`；默认 `15` |
| `aspect_ratio` | string | 否 | `16:9`、`9:16` 或 `1:1`；默认 `9:16` |
| `images` | string\[] | 否 | 最多 4 个公开图片 URL 或 base64 data 图片 |
| `videos` | string\[] | 否 | 最多 3 个公开视频 URL |
| `audios` | string\[] | 否 | 最多 1 个公开音频 URL |
JSON 中不能使用本地文件路径。请先把参考文件上传到公开 URL；支持的图片也可以使用 base64 data URL。
使用 LEAPERone 生成参考图片 [#使用-leaperone-生成参考图片]
如果还没有公开图片 URL，可以先调用图片生成 API。任务完成后会返回签名 URL，Seedance 可以在 1 小时内下载该图片。
```bash
export LEAPERONE_API_KEY="sk-your-api-key"
IMAGE_CREATE=$(curl -sS --fail-with-body https://api.leaper.one/v1/images/generations \
-H "Authorization: Bearer $LEAPERONE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-image",
"prompt": "A bright red paper airplane on a white windowsill in warm morning sunlight, no text",
"number": 1,
"size": "9:16"
}')
IMAGE_ID=$(printf '%s' "$IMAGE_CREATE" | jq -er '.data.id')
for attempt in $(seq 1 120); do
IMAGE_STATUS=$(curl -sS --fail-with-body \
"https://api.leaper.one/v1/images/generations/$IMAGE_ID" \
-H "Authorization: Bearer $LEAPERONE_API_KEY")
IMAGE_STATE=$(printf '%s' "$IMAGE_STATUS" | jq -r '.data.status')
case "$IMAGE_STATE" in
completed|partial)
IMAGE_URL=$(printf '%s' "$IMAGE_STATUS" | jq -er '.data.images[0].url')
break
;;
failed) exit 1 ;;
esac
sleep 5
done
[ -n "${IMAGE_URL:-}" ] || exit 1
```
使用 CDN 图片作为参考 [#使用-cdn-图片作为参考]
Seedance 会从 `images` 中的 URL 下载参考图片。提交任务前，请确认 CDN URL：
* 未认证的 `GET` 请求会返回 `200`；
* 返回 `image/png`、`image/jpeg` 或 `image/webp` 等图片 `Content-Type`；
* 不依赖 Cookie、浏览器会话，或 Seedance 无法发送的自定义请求头；
* 在生成完成前持续有效。签名 URL 的有效期至少应为 30 分钟。
先验证图片：
```bash
export IMAGE_URL="https://cdn.example.com/reference.png"
curl -fsSL -o /dev/null -D - "$IMAGE_URL"
```
然后提交图生视频任务。下面是使用 `curl` 和 `jq` 的完整 Shell 示例。
```bash
export LEAPERONE_API_KEY="sk-your-api-key"
CREATE_RESPONSE=$(curl -sS --fail-with-body https://api.leaper.one/v1/videos \
-H "Authorization: Bearer $LEAPERONE_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg image "$IMAGE_URL" '{
model: "seedance-2.0",
prompt: "Add subtle natural motion and a slow cinematic camera push-in. Preserve the original composition.",
seconds: 5,
aspect_ratio: "16:9",
images: [$image]
}')")
echo "$CREATE_RESPONSE"
VIDEO_ID=$(printf '%s' "$CREATE_RESPONSE" | jq -er '.id')
```
每 10 秒轮询一次，直到任务进入终态：
```bash
for attempt in $(seq 1 180); do
STATUS_RESPONSE=$(curl -sS --fail-with-body \
"https://api.leaper.one/v1/videos/$VIDEO_ID" \
-H "Authorization: Bearer $LEAPERONE_API_KEY")
echo "$STATUS_RESPONSE"
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.status')
case "$STATUS" in
completed) break ;;
failed|cancelled) exit 1 ;;
esac
sleep 10
done
[ "$STATUS" = "completed" ] || exit 1
```
下载完成的视频：
```bash
curl -fL "https://api.leaper.one/v1/videos/$VIDEO_ID/content" \
-H "Authorization: Bearer $LEAPERONE_API_KEY" \
-o result.mp4
```
如果任务返回 `failed`，请更换参考图片或提示词并创建新任务。常见原因包括 CDN URL 已过期、URL 需要认证，或内容审核未通过。失败和取消的任务不会计费。
轮询状态 [#轮询状态]
```bash
curl https://api.leaper.one/v1/videos/video_01234567-89ab-cdef-0123-456789abcdef \
-H "Authorization: Bearer sk-your-api-key"
```
状态值包括 `queued`、`processing`、`completed`、`failed` 和 `cancelled`。
下载视频 [#下载视频]
```bash
curl -L https://api.leaper.one/v1/videos/video_01234567-89ab-cdef-0123-456789abcdef/content \
-H "Authorization: Bearer sk-your-api-key" \
-o result.mp4
```
计费和日志 [#计费和日志]
* 提交任务时会预留点数。
* 每个成功的视频任务固定消耗 1 点数（$1.00），请求 5、10 或 15 秒均为相同价格。人民币充值使用平台固定汇率，并可能包含渠道费用。
* 只有任务进入 `completed` 后才会结算费用。
* 失败和取消的任务会释放预留点数。
* 用量历史会记录请求 ID、API Key、公开模型、时长、渠道和最终费用。
* 每个响应都包含 `X-Request-Id`。联系支持时请保留该值。
* API 响应和用量日志不会暴露提示词、参考媒体内容、上游任务 ID、上游 URL 或凭据。
* 任务 ID 只对所属 LEAPERone 账户有效。其他用户查询时会收到 `404`。
# 音频转写指南 (/zh/docs/guides/audio-transcription)
音频转写端点可以将语音转换为文字。你可以上传音频文件，也可以传入文件 URL。
模型 [#模型]
| 模型 | 价格 | 适用场景 |
| ----------- | ----------------- | ---------- |
| `rapid`（默认） | 0.006 credits/min | 快速、通用的音频转写 |
| `whisper-1` | 0.006 credits/min | 高准确率，支持提示词 |
快速开始 [#快速开始]
```bash title="POST /v1/audio/transcriptions"
curl -X POST https://api.leaper.one/v1/audio/transcriptions \
-H "Authorization: Bearer sk-your-api-key" \
-F file=@meeting.mp3
```
```json title="响应"
{
"text": "Welcome to today's meeting. Let's start with the agenda..."
}
```
使用 file_uri [#使用-file_uri]
除了上传文件，你也可以传入 URL。音频文件较大或已经托管在线时，推荐使用这种方式。
```bash title="从 URL 转写"
curl -X POST https://api.leaper.one/v1/audio/transcriptions \
-H "Authorization: Bearer sk-your-api-key" \
-F file_uri=https://example.com/podcast-episode.mp3 \
-F language=en \
-F response_format=verbose_json
```
`file_uri` 支持任何可公开访问的音频 URL，包括 mp3、opus、m4a、wav 等格式。使用 URL 时没有文件大小限制。
选择模型 [#选择模型]
rapid（默认） [#rapid默认]
适合无需额外配置的快速转写。不需要传入 `model` 参数，支持 `language` 和 `prompt` 参数。
```bash title="使用 rapid"
curl -X POST https://api.leaper.one/v1/audio/transcriptions \
-H "Authorization: Bearer sk-your-api-key" \
-F file=@meeting.mp3 \
-F language=zh \
-F response_format=json
```
whisper-1 [#whisper-1]
OpenAI 的 Whisper 模型。支持通过 `prompt` 提高特定术语的识别准确率，也支持通过 `verbose_json` 返回词级时间戳。
```bash title="使用带提示词的 whisper-1"
curl -X POST https://api.leaper.one/v1/audio/transcriptions \
-H "Authorization: Bearer sk-your-api-key" \
-F file=@meeting.mp3 \
-F model=whisper-1 \
-F response_format=verbose_json \
-F prompt="LEAPERone, API, transcription"
```
支持的格式 [#支持的格式]
| 格式 | 扩展名 |
| ---- | ---------------- |
| MP3 | `.mp3` |
| MP4 | `.mp4` |
| MPEG | `.mpeg`, `.mpga` |
| M4A | `.m4a` |
| WAV | `.wav` |
| WebM | `.webm` |
| Opus | `.opus` |
响应格式 [#响应格式]
通过 `response_format` 控制输出格式：
| 值 | 说明 |
| -------------- | -------------------------- |
| `json` | 包含 `text` 字段的 JSON 对象，默认值。 |
| `text` | 纯文本转写结果。 |
| `verbose_json` | 包含时间戳、分段和元数据的 JSON。 |
| `srt` | SubRip 字幕格式。 |
| `vtt` | WebVTT 字幕格式。 |
费用按照音频时长计算。各模型价格请参阅 [API 参考](/zh/docs/api-reference/audio-transcriptions)。
# 身份验证 (/zh/docs/guides/authentication)
LEAPERone 对模型流量和账户控制面操作使用不同的凭据。
基础 URL [#基础-url]
```
https://api.leaper.one
```
模型 API 密钥（`sk-`） [#模型-api-密钥sk-]
调用 `/v1/*` 下兼容 OpenAI 的模型端点时，请使用 API 密钥，并通过 `Authorization` 请求头传入：
```bash title="Bearer Token"
curl https://api.leaper.one/v1/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'
```
X-API-Key 请求头 [#x-api-key-请求头]
也可以使用 `X-API-Key` 请求头：
```bash title="X-API-Key 请求头"
curl https://api.leaper.one/v1/chat/completions \
-H "X-API-Key: sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'
```
控制令牌（`lpc_`） [#控制令牌lpc_]
CLI、EnvX、账户自动化、用量查询、工单和组织操作使用 `/api/v1/*` 下具有明确权限范围的控制令牌。请通过 Dashboard 授权界面登录：
```bash
npx @leaperone/cli auth login
npx @leaperone/cli auth status
```
控制令牌具有明确的权限范围，例如 `api_keys:read`、`credits:read`、`usage:read` 或 `envx:write`。不要长期使用模型 API 密钥代替控制令牌。
创建 API 密钥 [#创建-api-密钥]
你可以通过以下两种方式创建和管理密钥：
**Dashboard** — 前往 **Settings > API Keys**，点击 **Create Key**。
**CLI** — 在终端中列出现有密钥：
```bash
npx @leaperone/cli apikey list
```
API 密钥只会在创建时显示一次，请妥善保存。
错误代码 [#错误代码]
| 状态码 | 含义 |
| ----- | ---------------- |
| `401` | 凭据无效、已过期、已撤销或缺失。 |
| `403` | 控制令牌不包含所需权限范围。 |
| `402` | 余额不足，请充值后继续。 |
完整的错误响应结构请参阅 [API 参考](/zh/docs/api-reference/chat-completions)。
# 对话补全指南 (/zh/docs/guides/chat-completions)
对话补全端点完全兼容 OpenAI。将现有 OpenAI SDK 或 HTTP 客户端指向 LEAPERone，即可直接使用。
基础请求 [#基础请求]
```bash title="POST /v1/chat/completions"
curl -X POST https://api.leaper.one/v1/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [
{"role": "user", "content": "Explain quantum computing in one paragraph."}
]
}'
```
```json title="响应"
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Quantum computing uses qubits..."
},
"finish_reason": "stop"
}
]
}
```
将 `model` 设置为 `"auto"` 后，系统会自动把请求路由到当前最合适的模型。你也可以明确指定模型，例如 `"gpt-5-nano"`。
流式输出 [#流式输出]
设置 `stream: true` 后，结果会通过服务器发送事件（SSE）返回。Token 会在生成过程中逐步发送。
```bash title="流式请求"
curl -X POST https://api.leaper.one/v1/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"stream": true,
"messages": [
{"role": "user", "content": "Write a haiku about APIs."}
]
}'
```
每个 SSE 事件都包含一行 `data:`，后面是一个 JSON 数据块：
```
data: {"id":"chatcmpl-abc123","choices":[{"delta":{"content":"Endpoints"},"index":0}]}
data: {"id":"chatcmpl-abc123","choices":[{"delta":{"content":" await"},"index":0}]}
data: [DONE]
```
工具调用 / 函数调用 [#工具调用--函数调用]
你可以传入 `tools` 数组，让模型调用你定义的函数。模型判断需要调用函数时，会返回 `tool_calls`。其格式与 OpenAI 函数调用 API 相同。
```json title="tools 参数（节选）"
{
"model": "auto",
"messages": [{"role": "user", "content": "What's the weather in Tokyo?"}],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}
}
]
}
```
完整参数列表和响应结构请参阅 [API 参考](/zh/docs/api-reference/chat-completions)。
OpenRouter 模型 [#openrouter-模型]
除了内置模型，你还可以通过 [OpenRouter](https://openrouter.ai) 使用来自主要提供商（Anthropic、Google、Meta、Mistral 等）的 **350 多个模型**。请使用 `openrouter/` 前缀，后接 OpenRouter 模型 ID：
```bash title="使用 OpenRouter 模型"
curl -X POST https://api.leaper.one/v1/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "openrouter/anthropic/claude-sonnet-4.6",
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
```
OpenRouter 模型采用上游价格透传，费用与 OpenRouter 上游提供商的价格相同。完整模型列表和价格请参阅 [OpenRouter 模型](https://openrouter.ai/models)。
示例 [#示例]
| 模型 | `model` 值 |
| ----------------- | ---------------------------------------------- |
| Claude Sonnet 4.6 | `openrouter/anthropic/claude-sonnet-4.6` |
| Gemini 2.5 Flash | `openrouter/google/gemini-2.5-flash-preview` |
| Llama 3.3 70B | `openrouter/meta-llama/llama-3.3-70b-instruct` |
| DeepSeek V3 | `openrouter/deepseek/deepseek-chat` |
# 图像生成指南 (/zh/docs/guides/image-generation)
图像生成采用异步两步流程：先**创建任务**，再**轮询结果**。
支持的模型 [#支持的模型]
* `gpt-4o-image` — OpenAI GPT-4o 图像生成模型。
* `gpt-image-2` — OpenAI GPT Image 2。除固定尺寸外，还支持 `"9:16"` 等宽高比 `size` 值。
* `gemini-3-pro-image-preview` — Google Gemini 3 Pro Image。
第 1 步：创建任务 [#第-1-步创建任务]
```bash title="POST /v1/images/generations"
curl -X POST https://api.leaper.one/v1/images/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-image",
"prompt": "A watercolor painting of a mountain lake at sunrise"
}'
```
```json title="响应"
{
"code": 0,
"msg": "success",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
```
第 2 步：轮询状态 [#第-2-步轮询状态]
使用返回的 `id` 查询任务进度：
```bash title="GET /v1/images/generations/:id"
curl https://api.leaper.one/v1/images/generations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Authorization: Bearer sk-your-api-key"
```
```json title="完成响应"
{
"code": 0,
"msg": "success",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"images": [
{
"id": "image-abc123",
"url": "https://s3.bitiful.net/leaperone/images/generated/abc123?X-Amz-Expires=3600&..."
}
]
}
}
```
状态值 [#状态值]
| 状态 | 含义 |
| ------------ | ----------------- |
| `pending` | 任务已进入队列，尚未开始。 |
| `processing` | 模型正在生成图像。 |
| `uploading` | 图像正在上传到存储服务。 |
| `partial` | 部分图像已经就绪，适用于多图请求。 |
| `completed` | 所有图像都已就绪。 |
| `failed` | 生成失败。 |
Webhook 回调 [#webhook-回调]
除了轮询，你也可以传入 `callbackUrl`，在任务结束时接收 POST 通知：
```json title="带回调的请求"
{
"model": "gpt-4o-image",
"prompt": "A neon-lit cyberpunk cityscape",
"callbackUrl": "https://your-server.com/webhook/image"
}
```
每张生成图像消耗 **0.5 credits**。
轮询任务时返回的图像 URL 带有签名，会在 **1 小时**后过期。请使用 `data.images[].url` 中的最新值；需要新 URL 时，请再次轮询任务。
完整参数列表和响应结构请参阅 [API 参考](/zh/docs/api-reference/images-create)。
# 文本转语音指南 (/zh/docs/guides/text-to-speech)
文本转语音端点可以根据输入文本生成语音音频。你可以从多语言预设音色中选择，也可以通过一段简短的音频样本克隆任意音色。
模型 [#模型]
| 模型 | 价格 | 适用场景 |
| --------------- | ------------------------ | -------------- |
| `moss-tts-nano` | 0.005 credits / 1K chars | 支持音色克隆的多语言语音生成 |
快速开始 [#快速开始]
```bash title="POST /v1/audio/speech"
curl -X POST https://api.leaper.one/v1/audio/speech \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"input": "Hello world!", "voice": "alloy"}' \
--output hello.wav
```
响应是一个可以直接播放的 WAV 音频文件。
使用 OpenAI SDK [#使用-openai-sdk]
该端点兼容 OpenAI，因此可以使用官方 SDK：
```python title="Python"
from openai import OpenAI
client = OpenAI(
base_url="https://api.leaper.one/v1",
api_key="sk-your-api-key"
)
response = client.audio.speech.create(
model="moss-tts-nano",
input="Welcome to LEAPERone. This is a text to speech demo.",
voice="alloy"
)
response.stream_to_file("welcome.wav")
```
```typescript title="Node.js"
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.leaper.one/v1",
apiKey: "sk-your-api-key",
});
const response = await client.audio.speech.create({
model: "moss-tts-nano",
input: "Welcome to LEAPERone.",
voice: "alloy",
});
const buffer = Buffer.from(await response.arrayBuffer());
await fs.promises.writeFile("welcome.wav", buffer);
```
选择音色 [#选择音色]
OpenAI 兼容音色 [#openai-兼容音色]
如果你正在从 OpenAI 迁移，可以继续使用熟悉的音色名称：
| 音色 | 对应风格 |
| --------- | ------- |
| `alloy` | 英语，中性 |
| `echo` | 英语，新闻主播 |
| `fable` | 英语，温和 |
| `onyx` | 英语，学术风格 |
| `nova` | 中文，中性 |
| `shimmer` | 中文，柔和 |
特定语言音色 [#特定语言音色]
音色按语言和风格命名，例如 `zh-gentle`、`en-news`、`ja-news`。
```bash title="中文温和音色"
curl -X POST https://api.leaper.one/v1/audio/speech \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"input": "晚安，祝你做个好梦。", "voice": "zh-gentle"}' \
--output goodnight.wav
```
```bash title="日语新闻音色"
curl -X POST https://api.leaper.one/v1/audio/speech \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"input": "本日のニュースをお伝えします。", "voice": "ja-news"}' \
--output news_ja.wav
```
完整音色列表请参阅 [API 参考](/zh/docs/api-reference/audio-speech)。
音色克隆 [#音色克隆]
上传一段简短的音频样本，即可克隆任意音色。该功能需要使用 `multipart/form-data`，不能使用 JSON。
```bash title="克隆音色"
curl -X POST https://api.leaper.one/v1/audio/speech \
-H "Authorization: Bearer sk-your-api-key" \
-F input="This sentence will be spoken in the cloned voice." \
-F prompt_audio=@my-voice-sample.mp3 \
--output cloned.wav
```
**获得良好音色克隆效果的建议：**
* 使用 5 到 15 秒的清晰人声录音
* 尽量减少背景噪声
* 音频文件必须小于 1MB，支持 mp3、wav、flac、m4a、ogg
* 音色克隆在 CPU 上运行，需要 20 到 60 秒
OpenAI SDK 不支持音色克隆，因为该功能需要同时上传文件和文本参数。请使用 `curl` 或直接发送 HTTP 请求。
输出格式 [#输出格式]
| 格式 | 使用场景 |
| --------- | -------------------------------- |
| `wav`（默认） | 可以直接播放的音频文件 |
| `pcm` | 用于后续处理的原始音频（48kHz、16-bit、stereo） |
```bash title="获取 PCM 输出"
curl -X POST https://api.leaper.one/v1/audio/speech \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"input": "Raw PCM output.", "voice": "alloy", "response_format": "pcm"}' \
--output raw.pcm
```
费用按照字符数计算。价格详情请参阅 [API 参考](/zh/docs/api-reference/audio-speech)。
# 视频解析指南 (/zh/docs/guides/video-extract)
从社交媒体分享链接中提取视频下载信息。传入 URL 或原始分享文本，一次请求即可获得多清晰度视频流、音轨、封面图和元数据。
快速开始 [#快速开始]
获取 API 密钥 [#获取-api-密钥]
前往 [Dashboard](https://dashboard.leaper.one/dashboard/settings/api-keys) 创建 API 密钥。
发送请求 [#发送请求]
通过 `url` 参数传入任意受支持的视频 URL：
```bash title="GET /v1/social-media/video/extract"
curl -G "https://api.leaper.one/v1/social-media/video/extract" \
--data-urlencode "url=https://v.douyin.com/L4FJNR3/" \
-H "Authorization: Bearer sk-your-api-key"
```
获取结果 [#获取结果]
响应包含统一格式的元数据和多清晰度下载选项：
```json title="响应"
{
"platform": "douyin",
"data": {
"videoId": "6918273131559881997",
"title": "骑白马的也可以是公主#百万转场变身",
"author": "Real机智张",
"duration": 10,
"videos": [
{ "url": "https://...mp4", "quality": "1080p", "format": "mp4", "width": 1080, "height": 1920 },
{ "url": "https://...mp4", "quality": "720p", "format": "mp4", "width": 720, "height": 1280 }
],
"audios": [
{ "url": "https://...mp3", "format": "mp3" }
]
}
}
```
支持的平台 [#支持的平台]
| 平台 | URL 格式 | 视频 | 音频 | 说明 |
| -------- | ------------------------------------- | --------------------- | --------- | -------------- |
| **抖音** | `v.douyin.com/*` | 多清晰度（1080p/720p/540p） | 背景音乐 MP3 | 与 TikTok 共用解析器 |
| **快手** | `v.kuaishou.com/*`, `*.gifshow.com/*` | 多清晰度 | 支持 | — |
| **哔哩哔哩** | `bilibili.com/video/BV*`, `b23.tv/*` | DASH 多码流 | DASH 独立音轨 | 需要使用 ffmpeg 合并 |
| **小红书** | `xiaohongshu.com/*`, `xhslink.com/*` | H.264/H.265 | — | 支持多种编码 |
| **微博** | `weibo.com/*`, `weibo.cn/*` | 720p/HD/LD | — | — |
| **西瓜视频** | `ixigua.com/*` | 支持 | — | — |
| **皮皮虾** | `pipix.com/*`, `pipixia.com/*` | 高/低清晰度 | — | — |
| 平台 | URL 格式 | 视频 | 音频 | 说明 |
| ------------- | ------------------------------------------------------------- | --------------------- | -------- | ------------ |
| **TikTok** | `tiktok.com/@user/video/*` | 多清晰度（1080p/720p/540p） | 背景音乐 MP3 | 与抖音共用解析器 |
| **YouTube** | `youtube.com/watch?v=*`, `youtu.be/*`, `youtube.com/shorts/*` | 360p–4K、mp4/webm | m4a/weba | 最多返回 20 多种格式 |
| **Instagram** | `instagram.com/reel/*` | 多分辨率 | — | — |
| **Twitter/X** | `x.com/*/status/*`, `twitter.com/*/status/*` | 多码率 | — | 按码率排序 |
**音频说明**：“—”表示音频内嵌在视频文件中，此时 `audios` 返回空数组。哔哩哔哩和 YouTube 使用音视频分离的 DASH 格式，需要使用 ffmpeg 合并。抖音和 TikTok 的 `audios` 是独立的背景音乐文件。
试用地址 [#试用地址]
复制下面任意 URL，即可直接调用 API：
```bash title="抖音"
curl -G "https://api.leaper.one/v1/social-media/video/extract" \
--data-urlencode "url=https://v.douyin.com/L4FJNR3/" \
-H "Authorization: Bearer sk-your-api-key"
```
返回 4 种清晰度选项（1080p 到 540p）和 1 个背景音乐 MP3。
```bash title="TikTok"
curl -G "https://api.leaper.one/v1/social-media/video/extract" \
--data-urlencode "url=https://www.tiktok.com/@bellapoarch/video/6862153058223197445" \
-H "Authorization: Bearer sk-your-api-key"
```
返回 4 种清晰度选项和背景音乐，与抖音使用相同的混合解析器。
```bash title="快手"
curl -G "https://api.leaper.one/v1/social-media/video/extract" \
--data-urlencode "url=https://v.kuaishou.com/dEHKhN" \
-H "Authorization: Bearer sk-your-api-key"
```
返回多清晰度视频流。
```bash title="哔哩哔哩"
curl -G "https://api.leaper.one/v1/social-media/video/extract" \
--data-urlencode "url=https://www.bilibili.com/video/BV1cAQqBqEpT/" \
-H "Authorization: Bearer sk-your-api-key"
```
返回 DASH 格式：6 个不同分辨率的视频流和 3 个不同编码的音频流。使用以下命令合并：
```bash title="使用 ffmpeg 合并"
ffmpeg -i video.mp4 -i audio.m4a -c copy output.mp4
```
```bash title="YouTube"
curl -G "https://api.leaper.one/v1/social-media/video/extract" \
--data-urlencode "url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
-H "Authorization: Bearer sk-your-api-key"
```
返回 20 多种视频格式（360p–4K、mp4/webm）和 4 个音轨（m4a/weba）。
直接粘贴分享文本 [#直接粘贴分享文本]
无需手动提取 URL，直接粘贴任意应用生成的原始分享文本：
```bash title="抖音分享文本"
curl -G "https://api.leaper.one/v1/social-media/video/extract" \
--data-urlencode "url=5.61 复制打开抖音，看看【某某的作品】标题 https://v.douyin.com/xxxxx/ g@B.tE 08/23" \
-H "Authorization: Bearer sk-your-api-key"
```
```bash title="小红书分享文本"
curl -G "https://api.leaper.one/v1/social-media/video/extract" \
--data-urlencode "url=25 【标题 - 作者 | 小红书】 😆 xxxxx 😆 https://www.xiaohongshu.com/discovery/item/xxxxx" \
-H "Authorization: Bearer sk-your-api-key"
```
API 会自动从文本中提取 `https://` 链接并进行解析。
使用场景 [#使用场景]
获取多种分辨率的无水印视频，让用户选择所需清晰度。
提取音轨，再通过音频转写将语音转换为文字。
获取视频标题、作者信息和描述，用于内容再利用或翻译。
从 videos 数组中选择最佳清晰度，并转载到其他平台。
价格 [#价格]
每次成功请求消耗 **$0.01 credit**，失败请求不计费。
视频和音频 URL **具有时效性**，通常在数小时到数天后失效。获取后请及时下载。
完整参数规格和响应结构请参阅 [API 参考](/zh/docs/api-reference/social-media/video-extract)。
# 地址分析 (/zh/docs/api-reference/address/analysis)
`classify-poi` — 地址类型分类 [#classify-poi--地址类型分类]
将地址划分到三级 POI 类目体系中。
```bash
curl -X POST https://api.leaper.one/v1/address/classify-poi \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "北京市朝阳区建国路93号万达广场"}'
```
```json title="Data"
{
"poi_category": "购物#商场#购物中心",
"status": "OK"
}
```
分类结果使用 `#` 分隔三级类目。
***
`predict-poi` — POI 预测 [#predict-poi--poi-预测]
预测与地址关联的详细 POI 信息，并评估置信度。
```bash
curl -X POST https://api.leaper.one/v1/address/predict-poi \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "北京市朝阳区建国路93号万达广场"}'
```
# 基础服务 (/zh/docs/api-reference/address/basic)
`extract` — 地址提取 [#extract--地址提取]
从自然文本中提取地址片段，并移除非地址内容。
```bash
curl -X POST https://api.leaper.one/v1/address/extract \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "张三13812345678北京市朝阳区建国路93号万达广场"}'
```
```json title="Data"
{
"location_extract": [
{ "start": 13, "end": 29, "type": "LOC", "word": "北京市朝阳区建国路93号万达广场" }
]
}
```
***
`extract-name` — 姓名提取 [#extract-name--姓名提取]
从物流文本中识别并提取人员姓名。
```bash
curl -X POST https://api.leaper.one/v1/address/extract-name \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "张三13812345678北京市朝阳区建国路93号"}'
```
```json title="Data"
{
"person_extract": [
{ "start": 0, "end": 2, "word": "张三" }
]
}
```
***
`extract-phone` — 手机号提取 [#extract-phone--手机号提取]
从文本中识别并提取手机号码。
```bash
curl -X POST https://api.leaper.one/v1/address/extract-phone \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "张三13812345678北京市朝阳区建国路93号"}'
```
```json title="Data"
{
"phone_extract": [
{ "start": 2, "end": 13, "word": "13812345678" }
]
}
```
***
`division-code` — 行政区划代码 [#division-code--行政区划代码]
识别给定地址的行政区划代码，包括省、市、区县和街道。
```bash
curl -X POST https://api.leaper.one/v1/address/division-code \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "北京市朝阳区建国路93号"}'
```
```json title="Data"
{
"division_info": {
"divcode": "110105001000",
"division_province": "北京市",
"division_city": "北京市",
"division_district": "朝阳区",
"division_street": "建外街道"
}
}
```
***
`zipcode` — 邮政编码查询 [#zipcode--邮政编码查询]
返回给定地址对应的邮政编码。
```bash
curl -X POST https://api.leaper.one/v1/address/zipcode \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "北京市朝阳区建国路93号"}'
```
```json title="Data"
{
"zipcode": "100011",
"status": "OK"
}
```
# 地址清洗 (/zh/docs/api-reference/address/cleansing)
`structure` — 地址结构化 [#structure--地址结构化]
将地址解析为省、市、区县、街道、道路、门牌号等 23 个结构化字段。
```bash
curl -X POST https://api.leaper.one/v1/address/structure \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "浙江省杭州市余杭区文一西路969号"}'
```
```json title="Data"
{
"structure": "prov=浙江省\tcity=杭州市\tdistrict=余杭区\troad=文一西路\troadNo=969号",
"status": "OK"
}
```
结构化结果使用制表符分隔的 `key=value` 格式。
***
`correct` — 地址纠错 [#correct--地址纠错]
修正地址中的拼写错误，例如错误的行政区名称。
```bash
curl -X POST https://api.leaper.one/v1/address/correct \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "浙江省杭洲市余杭区文一西路969号"}'
```
```json title="Data (corrected 杭洲 → 杭州)"
{
"address_correct": ["浙江省=prov\t杭州市=city\t余杭区=district\t文一西路=road\t969号=roadNo"]
}
```
***
`complete` — 地址补全 [#complete--地址补全]
补全缺失的行政区、道路名称和门牌号。
```bash
curl -X POST https://api.leaper.one/v1/address/complete \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "余杭区文一西路969号"}'
```
```json title="Data (auto-completed province, city, and town)"
{
"complete": "prov=浙江省\tcity=杭州市\tdistrict=余杭区\ttown=五常街道\troad=文一西路\troadNo=969号",
"status": "OK"
}
```
***
`standardize` — 地址标准化 [#standardize--地址标准化]
纠正并补全地址信息，生成规范化的标准地址。
```bash
curl -X POST https://api.leaper.one/v1/address/standardize \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "杭州市余杭区文一西路969号阿里巴巴西溪园区"}'
```
***
`assessment` — 地址异常检测 [#assessment--地址异常检测]
检测地址中的问题，例如非地址文本、地址片段缺失、数字位数错误等。
```bash
curl -X POST https://api.leaper.one/v1/address/assessment \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "随便写的不是地址"}'
```
# 地理编码 (/zh/docs/api-reference/address/geo)
`geocode` — POI 级地理编码 [#geocode--poi-级地理编码]
返回给定地址的经纬度坐标。
```bash
curl -X POST https://api.leaper.one/v1/address/geocode \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "北京市朝阳区建国路93号万达广场"}'
```
```json title="Data"
{
"offline_geocode": {
"wgs84": "116.465328,39.908812",
"gcj02": "116.471607,39.910660"
}
}
```
***
`hp-geocode` — 楼栋级地理编码 [#hp-geocode--楼栋级地理编码]
返回楼栋级高精度经纬度坐标。
```bash
curl -X POST https://api.leaper.one/v1/address/hp-geocode \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "北京市朝阳区建国路93号万达广场"}'
```
***
`transfer-coord` — 坐标系转换 [#transfer-coord--坐标系转换]
在 GCJ02、WGS84、CGCS2000 和 BD09 坐标系之间转换。
此端点的 `text` 参数接收坐标而不是地址，并且必须额外提供 `srcCoord` 参数。
附加参数 [#附加参数]
| 参数 | 类型 | 必填 | 说明 |
| -------- | ------ | -- | -------------------------------------- |
| text | string | 是 | `"longitude,latitude"` 格式的坐标 |
| srcCoord | string | 是 | 源坐标系：`gcj02`、`wgs84`、`cgcs2000`、`bd09` |
| dstCoord | string | 否 | 目标坐标系，省略时返回所有坐标系 |
```bash
curl -X POST https://api.leaper.one/v1/address/transfer-coord \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "116.465,39.909", "srcCoord": "gcj02"}'
```
```json title="Data"
{
"coord_transfer": {
"BD09": "116.471607,39.914660",
"CGCS2000": "116.458867,39.907680",
"WGS84": "116.458867,39.907680",
"GCJ02": "116.465000,39.909000"
}
}
```
# 地址净化 (/zh/docs/api-reference/address)
LEAPERone 通过统一的 RESTful JSON API 提供 22 个地址净化端点，涵盖地址提取、标准化、地理编码等能力。
端点 [#端点]
```
POST https://api.leaper.one/v1/address/:action
```
将 `:action` 替换为具体的 API 操作名称。
身份验证 [#身份验证]
```
Authorization: Bearer sk-your-api-key
```
通用参数 [#通用参数]
所有端点共用以下 JSON 请求体参数：
| 参数 | 类型 | 必填 | 说明 |
| --------------- | ------ | -- | ---------------- |
| text | string | 是 | 需要处理的文本内容 |
| defaultProvince | string | 否 | 默认省份（例如 `"浙江省"`） |
| defaultCity | string | 否 | 默认城市（例如 `"杭州市"`） |
| defaultDistrict | string | 否 | 默认区县（例如 `"余杭区"`） |
通用响应 [#通用响应]
```json
{
"RequestId": "xxx-xxx-xxx",
"Data": "{ ... }"
}
```
`Data` 字段是 JSON 字符串。你需要调用 `JSON.parse(response.Data)` 进行解析。
操作参考 [#操作参考]
| 操作 | 端点 | 说明 | 价格（积分/次） |
| ----------------- | ----------------------------- | --------- | -------- |
| `extract` | `/v1/address/extract` | 地址提取 | $0.004 |
| `extract-name` | `/v1/address/extract-name` | 姓名提取 | $0.004 |
| `extract-phone` | `/v1/address/extract-phone` | 手机号提取 | $0.004 |
| `division-code` | `/v1/address/division-code` | 行政区划代码 | $0.004 |
| `zipcode` | `/v1/address/zipcode` | 邮政编码查询 | $0.004 |
| `structure` | `/v1/address/structure` | 地址结构化 | $0.008 |
| `correct` | `/v1/address/correct` | 地址纠错 | $0.008 |
| `complete` | `/v1/address/complete` | 地址补全 | $0.008 |
| `standardize` | `/v1/address/standardize` | 地址标准化 | $0.008 |
| `assessment` | `/v1/address/assessment` | 地址异常检测 | $0.008 |
| `extract-express` | `/v1/address/extract-express` | 快递面单提取 | $0.008 |
| `search` | `/v1/address/search` | 地址搜索 | $0.008 |
| `input-search` | `/v1/address/input-search` | 地址自动补全 | $0.008 |
| `similarity` | `/v1/address/similarity` | 多地址相似度 | $0.008 |
| `one-id` | `/v1/address/one-id` | 多源地址统一 | $0.008 |
| `geocode` | `/v1/address/geocode` | POI 级地理编码 | $0.008 |
| `hp-geocode` | `/v1/address/hp-geocode` | 楼栋级地理编码 | $0.008 |
| `transfer-coord` | `/v1/address/transfer-coord` | 坐标系转换 | $0.008 |
| `classify-poi` | `/v1/address/classify-poi` | 地址类型分类 | $0.008 |
| `predict-poi` | `/v1/address/predict-poi` | POI 预测 | $0.008 |
| `asr` | `/v1/address/asr` | 语音地址识别 | $0.008 |
| `inference` | `/v1/address/inference` | 对话式地址推理 | $0.008 |
错误代码 [#错误代码]
| HTTP 状态码 | 代码 | 说明 |
| -------- | ---------------------- | ---------- |
| 400 | InvalidParameter | 参数无效 |
| 401 | missing\_api\_key | 未提供 API 密钥 |
| 402 | insufficient\_credits | 余额不足 |
| 403 | Forbidden.NoPermission | 无权访问此端点 |
| 429 | Throttling.User | 超出速率限制 |
| 500 | InternalError | 上游内部错误 |
| 504 | Timeout | 上游请求超时 |
# 智能应用 (/zh/docs/api-reference/address/smart-application)
`similarity` — 多地址相似度 [#similarity--多地址相似度]
判断两个地址是否指向同一地点，并返回相似度分数和距离信息。
由于上游服务问题，此端点目前可能返回 500 错误。
```bash
curl -X POST https://api.leaper.one/v1/address/similarity \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "北京市朝阳区建国路93号\t北京朝阳建国路93号"}'
```
***
`one-id` — 多源地址统一 [#one-id--多源地址统一]
规范化来自不同来源的地址并返回唯一标识符（oneID）。支持 POI 级和房间级统一。
```bash
curl -X POST https://api.leaper.one/v1/address/one-id \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "北京市朝阳区建国路93号万达广场"}'
```
# 智能输入 (/zh/docs/api-reference/address/smart-input)
`extract-express` — 快递面单提取 [#extract-express--快递面单提取]
通过一次调用从快递面单文本中提取姓名、手机号和地址。
```bash
curl -X POST https://api.leaper.one/v1/address/extract-express \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "张三13812345678浙江省杭州市余杭区文一西路969号"}'
```
```json title="Data"
{
"express_extract": {
"person_info": "张三",
"phone_info": "13812345678",
"prov_info": "浙江省",
"city_info": "杭州市",
"district_info": "余杭区",
"road_info": "文一西路",
"road_no_info": "969号",
"poi_info": ""
}
}
```
***
`search` — 地址搜索 [#search--地址搜索]
使用拼音或汉字进行搜索，返回最相关的 5 个 POI 结果。
```bash
curl -X POST https://api.leaper.one/v1/address/search \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "万达广场"}'
```
***
`input-search` — 地址自动补全 [#input-search--地址自动补全]
为搜索框自动补全提供详细的地址建议。支持拼音、汉字和其他输入形式。
```bash
curl -X POST https://api.leaper.one/v1/address/input-search \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "万达"}'
```
# 语音与对话 (/zh/docs/api-reference/address/voice)
`asr` — 语音地址识别 [#asr--语音地址识别]
处理 ASR（自动语音识别）转写的地址文本，并输出标准化地址信息。适合对语音输入的地址进行后处理。
```bash
curl -X POST https://api.leaper.one/v1/address/asr \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "杭州余杭文一西路九六九号"}'
```
***
`inference` — 对话式地址推理 [#inference--对话式地址推理]
通过多轮对话推理识别地址，并返回最相关的 3 个候选结果。适合智能客服、语音助手和其他对话场景。
```bash
curl -X POST https://api.leaper.one/v1/address/inference \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "杭州那个阿里巴巴在的地方"}'
```
# 社交媒体数据 API (/zh/docs/api-reference/social-media/data-api)
通过一个 API 访问 **16 个社交媒体平台的 800 多个端点**。你可以获取视频、用户资料、评论、搜索结果、直播、热门内容等数据。
端点 [#端点]
```
GET https://api.leaper.one/v1/social-media/data/{platform}/{interface}/{action}
```
所有查询参数都会转发给上游服务，响应以原始格式返回。
快速开始 [#快速开始]
```bash
curl -G "https://api.leaper.one/v1/social-media/data/bilibili/web/fetch_one_video" \
--data-urlencode "url=https://www.bilibili.com/video/BV1GJ411x7h7" \
-H "Authorization: Bearer sk-your-api-key"
```
支持的平台 [#支持的平台]
| 平台 | 前缀 | 端点数 | 功能 |
| --------- | -------------- | --- | ---------------------- |
| 抖音 | `douyin/` | 248 | 视频、用户、搜索、直播、榜单、创作者数据分析 |
| TikTok | `tiktok/` | 109 | 视频、用户、搜索、热门内容、评论、话题标签 |
| Bilibili | `bilibili/` | 41 | 视频、用户、搜索、直播、弹幕、字幕 |
| YouTube | `youtube/` | 25 | 视频、频道、搜索、评论、播放列表 |
| Instagram | `instagram/` | 52 | 帖子、Reels、快拍、用户资料、搜索 |
| Twitter/X | `twitter/` | 28 | 推文、用户、搜索、趋势、Spaces |
| 微博 | `weibo/` | 30 | 帖子、用户、搜索、热门内容 |
| 小红书 | `xiaohongshu/` | 38 | 笔记、用户、搜索 |
| 快手 | `kuaishou/` | 29 | 视频、用户、搜索、直播 |
| 微信 | `wechat/` | 8 | 公众号、视频号 |
| Threads | `threads/` | 11 | 帖子、用户资料 |
| LinkedIn | `linkedin/` | 4 | 用户资料、帖子 |
| 知乎 | `zhihu/` | 6 | 回答、文章、用户 |
| Lemon8 | `lemon8/` | 8 | 帖子、用户 |
| 网易云音乐 | `netease/` | 12 | 歌曲、播放列表、用户 |
| Reddit | `reddit/` | 9 | 帖子、子版块、评论 |
| 混合模式 | `hybrid/` | 2 | 从 URL 自动识别平台 |
如需查看所有端点及其参数的完整列表，请获取 `GET https://api.leaper.one/openapi.json` 提供的 OpenAPI 规范。该规范包含每个可用端点和完整的参数定义。
平台示例 [#平台示例]
Bilibili [#bilibili]
```bash
# Get video details
curl -G "https://api.leaper.one/v1/social-media/data/bilibili/web/fetch_video_detail" \
--data-urlencode "bvid=BV1GJ411x7h7" \
-H "Authorization: Bearer sk-your-api-key"
# Get video play URL (for downloading)
curl -G "https://api.leaper.one/v1/social-media/data/bilibili/web/fetch_video_playurl" \
--data-urlencode "bvid=BV1GJ411x7h7" \
--data-urlencode "cid=171776208" \
-H "Authorization: Bearer sk-your-api-key"
# Get user profile
curl -G "https://api.leaper.one/v1/social-media/data/bilibili/web/fetch_user_profile" \
--data-urlencode "uid=546195" \
-H "Authorization: Bearer sk-your-api-key"
# Search videos
curl -G "https://api.leaper.one/v1/social-media/data/bilibili/web/fetch_general_search" \
--data-urlencode "keyword=programming" \
-H "Authorization: Bearer sk-your-api-key"
# Get video comments
curl -G "https://api.leaper.one/v1/social-media/data/bilibili/web/fetch_video_comments" \
--data-urlencode "bvid=BV1GJ411x7h7" \
-H "Authorization: Bearer sk-your-api-key"
# Get video danmaku (bullet comments)
curl -G "https://api.leaper.one/v1/social-media/data/bilibili/web/fetch_video_danmaku" \
--data-urlencode "cid=171776208" \
-H "Authorization: Bearer sk-your-api-key"
# Get video subtitles
curl -G "https://api.leaper.one/v1/social-media/data/bilibili/web/fetch_video_subtitle" \
--data-urlencode "bvid=BV1GJ411x7h7" \
-H "Authorization: Bearer sk-your-api-key"
```
**Bilibili 主要端点：**
| 端点 | 说明 |
| ------------------------------------- | -------------- |
| `bilibili/web/fetch_one_video` | 通过 URL 获取视频 |
| `bilibili/web/fetch_video_detail` | 通过 BV 号获取视频详情 |
| `bilibili/web/fetch_video_playurl` | 获取视频播放或下载地址 |
| `bilibili/web/fetch_video_comments` | 获取视频评论 |
| `bilibili/web/fetch_video_danmaku` | 获取弹幕 |
| `bilibili/web/fetch_video_subtitle` | 获取字幕 |
| `bilibili/web/fetch_user_profile` | 获取用户资料 |
| `bilibili/web/fetch_user_post_videos` | 获取用户上传的视频 |
| `bilibili/web/fetch_general_search` | 搜索视频 |
| `bilibili/web/fetch_hot_search` | 获取热门搜索 |
| `bilibili/web/fetch_live_room_detail` | 获取直播间信息 |
| `bilibili/web/bv_to_aid` | 将 BV 号转换为 AV 号 |
抖音 [#抖音]
```bash
# Get video by share URL
curl -G "https://api.leaper.one/v1/social-media/data/douyin/web/fetch_one_video_by_share_url" \
--data-urlencode "url=https://v.douyin.com/L4FJNR3/" \
-H "Authorization: Bearer sk-your-api-key"
# Get video by aweme_id
curl -G "https://api.leaper.one/v1/social-media/data/douyin/web/fetch_one_video" \
--data-urlencode "aweme_id=7123456789" \
-H "Authorization: Bearer sk-your-api-key"
# Search videos
curl -G "https://api.leaper.one/v1/social-media/data/douyin/web/fetch_general_search_result" \
--data-urlencode "keyword=cooking" \
-H "Authorization: Bearer sk-your-api-key"
```
TikTok [#tiktok]
```bash
# Get video details
curl -G "https://api.leaper.one/v1/social-media/data/tiktok/web/fetch_post_detail" \
--data-urlencode "aweme_id=7123456789" \
-H "Authorization: Bearer sk-your-api-key"
# Get user profile
curl -G "https://api.leaper.one/v1/social-media/data/tiktok/web/fetch_user_profile" \
--data-urlencode "secUid=MS4wLjABAAAA..." \
-H "Authorization: Bearer sk-your-api-key"
# Search
curl -G "https://api.leaper.one/v1/social-media/data/tiktok/web/fetch_search_video" \
--data-urlencode "keyword=dance" \
-H "Authorization: Bearer sk-your-api-key"
```
YouTube [#youtube]
```bash
# Get video info
curl -G "https://api.leaper.one/v1/social-media/data/youtube/web/get_video_info" \
--data-urlencode "video_id=dQw4w9WgXcQ" \
-H "Authorization: Bearer sk-your-api-key"
# Get channel info
curl -G "https://api.leaper.one/v1/social-media/data/youtube/web/get_channel_info" \
--data-urlencode "channel_id=UCuAXFkgsw1L7xaCfnd5JJOw" \
-H "Authorization: Bearer sk-your-api-key"
```
Instagram [#instagram]
```bash
# Get post by URL
curl -G "https://api.leaper.one/v1/social-media/data/instagram/v1/fetch_post_by_url" \
--data-urlencode "url=https://www.instagram.com/p/ABC123/" \
-H "Authorization: Bearer sk-your-api-key"
# Get user profile
curl -G "https://api.leaper.one/v1/social-media/data/instagram/web/fetch_user_info_by_username" \
--data-urlencode "username=instagram" \
-H "Authorization: Bearer sk-your-api-key"
```
Twitter/X [#twitterx]
```bash
# Get tweet details
curl -G "https://api.leaper.one/v1/social-media/data/twitter/web/fetch_tweet_detail" \
--data-urlencode "tweet_id=1234567890" \
-H "Authorization: Bearer sk-your-api-key"
# Get user profile
curl -G "https://api.leaper.one/v1/social-media/data/twitter/web/fetch_user_profile" \
--data-urlencode "screen_name=elonmusk" \
-H "Authorization: Bearer sk-your-api-key"
```
混合模式（自动识别平台） [#混合模式自动识别平台]
```bash
# Auto-detect platform from any social media URL
curl -G "https://api.leaper.one/v1/social-media/data/hybrid/video_data" \
--data-urlencode "url=https://v.douyin.com/L4FJNR3/" \
-H "Authorization: Bearer sk-your-api-key"
```
响应格式 [#响应格式]
通用响应结构如下：
```json
{
"code": 200,
"data": {
// Platform-specific data
}
}
```
`code: 200` 或 `code: 0` 表示请求成功。
错误响应 [#错误响应]
路径无效（400） [#路径无效400]
```json
{ "error": { "message": "Invalid path", "type": "invalid_request_error" } }
```
平台不可用（403） [#平台不可用403]
```json
{ "error": { "message": "Platform \"admin\" is not available", "type": "invalid_request_error" } }
```
上游超时（504） [#上游超时504]
```json
{ "error": { "message": "Upstream request timed out", "type": "server_error" } }
```
上游不可用（503） [#上游不可用503]
```json
{ "error": { "message": "Failed to reach upstream service", "type": "server_error" } }
```
价格 [#价格]
**每次成功请求 $0.01。** 请求失败（HTTP 4xx/5xx）不会计费。
与视频解析 API 的比较 [#与视频解析-api-的比较]
| 功能 | 视频解析 API | 社交媒体数据 API |
| ---- | ------------------------------------ | ----------------------------- |
| 端点 | `GET /v1/social-media/video/extract` | `GET /v1/social-media/data/*` |
| 输入 | 任意社交媒体 URL | 平台专用 API 路径和参数 |
| 响应 | 标准化格式 | 上游原始响应 |
| 使用场景 | 快速下载视频 | 访问完整的平台 API |
| 范围 | 仅视频解析 | 覆盖 16 个平台的 800 多个端点 |
| 价格 | $0.01/次 | $0.01/次 |
**提示：** 如果只需要通过 URL 下载视频，请使用 [视频解析 API](/zh/docs/api-reference/social-media/video-extract)，它的接口更简单，响应格式也经过标准化。需要用户资料、搜索、评论、直播等完整平台功能时，请使用社交媒体数据 API。
注意事项 [#注意事项]
* 所有端点都使用 GET 请求，并通过查询字符串传递参数。
* 媒体 URL（视频、图片）通常具有时效性。获取后请尽快下载。
* 部分端点可能需要平台专用 ID。如有需要，请先调用相应的搜索或查询端点。
* 如需包含所有参数的完整端点目录，请将 [OpenAPI 规范](/openapi.json) 导入 Postman 或 Swagger UI。
# 视频解析 API (/zh/docs/api-reference/social-media/video-extract)
从社交媒体分享链接中提取视频下载信息，包括多清晰度视频流、独立音频流、封面图片和元数据。
端点 [#端点]
```
GET https://api.leaper.one/v1/social-media/video/extract
```
参数 [#参数]
| 参数 | 类型 | 必填 | 说明 |
| ----- | ------ | -- | -------------------- |
| `url` | string | 是 | 视频 URL 或包含 URL 的分享文本 |
`url` 参数既可以接收视频直链，也可以接收从平台复制的原始分享文本。API 会自动从文本中提取 URL。
支持的平台 [#支持的平台]
| 平台 | URL 格式 | `paramName` | 视频输出 | 音频输出 |
| --------- | ------------------------------------- | ---------------- | -------------------- | --------- |
| 抖音 | `v.douyin.com/*`、`*.douyin.com/*` | `url` | 多清晰度 1080p/720p/540p | 背景音乐 MP3 |
| TikTok | `*.tiktok.com/*` | `url` | 多清晰度 | 背景音乐 MP3 |
| 快手 | `*.kuaishou.com/*`、`*.gifshow.com/*` | `url` | 多清晰度 | 有 |
| 小红书 | `*.xiaohongshu.com/*`、`xhslink.com/*` | `share_text` | H.264/H.265 | — |
| Instagram | `*.instagram.com/*` | `post_url` | 多分辨率 | — |
| Bilibili | `bilibili.com/video/BV*`、`b23.tv/*` | `url`（提取 BV 号） | DASH 多流 | DASH 独立音频 |
| YouTube | `youtube.com/watch?v=*`、`youtu.be/*` | `video_id`（自动提取） | 360p–4K、mp4/webm | m4a/weba |
| Twitter/X | `x.com/*/status/*`、`twitter.com/*` | `tweet_id`（自动提取） | 多码率 MP4 | — |
| 微博 | `weibo.com/*`、`weibo.cn/*` | `id`（自动提取） | 720p/HD/LD | — |
| 西瓜视频 | `ixigua.com/*` | `item_id`（自动提取） | 有 | — |
| 皮皮虾 | `pipix.com/*`、`pipixia.com/*` | `cell_id`（自动提取） | 高/低清晰度 | — |
“—”表示音频已嵌入视频文件中（`audios` 为空数组）。Bilibili 和 YouTube 使用音视频分离的 DASH 格式，下载后需要使用 ffmpeg 合并。
请求 [#请求]
```bash title="GET /v1/social-media/video/extract"
curl -G "https://api.leaper.one/v1/social-media/video/extract" \
--data-urlencode "url=https://v.douyin.com/L4FJNR3/" \
-H "Authorization: Bearer sk-your-api-key"
```
响应示例 [#响应示例]
返回多种清晰度的视频选项和背景音乐 MP3。
```json title="Response"
{
"platform": "douyin",
"data": {
"platform": "douyin",
"videoId": "6918273131559881997",
"title": "骑白马的也可以是公主#百万转场变身",
"author": "Real机智张",
"authorId": "MS4wLjABAAAA...",
"coverUrl": "https://p3-sign.douyinpic.com/...webp",
"duration": 10,
"videos": [
{ "url": "https://...mp4", "quality": "adapt_lowest_1080_1", "format": "mp4", "width": 1080, "height": 1920, "size": 3455733 },
{ "url": "https://...mp4", "quality": "adapt_lowest_720_1", "format": "mp4", "width": 720, "height": 1280, "size": 2205160 },
{ "url": "https://...mp4", "quality": "adapt_540_1", "format": "mp4", "width": 576, "height": 1024, "size": 1681820 }
],
"audios": [
{ "url": "https://sf6-cdn-tos.douyinstatic.com/...mp3", "format": "mp3" }
]
}
}
```
使用音视频分离的 DASH 格式。请使用 ffmpeg 合并。
```json title="Response"
{
"platform": "bilibili",
"data": {
"platform": "bilibili",
"videoId": "BV1cAQqBqEpT",
"title": "《万历黑诏书》第七十一话：帝王之术",
"author": "虾仁耶YE",
"authorId": "21741349",
"coverUrl": "http://i1.hdslb.com/bfs/archive/...jpg",
"duration": 545,
"videos": [
{ "url": "https://...bilivideo.com/...mp4", "quality": "480p", "format": "mp4", "codec": "avc1.640033", "width": 852, "height": 480 }
],
"audios": [
{ "url": "https://...bilivideo.com/...m4s", "format": "m4a", "codec": "mp4a.40.2" }
]
}
}
```
```bash title="Merge with ffmpeg"
ffmpeg -i video.mp4 -i audio.m4a -c copy output.mp4
```
返回 20 多种视频格式（360p 至 4K）和多条音轨。
```json title="Response"
{
"platform": "youtube",
"data": {
"platform": "youtube",
"videoId": "dQw4w9WgXcQ",
"title": "Rick Astley - Never Gonna Give You Up (Official Video)",
"author": "Rick Astley",
"authorId": "UCuAXFkgsw1L7xaCfnd5JJOw",
"coverUrl": "https://i.ytimg.com/vi_webp/dQw4w9WgXcQ/maxresdefault.webp",
"duration": 213,
"videos": [
{ "url": "https://...googlevideo.com/...", "quality": "360p", "format": "mp4", "codec": "avc1.42001E, mp4a.40.2", "width": 640, "height": 360, "size": 11829048 },
{ "url": "https://...googlevideo.com/...", "quality": "720p", "format": "mp4", "codec": "avc1.4d401f", "width": 1280, "height": 720 },
{ "url": "https://...googlevideo.com/...", "quality": "1080p", "format": "webm", "codec": "vp9", "width": 1920, "height": 1080 }
],
"audios": [
{ "url": "https://...googlevideo.com/...", "format": "m4a", "codec": "mp4a.40.2", "size": 3449447 },
{ "url": "https://...googlevideo.com/...", "format": "weba", "codec": "opus", "size": 1231355 }
]
}
}
```
YouTube 的 360p mp4 通常包含音轨，可以直接播放。更高分辨率的视频流通常不含音频，需要与 `audios` 中的音频流合并。
返回多种清晰度的视频流。
```json title="Response"
{
"platform": "kuaishou",
"data": {
"platform": "kuaishou",
"videoId": "5229242270556079433",
"title": "@爱笑岩❗️还在努力. #三道街 #爱笑岩 #爱笑岩安利挑战",
"author": "捕风在努力",
"authorId": "1152464658",
"coverUrl": "https://p3.a.kwimgs.com/...jpg",
"duration": 103,
"videos": [
{ "url": "https://tymov2.a.kwimgs.com/...mp4", "format": "mp4" },
{ "url": "https://tymov2.a.kwimgs.com/...mp4", "format": "mp4" }
],
"audios": []
}
}
```
测试 URL [#测试-url]
复制以下 URL，直接调用 API 进行测试：
| 平台 | 测试 URL |
| -------- | --------------------------------------------------------------- |
| 抖音 | `https://v.douyin.com/L4FJNR3/` |
| TikTok | `https://www.tiktok.com/@bellapoarch/video/6862153058223197445` |
| 快手 | `https://v.kuaishou.com/dEHKhN` |
| Bilibili | `https://www.bilibili.com/video/BV1cAQqBqEpT/` |
| YouTube | `https://www.youtube.com/watch?v=dQw4w9WgXcQ` |
响应字段 [#响应字段]
| 字段 | 类型 | 说明 |
| --------------- | -------------- | ------------------------ |
| `platform` | string | 检测到的平台名称 |
| `data` | object \| null | 标准化后的视频数据。标准化失败时为 `null` |
| `data.platform` | string | 平台名称 |
| `data.videoId` | string | 视频在平台上的 ID |
| `data.title` | string | 视频标题或描述 |
| `data.author` | string | 作者显示名称 |
| `data.authorId` | string | 作者在平台上的 ID |
| `data.coverUrl` | string | 封面图片 URL |
| `data.duration` | number | 时长，单位为秒 |
| `data.videos` | MediaItem\[] | 可用的视频下载选项 |
| `data.audios` | MediaItem\[] | 可用的音频下载选项；音频嵌入视频时为空数组 |
| `raw` | object | 上游原始响应，仅在标准化失败时返回 |
MediaItem [#mediaitem]
| 字段 | 类型 | 说明 |
| --------- | ------- | --------------------------------------------------- |
| `url` | string | 下载 URL |
| `quality` | string? | 清晰度标签：`"1080p"`、`"720p"`、`"480p"` 等 |
| `format` | string? | 文件格式：`"mp4"`、`"webm"`、`"m4a"`、`"mp3"`、`"weba"` |
| `codec` | string? | 编解码器：`"avc1.640033"`、`"mp4a.40.2"`、`"opus"`、`"vp9"` |
| `width` | number? | 视频宽度，单位为像素 |
| `height` | number? | 视频高度，单位为像素 |
| `size` | number? | 文件大小，单位为字节 |
错误响应 [#错误响应]
```json
{ "error": { "message": "\"url\" query parameter is required", "type": "invalid_request_error" } }
```
```json
{ "error": { "message": "Could not find a valid URL in the input", "type": "invalid_request_error" } }
```
```json
{
"error": { "message": "Unsupported platform", "type": "invalid_request_error" }
}
```
支持的平台：douyin、kuaishou、xiaohongshu、instagram、bilibili、youtube、twitter、weibo、xigua、pipixia。
```json
{ "error": { "message": "Failed to proxy request", "type": "server_error" } }
```
上游数据提供方暂时无法访问。
```json
{ "error": { "message": "Upstream request timed out", "type": "server_error" } }
```
请求耗时超过 30 秒。请重试或更换视频 URL。
价格 [#价格]
**每次成功请求 $0.01**（HTTP 2xx）。请求失败不会计费。
注意事项 [#注意事项]
* 视频和音频 URL 具有时效性，通常在数小时至数天后失效。获取后请尽快下载。
* 抖音和 TikTok 共用混合解析器，一个端点同时支持两个平台。
* 小红书支持完整 URL 和短链接（`xhslink.com`）。
* `duration` 的单位始终为秒。
* 当 `data` 为 `null` 时，`raw` 字段会包含未经处理的上游响应，便于调试。