# UnderSky (/zh/docs)
一个 API Key，调用主流 AI 模型和开发者服务。
```bash title="第一次 API 调用"
curl -X POST https://api.undersky.ai/v1/chat/completions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"Hello!"}]}'
```
## UnderSky 是什么？ [#undersky-是什么]
UnderSky 是统一的 AI API 网关。你可以用一个 API Key 调用对话补全、图片生成、音频转写等服务。
* **兼容 OpenAI** — 可直接替换现有接口，无需修改业务代码
* **按量计费** — 使用透明的点数计费
* **CLI 与控制台** — 管理 API Key、查询余额和查看用量
## 下一步 [#下一步]
获取 API Key，并在几分钟内完成第一次请求。
了解认证、模型和各个 API 端点。
查看所有端点的完整参数说明。
# 快速开始 (/zh/docs/quickstart)
## 1. 创建账户 [#1-创建账户]
前往 [Dashboard](https://dashboard.undersky.ai/signin)，使用 GitHub 或 Google 登录。
## 2. 获取 API Key [#2-获取-api-key]
进入 **Dashboard → Settings → API Keys** 并创建新的 Key。API Key 以 `sk-` 开头。
请安全保存 API Key。完整 Key 只会显示一次。
## 3. 发起第一次请求 [#3-发起第一次请求]
选择接入方式前，先查询当前模型：
```bash
curl -sS https://api.undersky.ai/v1/models | jq '.data[] | .id'
```
```bash title="Chat Completion"
curl -X POST https://api.undersky.ai/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-查询余额]
在 **Dashboard → Settings → Credit & Usage** 查看余额与近期用量。
服务集成可以使用带有 `credits:read` 权限的控制令牌：
```bash
curl https://api.undersky.ai/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) — 异步图片生成流程
# 语音合成 API (/zh/docs/api-reference/audio-speech)
该端点由 UnderSky Rust 网关实现，实际可用性取决于上游供应商和媒体存储配置。
把文本合成为语音音频。支持预设音色和自定义声音克隆。
## 端点 [#端点]
```
POST https://api.undersky.ai/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.undersky.ai/v1/audio/speech \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "moss-tts-nano",
"input": "Hello, welcome to UnderSky.",
"voice": "alloy"
}' \
--output speech.wav
```
### 使用自定义音频克隆声音 [#使用自定义音频克隆声音]
```bash
curl -X POST https://api.undersky.ai/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.undersky.ai/v1",
api_key="sk-your-api-key"
)
response = client.audio.speech.create(
model="moss-tts-nano",
input="Hello, welcome to UnderSky.",
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)
该端点由 UnderSky Rust 网关实现，实际可用性取决于上游供应商和媒体存储配置。
把音频转写为文本。支持直接上传文件或传入 URL。
## 端点 [#端点]
```
POST https://api.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/v1/audio/transcriptions \
-H "Authorization: Bearer sk-your-api-key" \
-F file=@recording.mp3 \
-F model=whisper-1 \
-F response_format=json \
-F prompt="UnderSky, GTC, NVIDIA"
```
### 请求字幕格式 [#请求字幕格式]
```bash
curl -X POST https://api.undersky.ai/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.undersky.ai/v1/chat/completions
```
## 参数 [#参数]
| 参数 | 类型 | 必填 | 说明 |
| ---------------- | ---------------- | -- | -------------------------------------------------------------- |
| model | string | 是 | 使用下方支持模型表中的模型 ID |
| 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" }` |
## 支持的模型 [#支持的模型]
| 模型 ID | 名称 |
| ------------------- | ----------------------------- |
| `auto` | Auto |
| `gpt-5-nano` | GPT-5 Nano |
| `gpt-5.4` | GPT-5.4 |
| `gpt-5.4-mini` | GPT-5.4 Mini |
| `gpt-5.5` | GPT-5.5 |
| `gpt-6-luna` | GPT-6 Luna |
| `gpt-6-sol` | GPT-6 Sol |
| `gpt-6-astra` | GPT-6 Astra |
| `claude-fable-5` | Claude Fable 5 |
| `claude-opus-4-8` | Claude Opus 4.8 |
| `claude-opus-4-7` | Claude Opus 4.7 |
| `claude-opus-4-6` | Claude Opus 4.6 |
| `claude-sonnet-5` | Claude Sonnet 5 |
| `claude-sonnet-4-6` | Claude Sonnet 4.6 |
| `claude-haiku-4-5` | Claude Haiku 4.5 |
| `deepseek-v4-flash` | DeepSeek V4 Flash |
| `deepseek-v4-pro` | DeepSeek V4 Pro |
| `openrouter/*` | Live OpenRouter model catalog |
## 请求 [#请求]
```bash
curl -X POST https://api.undersky.ai/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 UnderSky?" }
],
"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": "UnderSky 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-6-luna`。
* `stream` 为 `true` 时，接口通过 **Server-Sent Events**（SSE）返回增量内容，并以 `[DONE]` 消息结束。
* 按最终解析出的模型和实际 token 用量计费。
* **OpenRouter 模型**：使用 `"openrouter/{provider}/{model}"`（例如 `"openrouter/anthropic/claude-sonnet-4.6"`）调用实时目录中的模型。价格透传自 OpenRouter。详情参阅 [Chat Completions 指南](/zh/docs/guides/chat-completions#openrouter-模型)。
# Decisions API（Jev / System One） (/zh/docs/api-reference/decisions)
对一段 `state` 提交类型化问题（`noul` / `choice` / `score`），由 TypeSafe Jev（经 OpenRouter）完成评估。UnderSky 使用你的 API Key 鉴权，并按上游成本做 pass-through 计费。
## 端点 [#端点]
```
POST https://api.undersky.ai/v1/decisions
POST https://api.undersky.ai/api/alpha/decisions
```
`/api/alpha/decisions` 与 OpenRouter Decisions 路径一致，便于把 `https://openrouter.ai` 换成 `https://api.undersky.ai`。处理逻辑、鉴权、RPM 桶与计费与 `/v1/decisions` 相同。
## 身份认证 [#身份认证]
使用 UnderSky API Key：
* `Authorization: Bearer sk-your-api-key`
## 参数 [#参数]
请求体遵循 OpenRouter Decisions 原生格式。必填字段：
| 参数 | 类型 | 必填 | 说明 |
| --------- | ------------------------- | -- | ---------------------------------------------- |
| model | string | 是 | Jev 模型 ID（见下表）。可选 `openrouter/` 目录前缀。 |
| state | string \| object \| array | 是 | 待评估内容。 |
| questions | object | 是 | 问题 id → 类型化问题（`noul` / `choice` / `score`）的映射。 |
每个问题都需要 `type` 和 `instructions`。`choice` 还需要 `criteria` 对象，将选项 ID 映射到描述；`score` 则需要有序的 `criteria` 描述数组。
## 支持的模型 [#支持的模型]
| 模型 ID | 名称 |
| --------------------------------- | ------------------------------ |
| `~typesafe/jev-latest` | Jev Latest |
| `typesafe/jev-1.13` | Jev 1.13 |
| `openrouter/~typesafe/jev-latest` | Jev Latest (OpenRouter prefix) |
| `openrouter/typesafe/jev-1.13` | Jev 1.13 (OpenRouter prefix) |
可选的 `openrouter/` 前缀在转发上游前会被剥离，因此目录 ID 与 OpenRouter 风格 ID 均可使用。
## 定价 [#定价]
Pass-through：按上游响应中的 `usage`（`input_tokens`、`output_tokens`、`cost`）折算为 UnderSky 积分。参阅[定价](/zh/pricing)。
## 限流 [#限流]
与 **Chat** RPM 档位共用同一配置（与 Chat Completions 相同）。`/api/alpha/decisions` 别名映射到同一 `/v1/decisions` 限流键。参阅[速率限制](/zh/docs/advanced/rate-limits)。
## 请求（curl） [#请求curl]
```bash
curl -X POST https://api.undersky.ai/v1/decisions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "~typesafe/jev-latest",
"state": {
"ticket": "Customer paid twice for the same order",
"amount_usd": 48
},
"questions": {
"should_refund": {
"type": "noul",
"instructions": "Should we issue a full refund?"
},
"primary_reason": {
"type": "choice",
"instructions": "Primary reason category",
"criteria": {
"duplicate_charge": "The same order was charged more than once.",
"defective": "The product was defective.",
"late_delivery": "The delivery was late.",
"other": "Another reason applies."
}
},
"confidence": {
"type": "score",
"instructions": "Confidence that the refund is warranted (0-1)",
"criteria": ["A full refund is not warranted.", "A full refund is warranted."]
}
}
}'
```
OpenRouter 路径别名（请求体相同）：
```bash
curl -X POST https://api.undersky.ai/api/alpha/decisions \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "typesafe/jev-1.13",
"state": "Blank checkout page after payment redirect",
"questions": {
"is_incident": {
"type": "noul",
"instructions": "Is this a production incident?"
}
}
}'
```
## 响应 [#响应]
成功时透传 OpenRouter 响应，通常包含 `answers` 与 `usage`（token 与成本）。具体字段以上游 Decisions 契约为准。
## 注意事项 [#注意事项]
* API 侧需配置 Decisions 上游（`OPENROUTER_API_KEY`）。
* 上游超时为 60 秒。
* Chat / Responses / Messages 仍走各自端点；Decisions 仅用于类型化的 Jev 评估。
# 图片生成（创建任务） (/zh/docs/api-reference/images-create)
该端点由 UnderSky Rust 网关实现，实际可用性取决于上游供应商和媒体存储配置。
提交异步图片生成请求。接口返回任务 ID，你可以通过[图片生成状态](/zh/docs/api-reference/images-status)端点轮询结果。
## 端点 [#端点]
```
POST https://api.undersky.ai/v1/images/generations
```
## 参数 [#参数]
| 参数 | 类型 | 必填 | 说明 |
| --------------- | ------------------- | -- | -------------------------------------------------- |
| prompt | string | 是 | 要生成图片的文本描述 |
| model | string | 是 | 使用下方支持模型表中的模型 ID |
| referenceImages | string \| string\[] | 否 | 用于风格或内容参考的图片 URL |
| number | number | 否 | 生成图片数量，范围 1-4。默认：`1` |
| size | string | 否 | 图片尺寸，例如 `"1024x1024"`；或宽高比，例如 `"9:16"`。具体支持情况取决于模型 |
| callbackUrl | string | 否 | 生成完成后接收 POST 请求的 Webhook URL |
## 支持的模型 [#支持的模型]
| 模型 ID | 名称 | 售价 |
| -------------------------------- | ------------------------------ | -------------------: |
| `gpt-4o-image` | GPT-4o Image | 0.5 credits/张 |
| `gpt-image-2` | GPT Image 2 | 0.01 credits/张 |
| `gemini-3.1-flash-image-preview` | Gemini 3.1 Flash Image Preview | 约 0.081714 credits/张 |
## 请求 [#请求]
```bash
curl -X POST https://api.undersky.ai/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"
}
}
```
## 注意事项 [#注意事项]
* 创建任务时预占 `模型单价 × number` 的额度，成功后按实际生成张数结算。
* 任务失败会释放全部预占额度；部分成功只收取成功图片的费用。
* 余额不足时，API 返回 **402 Payment Required**。
* 使用返回的 `id` 通过[状态端点](/zh/docs/api-reference/images-status)轮询结果。
# 图片生成（查询状态） (/zh/docs/api-reference/images-status)
该端点由 UnderSky Rust 网关实现，实际可用性取决于上游供应商和媒体存储配置。
查询图片生成任务状态，并在任务完成后获取生成的图片。
## 端点 [#端点]
```
GET https://api.undersky.ai/v1/images/generations/:id
```
## 参数 [#参数]
| 参数 | 类型 | 必填 | 说明 |
| -- | ------------ | -- | ------------------------------------------------------------- |
| id | string（路径参数） | 是 | 图片生成任务 UUID，由[创建任务端点](/zh/docs/api-reference/images-create)返回 |
## 请求 [#请求]
```bash
curl https://api.undersky.ai/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://cdn.example.com/images/generated/abc123?token=example"
}
]
}
}
```
## 状态值 [#状态值]
| 状态 | 说明 |
| ------------ | ----------------------------- |
| `reserved` | 已预占额度，等待新版 worker 认领 |
| `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` 指向 UnderSky。
## 端点 [#端点]
```
POST https://api.undersky.ai/v1/messages
```
## 身份认证 [#身份认证]
使用与兼容 OpenAI 端点相同的 UnderSky API Key。以下两种请求头都可以使用：
* `Authorization: Bearer sk-your-api-key`
* `x-api-key: sk-your-api-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 Fable 5 |
| `claude-opus-4-8` | Claude Opus 4.8 |
| `claude-opus-4-7` | Claude Opus 4.7 |
| `claude-opus-4-6` | Claude Opus 4.6 |
| `claude-sonnet-5` | Claude Sonnet 5 |
| `claude-sonnet-4-6` | Claude Sonnet 4.6 |
| `claude-haiku-4-5` | Claude Haiku 4.5 |
| `deepseek-v4-flash` | DeepSeek V4 Flash |
| `deepseek-v4-pro` | DeepSeek V4 Pro |
价格与 Chat Completions 网关一致，单位为每 100 万 token 的美元价格。参阅[模型列表](/zh/docs/api-reference/models)。
## 请求（curl） [#请求curl]
```bash
curl -X POST https://api.undersky.ai/v1/messages \
-H "Authorization: Bearer sk-your-api-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-api-key",
base_url="https://api.undersky.ai",
)
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` 中累计；UnderSky 按最终合并的用量计费。
## 注意事项 [#注意事项]
* GPT 和 Auto 路由仍使用 [`/v1/chat/completions`](/zh/docs/api-reference/chat-completions)。
* Claude 的工具调用、视觉输入（图片内容块）和扩展思考会原样透传。DeepSeek 能力取决于其上游兼容 Anthropic 的 API。
* 扩展思考和大上下文等长请求目前共用 120 秒上游超时。接近限制时请拆分重任务。
# 模型列表 (/zh/docs/api-reference/models)
列出所有可用模型。此端点公开访问，不需要身份认证。
## 端点 [#端点]
```
GET https://api.undersky.ai/v1/models
```
## 响应 [#响应]
返回当前内置模型和 OpenRouter 模型对象列表。模型目录会随时间变化。
```json
{
"object": "list",
"data": [
{
"id": "auto",
"object": "model",
"created": 0,
"owned_by": "undersky",
"name": "Auto"
},
{
"id": "gpt-5-nano",
"object": "model",
"created": 0,
"owned_by": "undersky",
"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 | 内置模型为 `"undersky"`，OpenRouter 模型为 `"openrouter"` |
| name | string | 便于阅读的模型名称 |
| context\_length | number | 最大上下文窗口，仅 OpenRouter 模型提供 |
| pricing | object | 每 100 万 token 的美元价格，包含 `prompt_per_1m` 和 `completion_per_1m` |
## 注意事项 [#注意事项]
* 内置模型（`owned_by: "undersky"`）可以直接使用 ID，例如 `"gpt-5-nano"`、`"claude-sonnet-4-6"`、`"gpt-5.5"`。
* OpenRouter 模型（`owned_by: "openrouter"`）必须使用完整 ID，例如 `"openrouter/anthropic/claude-sonnet-4.6"`。
* Claude 和 DeepSeek V4 模型也可以通过 Anthropic 原生的 [`POST /v1/messages`](/zh/docs/api-reference/messages) 端点调用。
* 模型列表会缓存，并每小时刷新一次。
* 此端点不需要身份认证。
# Responses (/zh/docs/api-reference/responses)
创建模型响应。Responses API 是 Chat Completions 的替代方案，采用更简单的输入格式。
## 端点 [#端点]
```
POST https://api.undersky.ai/v1/responses
```
## 参数 [#参数]
| 参数 | 类型 | 必填 | 说明 |
| ------ | --------------- | -- | ---------------------------------- |
| model | string | 是 | 使用下方支持模型表中的模型 ID |
| input | string \| array | 是 | 用于生成响应的文本字符串或输入对象数组 |
| stream | boolean | 否 | 为 `true` 时通过 SSE 返回增量内容。默认：`false` |
## 支持的模型 [#支持的模型]
| 模型 ID | 名称 |
| -------------- | ------------ |
| `gpt-5-nano` | GPT-5 Nano |
| `gpt-5.4` | GPT-5.4 |
| `gpt-5.4-mini` | GPT-5.4 Mini |
| `gpt-5.5` | GPT-5.5 |
| `gpt-6-luna` | GPT-6 Luna |
| `gpt-6-sol` | GPT-6 Sol |
| `gpt-6-astra` | GPT-6 Astra |
## 请求 [#请求]
```bash
curl -X POST https://api.undersky.ai/v1/responses \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5-nano",
"input": "What is UnderSky?"
}'
```
## 响应 [#响应]
```json
{
"id": "resp-abc123",
"object": "response",
"created_at": 1700000000,
"model": "gpt-5-nano",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "UnderSky 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
}
}
```
# 终端与 curl (/zh/docs/advanced/cli)
通过 `https://api.undersky.ai` 使用常规 HTTP 工具即可接入。在 [Dashboard](https://dashboard.undersky.ai) 创建 API Key、充值并管理账户。
## UnderSky CLI（账户工具） [#undersky-cli账户工具]
安装 `undersky-cli` / `usai`，用于登录、doctor 与控制面辅助：
```bash
curl -fsSL https://raw.githubusercontent.com/leaperone/UnderSky/main/scripts/install-cli.sh | sh
```
更新可执行 `undersky-cli upgrade`，或重新运行安装脚本。预编译包发布在 GitHub Releases 的 `cli-v*` 标签（linux/macOS，x64 与 arm64），附带 `SHA256SUMS`。若仓库为私有，安装与 upgrade 需设置具有 `contents:read` 的 `GH_TOKEN`（或 `GITHUB_TOKEN`）。
## 设置 API Key [#设置-api-key]
在 shell 中导出模型 API Key，便于重复运行示例：
```bash
export UNDERSKY_API_KEY="sk-your-api-key"
```
请勿将真实 API Key 提交到代码仓库。若 Key 泄露，请在 Dashboard → Settings → API Keys 中轮换。
## 发现模型与端点 [#发现模型与端点]
以下公开目录接口无需鉴权：
```bash
curl -sS https://api.undersky.ai/v1/models | jq '.data[] | {id, owned_by}'
curl -sS https://api.undersky.ai/openapi.json | jq '.paths | keys[:10]'
```
完整参考见 [undersky.ai/docs](https://undersky.ai/docs)。
## Chat Completion [#chat-completion]
```bash
curl -sS https://api.undersky.ai/v1/chat/completions \
-H "Authorization: Bearer $UNDERSKY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5-nano",
"messages": [{"role": "user", "content": "Hello!"}]
}' | jq '.choices[0].message.content'
```
## 流式响应 [#流式响应]
```bash
curl -N https://api.undersky.ai/v1/chat/completions \
-H "Authorization: Bearer $UNDERSKY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5-nano",
"stream": true,
"messages": [{"role": "user", "content": "数到三。"}]
}'
```
## OpenAI SDK（Python） [#openai-sdkpython]
```bash
pip install openai
```
```python
from openai import OpenAI
client = OpenAI(
api_key="sk-your-api-key",
base_url="https://api.undersky.ai/v1",
)
response = client.chat.completions.create(
model="gpt-5-nano",
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)
```
## 点数与用量 [#点数与用量]
余额与用量记录在 **Dashboard → Settings → Credit & Usage** 查看。已持有 scoped 控制令牌（`lpc_…`）的服务端集成可查询余额：
```bash
curl -sS https://api.undersky.ai/api/v1/credits/balance \
-H "Authorization: Bearer lpc-your-control-token" | jq
```
## 脚本建议 [#脚本建议]
用 `jq` 处理 JSON，用 `-w "%{http_code}"` 记录 HTTP 状态码，遇到 `429` 时退避重试。只解析响应体；不要将 API 错误与 shell 的 stderr 混为一谈。
# 错误代码 (/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 | 余额不足 | 大多数需要认证的业务请求要求有效余额至少为 $0.10。请核对价格并前往 [Dashboard](https://dashboard.undersky.ai) 充值。 |
| 403 | 禁止访问 | 读取 `error.code` 和 `error.message`；常见原因包括控制令牌缺少权限范围或账户不可用。 |
| 404 | 未找到 | 检查端点 URL 和相关资源 ID。 |
| 410 | 资源已失效 | 资源已经过期，例如超过 30 天的图像生成任务。 |
| 429 | 触发速率限制 | 降低请求速度并实现退避重试。参阅[速率限制](/zh/docs/advanced/rate-limits)。 |
| 500 | 服务器错误 | 稍后重试。如果问题持续存在，请联系支持团队。 |
## 重试策略 [#重试策略]
并非所有错误都适合重试。可以参考下表：
| 状态码 | 可重试？ | 说明 |
| --- | ---- | ---------------------------------------------------- |
| 400 | 否 | 修正请求后再重试。 |
| 401 | 否 | 修正 API 密钥或身份验证配置。 |
| 402 | 否 | 充值后再重试。 |
| 403 | 否 | 修正账户、权限范围或访问权限后再重试。 |
| 404 | 否 | 修正 URL 或资源 ID。 |
| 410 | 否 | 资源已经永久失效。 |
| 429 | 是 | 优先遵循 `Retry-After`；不存在时使用 `X-RateLimit-Reset` 或指数退避。 |
| 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)
UnderSky 使用类似 OpenAI 的分级速率限制系统。你的等级决定了每个端点每分钟允许的最大请求数（RPM）。
## 用量等级 [#用量等级]
等级由累计消费金额和账户使用时长决定。随着 API 使用量增加，你会自动获得更高等级。
| 等级 | 达标条件 | 对话 RPM | 图像 RPM | 音频 RPM | 视频 RPM |
| ----- | ------------------ | ------ | ------ | ------ | ------ |
| 0（免费） | 默认等级 | 5 | 2 | 2 | 10 |
| 1（入门） | 累计消费 $5 | 20 | 5 | 5 | 20 |
| 2（标准） | 累计消费 $50 且满 7 天 | 40 | 10 | 10 | 30 |
| 3（专业） | 累计消费 $100 且满 7 天 | 60 | 20 | 10 | 40 |
| 4（商业） | 累计消费 $250 且满 14 天 | 100 | 30 | 20 | 60 |
| 5（企业） | 累计消费 $1000 且满 30 天 | 200 | 60 | 30 | 80 |
“天数”从首次付款开始计算，不是从账户创建日期开始计算。等级会自动升级，且不会降级。
你可以在 [Dashboard](https://dashboard.undersky.ai/dashboard/settings/credit-and-usage) 中查看当前等级和限制。
`/v1/messages` 与 Chat Completions 共用 RPM 桶。`/v1/decisions` 使用 Chat RPM 配置；`/api/alpha/decisions` 映射到同一 Decisions 限流键。
## 自定义 API 密钥限制 [#自定义-api-密钥限制]
你可以为单个 API 密钥设置低于账户等级上限的自定义 RPM。这适合控制不同应用的用量。
前往 [API 密钥设置](https://dashboard.undersky.ai/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)
你无需持续轮询结果。异步任务（例如图像生成）完成后，可以让 UnderSky 主动向你的服务器推送通知。
## 工作方式 [#工作方式]
在请求中加入 `callbackUrl`。任务进入终态后，UnderSky 会向该 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-负载]
任务结束后，UnderSky 会发送一个带 JSON 请求体的 `POST` 请求：
```json title="成功负载"
{
"id": "img-abc123",
"status": "completed",
"images": [
{
"id": "img-file-1",
"url": "https://cdn.undersky.ai/images/abc123.png"
}
]
}
```
```json title="失败负载"
{
"id": "img-abc123",
"status": "failed",
"error": "Content policy violation"
}
```
### 负载字段 [#负载字段]
| 字段 | 类型 | 说明 |
| -------- | ------ | ------------------------------------------------ |
| `id` | string | 生成任务 ID。 |
| `status` | string | 可取 `completed`、`partial`、`uploading` 或 `failed`。 |
| `images` | array | 成功时出现，每项包含 `id` 和 `url`。 |
| `error` | string | 失败时出现，用于说明错误原因。 |
## 自动重试 [#自动重试]
如果你的端点返回非 2xx 状态码，或请求超过 10 秒后超时，UnderSky 会使用指数退避重试，最多重试 **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 小时后过期。
# 音频转写指南 (/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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="UnderSky, 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)
UnderSky 对模型流量和账户控制面操作使用不同的凭据。
## 基础 URL [#基础-url]
```
https://api.undersky.ai
```
## 模型 API 密钥（`sk-`） [#模型-api-密钥sk-]
调用 `/v1/*` 下需要认证的模型、媒体和数据端点时，请使用 API Key，并通过 `Authorization` 请求头传入。`GET /v1/models` 等公共发现端点不需要 Key。
```bash title="Bearer Token"
curl https://api.undersky.ai/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.undersky.ai/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_]
`/api/v1/*` 下的 scoped 控制令牌用于账户自动化、用量查询、工单与组织操作。集成服务端工具时，通过 Dashboard 授权界面获取。
控制令牌具有明确的权限范围，例如 `api_keys:read`、`credits:read`、`usage:read` 或 `envx:write`。不要长期使用模型 API 密钥代替控制令牌。
若已持有控制令牌，可示例查询余额：
```bash
curl -sS https://api.undersky.ai/api/v1/credits/balance \
-H "Authorization: Bearer lpc-your-control-token"
```
## 创建 API 密钥 [#创建-api-密钥]
在 **Dashboard → Settings → API Keys** 创建并管理密钥。点击 **Create Key** 后立即保存完整 `sk-` 值——它只会显示一次。
完整 API Key 只会显示一次，丢失后无法找回。请妥善保存新 Key。
## 错误代码 [#错误代码]
| 状态码 | 含义 |
| ----- | ---------------- |
| `401` | 凭据无效、已过期、已撤销或缺失。 |
| `403` | 控制令牌不包含所需权限范围。 |
| `402` | 余额不足，请充值后继续。 |
完整的错误响应结构请参阅 [API 参考](/zh/docs/api-reference/chat-completions)。
# 对话补全指南 (/zh/docs/guides/chat-completions)
对话补全端点完全兼容 OpenAI。将现有 OpenAI SDK 或 HTTP 客户端指向 UnderSky，即可直接使用。
## 基础请求 [#基础请求]
```bash title="POST /v1/chat/completions"
curl -X POST https://api.undersky.ai/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.undersky.ai/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 等）的实时模型目录。请使用 `openrouter/` 前缀，后接 OpenRouter 模型 ID：
```bash title="使用 OpenRouter 模型"
curl -X POST https://api.undersky.ai/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 图像生成模型，0.5 credits/张。
* `gpt-image-2` — OpenAI GPT Image 2，0.01 credits/张。除固定尺寸外，还支持 `"9:16"` 等宽高比 `size` 值。
* `gemini-3.1-flash-image-preview` — Google Gemini 3.1 Flash Image Preview，约 0.081714 credits/张。
## 第 1 步：创建任务 [#第-1-步创建任务]
```bash title="POST /v1/images/generations"
curl -X POST https://api.undersky.ai/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.undersky.ai/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://cdn.example.com/images/generated/abc123?token=example"
}
]
}
}
```
### 状态值 [#状态值]
| 状态 | 含义 |
| ------------ | --------------------- |
| `reserved` | 已预占额度，等待新版 worker 认领。 |
| `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"
}
```
费用按模型单价乘以实际生成图片数量结算。任务失败时会释放预占额度；部分成功只收取成功图片的费用。
轮询任务时返回的图像 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.undersky.ai/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.undersky.ai/v1",
api_key="sk-your-api-key"
)
response = client.audio.speech.create(
model="moss-tts-nano",
input="Welcome to UnderSky. 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.undersky.ai/v1",
apiKey: "sk-your-api-key",
});
const response = await client.audio.speech.create({
model: "moss-tts-nano",
input: "Welcome to UnderSky.",
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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/dashboard/settings/api-keys) 创建 API 密钥。
### 发送请求 [#发送请求]
通过 `url` 参数传入任意受支持的视频 URL：
```bash title="GET /v1/social-media/video/extract"
curl -G "https://api.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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)
UnderSky 通过统一的 RESTful JSON API 提供 22 个地址净化端点，涵盖地址提取、标准化、地理编码等能力。
## 端点 [#端点]
```
POST https://api.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/v1/social-media/data/{platform}/{interface}/{action}
```
所有查询参数都会转发给上游服务，响应以原始格式返回。
## 快速开始 [#快速开始]
```bash
curl -G "https://api.undersky.ai/v1/social-media/data/bilibili/web/fetch_one_video" \
--data-urlencode "bv_id=BV1M1421t7hT" \
-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.undersky.ai/openapi.json` 提供的 OpenAPI 规范。该规范包含每个可用端点和完整的参数定义。
## 平台示例 [#平台示例]
### Bilibili [#bilibili]
```bash
# Get video details
curl -G "https://api.undersky.ai/v1/social-media/data/bilibili/web/fetch_video_detail" \
--data-urlencode "aid=114902186396822" \
-H "Authorization: Bearer sk-your-api-key"
# Get video play URL (for downloading)
curl -G "https://api.undersky.ai/v1/social-media/data/bilibili/web/fetch_video_playurl" \
--data-urlencode "bv_id=BV1y7411Q7Eq" \
--data-urlencode "cid=171776208" \
-H "Authorization: Bearer sk-your-api-key"
# Get user profile
curl -G "https://api.undersky.ai/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.undersky.ai/v1/social-media/data/bilibili/web/fetch_general_search" \
--data-urlencode "keyword=programming" \
--data-urlencode "order=totalrank" \
--data-urlencode "page=1" \
--data-urlencode "page_size=42" \
-H "Authorization: Bearer sk-your-api-key"
# Get video comments
curl -G "https://api.undersky.ai/v1/social-media/data/bilibili/web/fetch_video_comments" \
--data-urlencode "bv_id=BV1M1421t7hT" \
-H "Authorization: Bearer sk-your-api-key"
# Get video danmaku (bullet comments)
curl -G "https://api.undersky.ai/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.undersky.ai/v1/social-media/data/bilibili/web/fetch_video_subtitle" \
--data-urlencode "a_id=114006081739452" \
--data-urlencode "c_id=28400484458" \
-H "Authorization: Bearer sk-your-api-key"
```
**Bilibili 主要端点：**
| 端点 | 说明 |
| ------------------------------------- | -------------------- |
| `bilibili/web/fetch_one_video` | 通过 BV 号获取视频（`bv_id`） |
| `bilibili/web/fetch_video_detail` | 通过 AV 号获取视频详情（`aid`） |
| `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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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.undersky.ai/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` 字段会包含未经处理的上游响应，便于调试。