# LEAPERone (/docs)
One API Key, access all major AI models.
```bash title="Your first API call"
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!"}]}'
```
What is LEAPERone? [#what-is-leaperone]
LEAPERone is a unified AI API gateway. Use a single API key to access chat completions, image generation, audio transcription, and more.
* **OpenAI-compatible** — drop-in replacement, no code changes needed
* **Pay-as-you-go** — transparent credit-based billing
* **CLI & Dashboard** — manage keys, check balance, view usage
Next Steps [#next-steps]
Get your API key and make your first request in 5 minutes.
Learn about authentication, models, and each API endpoint.
Full parameter reference for every endpoint.
# Quick Start (/docs/quickstart)
1\. Create an Account [#1-create-an-account]
Sign up at [leaper.one/signin](https://leaper.one/signin) using GitHub or Google.
2\. Get an API Key [#2-get-an-api-key]
Go to **Dashboard → Settings → API Keys** and create a new key. It starts with `sk-`.
Store your API key securely. It will only be shown once.
3\. Make Your First Request [#3-make-your-first-request]
```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!"}
]
}'
```
You should receive a response like:
```json title="Response"
{
"id": "chatcmpl-abc123",
"choices": [
{
"message": {
"role": "assistant",
"content": "Hello! How can I help you today?"
}
}
]
}
```
4\. Check Your Balance [#4-check-your-balance]
```bash
curl https://api.leaper.one/v1/cli/credits/balance \
-H "Authorization: Bearer sk-your-api-key"
```
Or use the CLI:
```bash
npx @leaperone/cli credit balance
```
What's Next? [#whats-next]
* [Authentication](/docs/guides/authentication) — learn about API key management
* [Chat Completions](/docs/guides/chat-completions) — streaming, tools, JSON mode
* [Image Generation](/docs/guides/image-generation) — async image creation workflow
# CLI (/docs/advanced/cli)
The LEAPERone CLI lets you manage API keys, check credits, and browse documentation directly from your terminal.
Installation [#installation]
No installation required. Run it with `npx`:
```bash
npx @leaperone/cli
```
Or install it globally:
```bash
npm install -g @leaperone/cli
```
After a global install, both `leaperone` and the short alias `lpr` are available.
Authentication [#authentication]
Log in to connect the CLI to your LEAPERone account:
```bash
npx @leaperone/cli auth login
```
This opens your browser for authentication. If you are on a headless server or remote machine, use Device Flow:
```bash
npx @leaperone/cli auth login --device
```
Check your current auth status:
```bash
npx @leaperone/cli auth status
```
Log out and remove stored credentials:
```bash
npx @leaperone/cli auth logout
```
Commands [#commands]
API Keys [#api-keys]
```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"
```
When you create a new API key, it is displayed only once. Save it immediately.
Credits [#credits]
```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
```
Documentation [#documentation]
Browse API endpoints, models, and pricing without leaving the terminal:
```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
```
Upgrade [#upgrade]
If you installed the CLI globally, upgrade it from the terminal:
```bash
# Upgrade the global install
leaperone upgrade
# Short alias also works
lpr upgrade
```
If you use `npx`, run the latest package directly:
```bash
npx @leaperone/cli@latest
```
JSON Output [#json-output]
All commands support a `--json` flag for machine-readable output, useful for scripting and CI pipelines:
```bash
npx @leaperone/cli credit balance --json
lpr credit balance --json
```
```json title="Example JSON output"
{
"paid": 10.0,
"gift": 5.0,
"total": 15.0,
"giftExpiresAt": "2026-04-01T00:00:00.000Z"
}
```
Agent Skills [#agent-skills]
LEAPERone CLI bundles [Agent Skills](https://skills.sh/) — reusable instruction sets that help AI coding assistants (Claude Code, Cursor, Codex, Windsurf, etc.) understand how to use LEAPERone.
Quick Install [#quick-install]
```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/
```
What It Does [#what-it-does]
Once installed, your AI agent knows how to:
* Authenticate and manage API keys
* Check credit balance and usage
* Make API requests using the OpenAI-compatible endpoints
* Browse documentation and check endpoint status
Supported Agents [#supported-agents]
Skills work with 40+ AI coding assistants including Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI, and more.
Environment Variables [#environment-variables]
You can also authenticate by setting an API key as an environment variable instead of using `auth login`:
```bash
export LEAPERONE_API_KEY=sk-your-api-key
npx @leaperone/cli credit balance
```
# Error Codes (/docs/advanced/error-codes)
All API errors return a JSON body with an `error` object. Use the HTTP status code and the `error.code` field to determine what went wrong.
Error Response Format [#error-response-format]
```json title="Example error response"
{
"error": {
"message": "Rate limit exceeded. Please slow down.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}
```
Error Code Reference [#error-code-reference]
| Code | Meaning | How to Fix |
| ---- | -------------------- | ---------------------------------------------------------------------------------------- |
| 400 | Bad Request | Check request body format and required fields. |
| 401 | Unauthorized | Check that your API key is valid and included in the `Authorization` header. |
| 402 | Insufficient Credits | Top up credits in the [Dashboard](https://leaper.one/dashboard). |
| 404 | Not Found | Check the endpoint URL and any resource IDs. |
| 410 | Gone | Resource has expired (e.g., an image generation task older than 30 days). |
| 429 | Rate Limited | Slow down requests and implement backoff. See [Rate Limits](/docs/advanced/rate-limits). |
| 500 | Server Error | Retry after a moment. Contact support if the issue persists. |
Retry Strategy [#retry-strategy]
Not all errors are retryable. Here is a quick guide:
| Code | Retryable? | Notes |
| ---- | ---------- | ------------------------------------------- |
| 400 | No | Fix the request before retrying. |
| 401 | No | Fix your API key or authentication. |
| 402 | No | Add credits, then retry. |
| 404 | No | Fix the URL or resource ID. |
| 410 | No | The resource is permanently gone. |
| 429 | Yes | Wait for the `Retry-After` header duration. |
| 500 | Yes | Use exponential backoff. |
Exponential Backoff [#exponential-backoff]
For retryable errors, use exponential backoff to avoid overwhelming the API:
```javascript title="Retry with exponential backoff"
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");
}
```
Always add random jitter to your backoff delay. This prevents many clients from retrying at exactly the same moment.
# Rate Limits (/docs/advanced/rate-limits)
LEAPERone uses a tier-based rate limiting system, similar to OpenAI. Your tier determines the maximum requests per minute (RPM) for each endpoint.
Usage Tiers [#usage-tiers]
Your tier is determined by cumulative spend and account age. As you use the API more, you automatically qualify for higher tiers.
| Tier | Qualification | Chat RPM | Image RPM | Audio RPM | Video RPM |
| -------------- | --------------------- | -------- | --------- | --------- | --------- |
| 0 (free) | Default | 5 | 2 | 2 | 3 |
| 1 (starter) | $5 spent | 20 | 5 | 5 | 10 |
| 2 (standard) | $50 spent + 7 days | 40 | 10 | 10 | 20 |
| 3 (pro) | $100 spent + 7 days | 60 | 20 | 10 | 30 |
| 4 (business) | $250 spent + 14 days | 100 | 30 | 20 | 50 |
| 5 (enterprise) | $1000 spent + 30 days | 200 | 60 | 30 | 100 |
"Days" refers to days since your first payment, not account creation date. Tier upgrades are automatic and never downgrade.
You can view your current tier and limits in your [dashboard](/dashboard/settings/credit-and-usage).
Custom API Key Limits [#custom-api-key-limits]
You can set a custom RPM limit on individual API keys that is lower than your tier's maximum. This is useful for controlling usage across different applications.
Set this in [API Key settings](/dashboard/settings/api-keys) by clicking the RPM badge on any key.
Rate Limit Headers [#rate-limit-headers]
When a request is rate-limited, the `429` response includes these headers:
| Header | Description |
| ----------------------- | -------------------------------------------------------------- |
| `X-RateLimit-Limit` | Maximum number of requests allowed in the current window. |
| `X-RateLimit-Remaining` | Number of requests remaining in the current window. |
| `X-RateLimit-Reset` | Unix timestamp (seconds) when the current window resets. |
| `Retry-After` | Seconds until you can retry (only present on `429` responses). |
Handling 429 Responses [#handling-429-responses]
When you exceed the rate limit, the API returns a `429` status:
```json title="429 Response"
{
"error": {
"message": "Rate limit exceeded. Please slow down.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}
```
Use the `Retry-After` header to determine how long to wait before sending the next request.
Exponential Backoff [#exponential-backoff]
The recommended strategy for handling rate limits is exponential backoff with jitter:
```javascript title="Rate-limit-aware 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");
}
```
Best Practices [#best-practices]
* **Monitor the headers.** Check `X-RateLimit-Remaining` proactively and slow down before hitting zero.
* **Queue requests.** If you are making many calls in a batch, use a queue to space them out evenly across the window.
* **Use jitter.** Always add random jitter to backoff delays to prevent synchronized retries from multiple clients.
* **Cache responses.** If you call the same endpoint with the same parameters, cache the result to avoid unnecessary requests.
# Webhooks (/docs/advanced/webhooks)
Instead of polling for results, you can have LEAPERone push a notification to your server when an asynchronous task (such as image generation) finishes.
How It Works [#how-it-works]
Include a `callbackUrl` in your request. When the task completes (or fails), LEAPERone sends a JSON `POST` request to that URL.
```json title="Request with callbackUrl"
{
"model": "gpt-4o-image",
"prompt": "A neon-lit cyberpunk cityscape",
"callbackUrl": "https://your-server.com/webhook/image"
}
```
The `callbackUrl` must use HTTPS and must not point to private or internal network addresses.
Webhook Payload [#webhook-payload]
When the task finishes, LEAPERone sends a `POST` request with a JSON body:
```json title="Completed payload"
{
"id": "img-abc123",
"status": "completed",
"images": [
{
"id": "img-file-1",
"url": "https://cdn.leaper.one/images/abc123.png"
}
]
}
```
```json title="Failed payload"
{
"id": "img-abc123",
"status": "failed",
"error": "Content policy violation"
}
```
Payload Fields [#payload-fields]
| Field | Type | Description |
| -------- | ------ | -------------------------------------------------- |
| `id` | string | The generation task ID. |
| `status` | string | `completed`, `uploading`, or `failed`. |
| `images` | array | Present on success. Each entry has `id` and `url`. |
| `error` | string | Present on failure. Describes what went wrong. |
Automatic Retries [#automatic-retries]
If your endpoint returns a non-2xx status code or the request times out (10 seconds), LEAPERone retries up to **5 times** with exponential backoff (starting at 2 seconds, capped at 30 seconds).
If all retries are exhausted, the callback is marked as failed. You can still retrieve the result by polling the `GET /v1/images/generations/:id` endpoint.
Verifying Webhook Source [#verifying-webhook-source]
There is currently no signature header for webhook verification. To protect your endpoint, consider these strategies:
* Use a secret path that is hard to guess (e.g., `https://your-server.com/webhook/a8f3b2c1`).
* Verify the `id` in the payload by calling `GET /v1/images/generations/:id` to confirm it exists and matches.
* Restrict inbound traffic to known IP ranges if your infrastructure supports it.
Best Practices [#best-practices]
* **Respond quickly.** Return a `200` status as soon as you receive the payload. Process the data asynchronously on your side to avoid timeouts.
* **Handle duplicates.** In rare cases a retry may arrive after a previous attempt already succeeded. Use the `id` field to deduplicate.
* **Download images promptly.** Image URLs are temporary and expire after 1 hour.
# Text to Speech API (/docs/api-reference/audio-speech)
Generate speech audio from text. Supports preset voices and custom voice cloning.
Endpoint [#endpoint]
```
POST https://api.leaper.one/v1/audio/speech
```
Models [#models]
| Model | Pricing | Description |
| --------------- | ------------------------ | ----------------------------------- |
| `moss-tts-nano` | 0.005 credits / 1K chars | Multilingual TTS with voice cloning |
Parameters [#parameters]
JSON Body (preset voices) [#json-body-preset-voices]
| Parameter | Type | Required | Description |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------- |
| model | string | No | Model to use. Default: `"moss-tts-nano"` |
| input | string | Yes | Text to synthesize (max 4096 characters) |
| voice | string | No | Voice preset name. Default: `"nova"` (Chinese). See [Available Voices](#available-voices) |
| response\_format | string | No | Output format: `"wav"` or `"pcm"`. Default: `"wav"` |
Multipart Form (voice cloning) [#multipart-form-voice-cloning]
| Parameter | Type | Required | Description |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| model | string | No | Model to use. Default: `"moss-tts-nano"` |
| input | string | Yes | Text to synthesize (max 4096 characters) |
| voice | string | No | Voice preset name (used as base for cloning) |
| prompt\_audio | file | No | Reference audio file for voice cloning (max 1MB). Supports mp3, wav, flac, m4a, ogg |
| response\_format | string | No | Output format: `"wav"` or `"pcm"`. Default: `"wav"` |
Request [#request]
Basic usage with preset voice [#basic-usage-with-preset-voice]
```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
```
Voice cloning with custom audio [#voice-cloning-with-custom-audio]
```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
```
Using the OpenAI SDK [#using-the-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")
```
Voice cloning requires `multipart/form-data` to upload the reference audio file. The OpenAI SDK does not support this — use `curl` or a custom HTTP request for voice cloning.
Response [#response]
Returns audio bytes directly. The `Content-Type` header indicates the format:
| Format | Content-Type |
| ------ | -------------------------- |
| `wav` | `audio/wav` |
| `pcm` | `application/octet-stream` |
PCM format is raw 48kHz, 16-bit, stereo (2 channels).
Available Voices [#available-voices]
OpenAI-compatible aliases [#openai-compatible-aliases]
| Voice | Language | Style |
| --------- | -------- | ------------------ |
| `alloy` | English | Welcome / neutral |
| `echo` | English | News anchor |
| `fable` | English | Gentle reminder |
| `onyx` | English | Academic / lecture |
| `nova` | Chinese | Welcome / neutral |
| `shimmer` | Chinese | Soft / gentle |
Chinese voices [#chinese-voices]
| Voice | Style |
| ------------ | ----------------- |
| `zh-welcome` | Neutral welcome |
| `zh-gentle` | Soft late-night |
| `zh-taiwan` | Taiwanese accent |
| `zh-beijing` | Beijing dialect |
| `zh-culture` | Formal / cultural |
| `zh-yangmi` | Celebrity voice |
English voices [#english-voices]
| Voice | Style |
| ------------ | ----------------- |
| `en-welcome` | Neutral welcome |
| `en-lesson` | Academic lecture |
| `en-news` | News anchor |
| `en-gentle` | Gentle reminder |
| `en-taylor` | Celebrity voice |
| `en-quiet` | Calm / reflective |
Other languages [#other-languages]
| Voice | Language |
| --------- | -------- |
| `ja-news` | Japanese |
| `ko-news` | Korean |
| `es-news` | Spanish |
| `fr-news` | French |
| `de-news` | German |
| `it-news` | Italian |
| `ru-news` | Russian |
You can also pass `demo-1` through `demo-29` directly for the full list of MOSS presets.
Notes [#notes]
* Billing is based on character count at 0.005 credits per 1,000 characters.
* Voice cloning is significantly slower than preset voices (CPU inference). Expect 20-60 seconds for short text.
* The `prompt_audio` file should be a clear speech sample, ideally 5-15 seconds long.
* Maximum input length is 4,096 characters.
# Audio Transcriptions API (/docs/api-reference/audio-transcriptions)
Transcribe audio into text. Supports file upload or URL.
Endpoint [#endpoint]
```
POST https://api.leaper.one/v1/audio/transcriptions
```
Models [#models]
| Model | Pricing | Description |
| ----------- | ----------------- | -------------------------------------- |
| `rapid` | 0.006 credits/min | Fast transcription, supports file\_uri |
| `whisper-1` | 0.006 credits/min | High accuracy with prompt support |
Parameters [#parameters]
| Parameter | Type | Required | Description |
| ---------------- | ------ | --------------------------- | ------------------------------------------------------------------------------------------- |
| file | file | Either `file` or `file_uri` | Audio file to transcribe (multipart upload) |
| file\_uri | string | Either `file` or `file_uri` | URL of the audio file to transcribe |
| model | string | No | Model to use: `"rapid"` or `"whisper-1"`. Default: `"rapid"` |
| response\_format | string | No | Output format: `"text"`, `"json"`, `"verbose_json"`, `"srt"`, or `"vtt"`. Default: `"json"` |
| language | string | No | ISO 639-1 language code (e.g. `"en"`, `"zh"`). Improves accuracy if specified |
| prompt | string | No | Hint text to improve transcription quality |
| temperature | number | No | Sampling temperature between 0 and 1 (`whisper-1` only) |
Request [#request]
Upload a file [#upload-a-file]
```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
```
Pass a URL (recommended for large files) [#pass-a-url-recommended-for-large-files]
```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
```
Using `file_uri` avoids uploading large files through your network. The audio is fetched server-side. Supported with both `rapid` and `whisper-1` models.
Using whisper-1 with prompt [#using-whisper-1-with-prompt]
```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"
```
Requesting subtitle output [#requesting-subtitle-output]
```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
```
Response [#response]
```json
{
"text": "Hello, this is a sample transcription of the audio file."
}
```
When using `verbose_json`, the response includes timestamps and segments:
```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." }
]
}
```
When using `srt`, the response is plain text subtitle output:
```text
1
00:00:00,000 --> 00:00:02,400
Hello, this is a sample transcription.
```
When using `vtt`, the response is returned as WebVTT:
```text
WEBVTT
00:00:00.000 --> 00:00:02.400
Hello, this is a sample transcription.
```
Supported Audio Formats [#supported-audio-formats]
`mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm`, `opus`
File uploads are limited to 25 MB. When using `file_uri`, there is no size limit.
Notes [#notes]
* Billing is based on audio duration, charged at the per-model rate listed above.
* If no `model` is specified, `rapid` is used by default.
* Streaming (`stream=true`) is not supported at this time.
# Chat Completions API (/docs/api-reference/chat-completions)
Create a chat completion. This endpoint is OpenAI-compatible and supports streaming, tool calling, and JSON mode.
Endpoint [#endpoint]
```
POST https://api.leaper.one/v1/chat/completions
```
Parameters [#parameters]
| Parameter | Type | Required | Description |
| ---------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| model | string | Yes | Model ID. Built-in: `"auto"`, `"gpt-5-nano"`, `"gpt-5.4"`. Or `"openrouter/{provider}/{model}"` for 350+ models via OpenRouter |
| messages | array | Yes | Array of message objects with `"role"` (`system`/`user`/`assistant`) and `"content"` |
| stream | boolean | No | If `true`, partial message deltas sent as SSE. Default: `false` |
| temperature | number | No | Sampling temperature 0-2. Default: `0.7` |
| top\_p | number | No | Nucleus sampling. Default: `1` |
| max\_tokens | integer | No | Maximum tokens to generate |
| stop | string \| array | No | Up to 4 stop sequences |
| tools | array | No | List of tool definitions the model may call |
| tool\_choice | string \| object | No | `"none"`, `"auto"`, or specify a function |
| response\_format | object | No | `{ "type": "json_object" }` for JSON mode |
Request [#request]
```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
}'
```
Response [#response]
```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
}
}
```
Notes [#notes]
* `"auto"` routes to `gpt-5-nano` by default.
* When `stream` is `true`, partial deltas are sent as **Server-Sent Events** (SSE). The stream terminates with a `[DONE]` message.
* Billing is calculated per token based on the resolved model.
* **OpenRouter models**: Use `"openrouter/{provider}/{model}"` (e.g. `"openrouter/anthropic/claude-sonnet-4.6"`) to access 350+ models. Pricing is pass-through from OpenRouter. See the [Chat Completions Guide](/docs/guides/chat-completions#openrouter-models) for details.
# Image Generation (Create) (/docs/api-reference/images-create)
Submit an asynchronous image generation request. The response returns a task ID that you can poll for status using the [Image Generation (Status)](/docs/api-reference/images-status) endpoint.
Endpoint [#endpoint]
```
POST https://api.leaper.one/v1/images/generations
```
Parameters [#parameters]
| Parameter | Type | Required | Description |
| --------------- | ------------------- | -------- | -------------------------------------------------------------------------------------- |
| prompt | string | Yes | Text description of the image to generate |
| model | string | Yes | Model ID. Supported: `"gpt-4o-image"`, `"gpt-image-2"`, `"gemini-3-pro-image-preview"` |
| referenceImages | string \| string\[] | No | URL(s) of reference images for style or content guidance |
| number | number | No | Number of images to generate, 1-4. Default: `1` |
| size | string | No | Image dimensions (e.g. `"1024x1024"`) or aspect ratio (e.g. `"9:16"`, model-dependent) |
| callbackUrl | string | No | Webhook URL to receive a POST when generation completes |
Supported Models [#supported-models]
| Model | Description |
| ---------------------------- | --------------------------------------------------------------- |
| `gpt-4o-image` | OpenAI GPT-4o image generation. Good general-purpose quality. |
| `gpt-image-2` | OpenAI GPT Image 2. Supports aspect-ratio `size` like `"9:16"`. |
| `gemini-3-pro-image-preview` | Google Gemini 3 Pro Image. |
Request [#request]
```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"
}'
```
Response [#response]
```json
{
"code": 0,
"msg": "success",
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
```
Notes [#notes]
* Each image costs **0.5 credits**. Credits are deducted at creation time.
* If your balance is insufficient, the API returns **402 Payment Required**.
* Use the returned `id` to poll for results via the [Status endpoint](/docs/api-reference/images-status).
# Image Generation (Status) (/docs/api-reference/images-status)
Check the status of an image generation task and retrieve the generated images once complete.
Endpoint [#endpoint]
```
GET https://api.leaper.one/v1/images/generations/:id
```
Parameters [#parameters]
| Parameter | Type | Required | Description |
| --------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| id | string (path) | Yes | UUID of the image generation task, returned by the [Create endpoint](/docs/api-reference/images-create) |
Request [#request]
```bash
curl https://api.leaper.one/v1/images/generations/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Authorization: Bearer sk-your-api-key"
```
Response [#response]
```json
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"images": [
{
"url": "https://storage.leaper.one/images/a1b2c3d4.png"
}
]
}
```
Status Values [#status-values]
| Status | Description |
| ------------ | ------------------------------------------------------ |
| `pending` | Task is queued and waiting to start |
| `processing` | Image generation is in progress |
| `uploading` | Generated images are being uploaded to storage |
| `partial` | Some images are ready; others are still processing |
| `completed` | All images are ready for download |
| `failed` | Generation failed; check error details in the response |
Notes [#notes]
* Image URLs are **temporary** and expire after **1 hour**. Download or cache them promptly.
* Tasks older than **30 days** are deleted. Requesting a deleted task returns **410 Gone**.
# List Models (/docs/api-reference/models)
List all available models. This endpoint is public and does not require authentication.
Endpoint [#endpoint]
```
GET https://api.leaper.one/v1/models
```
Response [#response]
Returns a list of model objects, including built-in models and 350+ models available via OpenRouter.
```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
}
}
]
}
```
Model Fields [#model-fields]
| Field | Type | Description |
| --------------- | ------ | ----------------------------------------------------------------------- |
| id | string | Model ID to use in the `model` parameter |
| object | string | Always `"model"` |
| created | number | Unix timestamp |
| owned\_by | string | `"leaperone"` for built-in models, `"openrouter"` for OpenRouter models |
| name | string | Human-readable name |
| context\_length | number | Maximum context window (OpenRouter models only) |
| pricing | object | `prompt_per_1m` and `completion_per_1m` in USD per 1M tokens |
Notes [#notes]
* Built-in models (`owned_by: "leaperone"`) can be used directly by ID (e.g. `"gpt-5-nano"`).
* OpenRouter models (`owned_by: "openrouter"`) should be used with their full ID (e.g. `"openrouter/anthropic/claude-sonnet-4.6"`).
* The model list is cached and refreshes every hour. Pricing reflects OpenRouter's current rates.
* No authentication is required for this endpoint.
# Responses (/docs/api-reference/responses)
Create a model response. This is the OpenAI Responses API, an alternative to Chat Completions that accepts a simpler input format.
Endpoint [#endpoint]
```
POST https://api.leaper.one/v1/responses
```
Parameters [#parameters]
| Parameter | Type | Required | Description |
| --------- | --------------- | -------- | ------------------------------------------------------------------ |
| model | string | Yes | Model ID. Supported: `"gpt-5-nano"`, `"gpt-5.4"` |
| input | string \| array | Yes | A text string or array of input objects to generate a response for |
| stream | boolean | No | If `true`, partial deltas sent as SSE. Default: `false` |
Request [#request]
```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?"
}'
```
Response [#response]
```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
}
}
```
# Audio Transcription Guide (/docs/guides/audio-transcription)
The Audio Transcription endpoint converts speech to text. You can upload an audio file or pass a URL.
Models [#models]
| Model | Pricing | Best for |
| ----------------- | ----------------- | ----------------------------------- |
| `rapid` (default) | 0.006 credits/min | Fast, general-purpose transcription |
| `whisper-1` | 0.006 credits/min | High accuracy with prompt support |
Quick Start [#quick-start]
```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="Response"
{
"text": "Welcome to today's meeting. Let's start with the agenda..."
}
```
Using file_uri [#using-file_uri]
Instead of uploading a file, you can pass a URL. This is recommended for large files or when your audio is already hosted online.
```bash title="Transcribe from 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` supports any publicly accessible audio URL. Formats include mp3, opus, m4a, wav, and more. No file size limit when using URL.
Choosing a Model [#choosing-a-model]
rapid (default) [#rapid-default]
Best for quick transcription without extra configuration. No `model` parameter needed. Supports `language` and `prompt` parameters.
```bash title="Using 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's Whisper model. Supports `prompt` to improve recognition of specific terms and `verbose_json` for word-level timestamps.
```bash title="Using whisper-1 with prompt"
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"
```
Supported Formats [#supported-formats]
| Format | Extension |
| ------ | ---------------- |
| MP3 | `.mp3` |
| MP4 | `.mp4` |
| MPEG | `.mpeg`, `.mpga` |
| M4A | `.m4a` |
| WAV | `.wav` |
| WebM | `.webm` |
| Opus | `.opus` |
Response Formats [#response-formats]
Set `response_format` to control the output:
| Value | Description |
| -------------- | --------------------------------------------- |
| `json` | JSON object with a `text` field (default). |
| `text` | Plain text transcription. |
| `verbose_json` | JSON with timestamps, segments, and metadata. |
| `srt` | SubRip subtitle format. |
| `vtt` | WebVTT subtitle format. |
Billing is based on audio duration. See the [API Reference](/docs/api-reference/audio-transcriptions) for per-model pricing.
# Authentication (/docs/guides/authentication)
All API requests must include your API key. LEAPERone supports two authentication methods.
Base URL [#base-url]
```
https://api.leaper.one
```
Bearer Token (recommended) [#bearer-token-recommended]
Pass your key in the `Authorization` header:
```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 Header [#x-api-key-header]
Alternatively, use the `X-API-Key` header:
```bash title="X-API-Key Header"
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"}]}'
```
Creating API Keys [#creating-api-keys]
You can create and manage keys in two ways:
**Dashboard** — go to **Settings > API Keys** and click **Create Key**.
**CLI** — list your existing keys from the terminal:
```bash
npx @leaperone/cli apikey list
```
API keys are shown only once at creation time. Store them securely.
Error Codes [#error-codes]
| Code | Meaning |
| ----- | ------------------------------------------------------ |
| `401` | Invalid or missing API key. |
| `402` | Insufficient credits. Top up your balance to continue. |
For full error response schemas, see the [API Reference](/docs/api-reference/chat-completions).
# Chat Completions Guide (/docs/guides/chat-completions)
The Chat Completions endpoint is fully OpenAI-compatible. Point any existing OpenAI SDK or HTTP client at LEAPERone and it works out of the box.
Basic Request [#basic-request]
```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="Response"
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Quantum computing uses qubits..."
},
"finish_reason": "stop"
}
]
}
```
Setting `model` to `"auto"` routes your request to the best available model automatically. You can also specify a model explicitly (e.g., `"gpt-5-nano"`).
Streaming [#streaming]
Set `stream: true` to receive results as Server-Sent Events (SSE). Tokens are delivered incrementally as they are generated.
```bash title="Streaming Request"
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."}
]
}'
```
Each SSE event contains a `data:` line with a JSON chunk:
```
data: {"id":"chatcmpl-abc123","choices":[{"delta":{"content":"Endpoints"},"index":0}]}
data: {"id":"chatcmpl-abc123","choices":[{"delta":{"content":" await"},"index":0}]}
data: [DONE]
```
Tools / Function Calling [#tools--function-calling]
You can pass a `tools` array to let the model call functions you define. The model will return a `tool_calls` response when it decides a function should be invoked. This follows the same format as the OpenAI function calling API.
```json title="Tools Parameter (abbreviated)"
{
"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"]
}
}
}
]
}
```
For the complete parameter list and response schema, see the [API Reference](/docs/api-reference/chat-completions).
OpenRouter Models [#openrouter-models]
Beyond the built-in models, you can access **350+ models** from all major providers (Anthropic, Google, Meta, Mistral, etc.) via [OpenRouter](https://openrouter.ai). Use the `openrouter/` prefix followed by the OpenRouter model ID:
```bash title="Using an OpenRouter model"
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 models use pass-through pricing — you are billed at the same rate as OpenRouter's upstream provider. See [OpenRouter Models](https://openrouter.ai/models) for the full model list and pricing.
Examples [#examples]
| Model | `model` value |
| ----------------- | ---------------------------------------------- |
| 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` |
# Image Generation Guide (/docs/guides/image-generation)
Image generation uses an asynchronous two-step workflow: **create a task**, then **poll for the result**.
Supported Models [#supported-models]
* `gpt-4o-image` — OpenAI GPT-4o image generation.
* `gpt-image-2` — OpenAI GPT Image 2. Supports aspect-ratio `size` values like `"9:16"` in addition to fixed dimensions.
* `gemini-3-pro-image-preview` — Google Gemini 3 Pro Image.
Step 1 — Create a Task [#step-1--create-a-task]
```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="Response"
{
"id": "img-abc123",
"status": "pending"
}
```
Step 2 — Poll for Status [#step-2--poll-for-status]
Use the returned `id` to check progress:
```bash title="GET /v1/images/generations/:id"
curl https://api.leaper.one/v1/images/generations/img-abc123 \
-H "Authorization: Bearer sk-your-api-key"
```
```json title="Completed Response"
{
"id": "img-abc123",
"status": "completed",
"data": [
{
"url": "https://cdn.leaper.one/images/abc123.png"
}
]
}
```
Status Values [#status-values]
| Status | Meaning |
| ------------ | --------------------------------------------- |
| `pending` | Task queued, not yet started. |
| `processing` | Model is generating the image. |
| `uploading` | Image is being uploaded to storage. |
| `partial` | Some images ready (for multi-image requests). |
| `completed` | All images ready. |
| `failed` | Generation failed. |
Webhook Callback [#webhook-callback]
Instead of polling, you can provide a `callbackUrl` to receive a POST notification when the task finishes:
```json title="Request with Callback"
{
"model": "gpt-4o-image",
"prompt": "A neon-lit cyberpunk cityscape",
"callbackUrl": "https://your-server.com/webhook/image"
}
```
Each generated image costs **0.5 credits**.
Image URLs are **temporary** and expire after **1 hour**. Download or cache them promptly.
For the full parameter list and response schema, see the [API Reference](/docs/api-reference/images-create).
# Text to Speech Guide (/docs/guides/text-to-speech)
The Text to Speech endpoint generates spoken audio from text input. Choose from preset voices across multiple languages, or clone any voice from a short audio sample.
Models [#models]
| Model | Pricing | Best for |
| --------------- | ------------------------ | -------------------------------------- |
| `moss-tts-nano` | 0.005 credits / 1K chars | Multilingual speech with voice cloning |
Quick Start [#quick-start]
```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
```
The response is a WAV audio file you can play directly.
Using the OpenAI SDK [#using-the-openai-sdk]
The endpoint is OpenAI-compatible, so you can use the official 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);
```
Choosing a Voice [#choosing-a-voice]
OpenAI-compatible voices [#openai-compatible-voices]
Use familiar voice names if you're migrating from OpenAI:
| Voice | Maps to |
| --------- | -------------------- |
| `alloy` | English, neutral |
| `echo` | English, news anchor |
| `fable` | English, gentle |
| `onyx` | English, academic |
| `nova` | Chinese, neutral |
| `shimmer` | Chinese, soft |
Language-specific voices [#language-specific-voices]
Voices are named by language and style, e.g. `zh-gentle`, `en-news`, `ja-news`.
```bash title="Chinese gentle voice"
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="Japanese news voice"
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
```
See the [API Reference](/docs/api-reference/audio-speech) for the full list of available voices.
Voice Cloning [#voice-cloning]
Upload a short audio sample to clone any voice. This requires `multipart/form-data` instead of JSON.
```bash title="Clone a voice"
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
```
**Tips for good voice cloning:**
* Use a clear speech recording, 5-15 seconds long
* Minimize background noise
* Audio file must be under 1MB (mp3, wav, flac, m4a, ogg)
* Voice cloning runs on CPU and takes 20-60 seconds
Voice cloning is not supported via the OpenAI SDK because it requires file upload alongside text parameters. Use `curl` or a direct HTTP request.
Output Formats [#output-formats]
| Format | Use case |
| --------------- | -------------------------------------------------------- |
| `wav` (default) | Ready-to-play audio file |
| `pcm` | Raw audio for further processing (48kHz, 16-bit, stereo) |
```bash title="Get PCM output"
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
```
Billing is based on character count. See the [API Reference](/docs/api-reference/audio-speech) for pricing details.
# Video Extract Guide (/docs/guides/video-extract)
Extract video download info from social media share links. Paste a URL (or raw share text), get multi-quality video streams, audio tracks, cover images, and metadata — all in one request.
Quick Start [#quick-start]
Get your API Key [#get-your-api-key]
Go to the [Dashboard](https://leaper.one/dashboard/settings/api-keys) and create an API key.
Make a request [#make-a-request]
Pass any supported video URL as the `url` parameter:
```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"
```
Get the result [#get-the-result]
The response includes normalized metadata and multi-quality download options:
```json title="Response"
{
"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" }
]
}
}
```
Supported Platforms [#supported-platforms]
| Platform | URL Formats | Video | Audio | Notes |
| --------------- | ------------------------------------- | ------------------------------- | -------------------- | ------------------------- |
| **Douyin** | `v.douyin.com/*` | Multi-quality (1080p/720p/540p) | Background music MP3 | Shares parser with TikTok |
| **Kuaishou** | `v.kuaishou.com/*`, `*.gifshow.com/*` | Multi-quality | Yes | — |
| **Bilibili** | `bilibili.com/video/BV*`, `b23.tv/*` | DASH multi-stream | DASH separate audio | Requires ffmpeg to merge |
| **Xiaohongshu** | `xiaohongshu.com/*`, `xhslink.com/*` | H.264/H.265 | — | Multiple codecs |
| **Weibo** | `weibo.com/*`, `weibo.cn/*` | 720p/HD/LD | — | — |
| **Xigua** | `ixigua.com/*` | Yes | — | — |
| **Pipixia** | `pipix.com/*`, `pipixia.com/*` | high/low | — | — |
| Platform | URL Formats | Video | Audio | Notes |
| ------------- | ------------------------------------------------------------- | ------------------------------- | -------------------- | ------------------------- |
| **TikTok** | `tiktok.com/@user/video/*` | Multi-quality (1080p/720p/540p) | Background music MP3 | Shares parser with Douyin |
| **YouTube** | `youtube.com/watch?v=*`, `youtu.be/*`, `youtube.com/shorts/*` | 360p–4K, mp4/webm | m4a/weba | Up to 20+ formats |
| **Instagram** | `instagram.com/reel/*` | Multi-resolution | — | — |
| **Twitter/X** | `x.com/*/status/*`, `twitter.com/*/status/*` | Multi-bitrate | — | Sorted by bitrate |
**Audio note**: "—" means audio is embedded in the video file (`audios` returns empty array). Bilibili and YouTube use DASH format with separate audio/video — use ffmpeg to merge. Douyin/TikTok `audios` are standalone background music.
Try It — Test URLs [#try-it--test-urls]
Copy any URL below and use it directly with the API:
```bash title="Douyin"
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"
```
Returns 4 quality options (1080p → 540p) + 1 background music 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"
```
Returns 4 quality options + background music. Same hybrid parser as Douyin.
```bash title="Kuaishou"
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"
```
Returns multi-quality video streams.
```bash title="Bilibili"
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"
```
Returns DASH format: 6 video streams (different resolutions) + 3 audio streams (different codecs). Merge with:
```bash title="ffmpeg merge"
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"
```
Returns 20+ video formats (360p–4K, mp4/webm) + 4 audio tracks (m4a/weba).
Paste Share Text Directly [#paste-share-text-directly]
No need to manually extract URLs. Paste the raw share text from any app:
```bash title="Douyin share text"
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="Xiaohongshu share text"
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"
```
The API automatically extracts the `https://` link from the text and parses it.
Use Cases [#use-cases]
Get watermark-free video in multiple resolutions. Let users choose the quality they need.
Extract the audio track, then use Audio Transcription to convert speech to text.
Get video title, author info, and description for content repurposing or translation.
Pick the best quality from the videos array and repost to another platform.
Pricing [#pricing]
Each successful request costs **$0.01 credit**. Failed requests are not billed.
Video and audio URLs are **time-limited** (typically hours to a few days). Download promptly after retrieval.
For full parameter specs and response schema, see the [API Reference](/docs/api-reference/social-media/video-extract).
# Address Analysis (/docs/api-reference/address/analysis)
`classify-poi` — Address Type Classification [#classify-poi--address-type-classification]
Classify an address into a 3-level POI category hierarchy.
```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"
}
```
The classification uses a `#`-separated 3-level hierarchy.
***
`predict-poi` — POI Prediction [#predict-poi--poi-prediction]
Predict detailed POI information associated with an address and assess confidence level.
```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号万达广场"}'
```
# Basic Services (/docs/api-reference/address/basic)
`extract` — Address Extraction [#extract--address-extraction]
Extract address fragments from natural text, removing non-address content.
```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` — Name Extraction [#extract-name--name-extraction]
Identify and extract person names from logistics text.
```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` — Phone Number Extraction [#extract-phone--phone-number-extraction]
Identify and extract phone numbers from text.
```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` — Administrative Division Code [#division-code--administrative-division-code]
Identify the administrative division code (province, city, district, street) for a given address.
```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` — Zip Code Lookup [#zipcode--zip-code-lookup]
Return the postal code for a given address.
```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"
}
```
# Address Cleansing (/docs/api-reference/address/cleansing)
`structure` — Address Structuring [#structure--address-structuring]
Parse an address into 23 structured fields including province, city, district, street, road, house number, etc.
```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"
}
```
The structured result uses tab-separated `key=value` format.
***
`correct` — Address Correction [#correct--address-correction]
Fix spelling errors in addresses (e.g., incorrect administrative region names).
```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` — Address Completion [#complete--address-completion]
Fill in missing administrative regions, road names, and house numbers.
```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` — Address Standardization [#standardize--address-standardization]
Correct and complete address information, producing a normalized standard address.
```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` — Address Anomaly Detection [#assessment--address-anomaly-detection]
Detect issues in an address (non-address text, missing segments, incorrect digit count, etc.).
```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": "随便写的不是地址"}'
```
# Geocoding (/docs/api-reference/address/geo)
`geocode` — POI-level Geocoding [#geocode--poi-level-geocoding]
Return the latitude and longitude coordinates for a given address.
```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` — Building-level Geocoding [#hp-geocode--building-level-geocoding]
Return high-precision latitude and longitude coordinates at the building level.
```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` — Coordinate System Conversion [#transfer-coord--coordinate-system-conversion]
Convert between GCJ02, WGS84, CGCS2000, and BD09 coordinate systems.
The `text` parameter for this endpoint takes coordinates instead of an address, and requires an additional `srcCoord` parameter.
Additional Parameters [#additional-parameters]
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------------------------- |
| text | string | Yes | Coordinates in `"longitude,latitude"` format |
| srcCoord | string | Yes | Source coordinate system: `gcj02`, `wgs84`, `cgcs2000`, `bd09` |
| dstCoord | string | No | Target coordinate system (returns all systems if omitted) |
```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"
}
}
```
# Address Purification (/docs/api-reference/address)
LEAPERone provides a suite of 22 address purification endpoints through a unified RESTful JSON API, covering address extraction, standardization, geocoding, and more.
Endpoint [#endpoint]
```
POST https://api.leaper.one/v1/address/:action
```
Replace `:action` with the specific API action name.
Authentication [#authentication]
```
Authorization: Bearer sk-your-api-key
```
Common Parameters [#common-parameters]
All endpoints share the following JSON body parameters:
| Parameter | Type | Required | Description |
| --------------- | ------ | -------- | -------------------------------- |
| text | string | Yes | The text content to process |
| defaultProvince | string | No | Default province (e.g., `"浙江省"`) |
| defaultCity | string | No | Default city (e.g., `"杭州市"`) |
| defaultDistrict | string | No | Default district (e.g., `"余杭区"`) |
Common Response [#common-response]
```json
{
"RequestId": "xxx-xxx-xxx",
"Data": "{ ... }"
}
```
The `Data` field is a JSON string. You need to call `JSON.parse(response.Data)` to parse it.
Action Reference [#action-reference]
| Action | Endpoint | Description | Price (credits/call) |
| ----------------- | ----------------------------- | -------------------------------- | -------------------- |
| `extract` | `/v1/address/extract` | Address extraction | $0.004 |
| `extract-name` | `/v1/address/extract-name` | Name extraction | $0.004 |
| `extract-phone` | `/v1/address/extract-phone` | Phone number extraction | $0.004 |
| `division-code` | `/v1/address/division-code` | Administrative division code | $0.004 |
| `zipcode` | `/v1/address/zipcode` | Zip code lookup | $0.004 |
| `structure` | `/v1/address/structure` | Address structuring | $0.008 |
| `correct` | `/v1/address/correct` | Address correction | $0.008 |
| `complete` | `/v1/address/complete` | Address completion | $0.008 |
| `standardize` | `/v1/address/standardize` | Address standardization | $0.008 |
| `assessment` | `/v1/address/assessment` | Address anomaly detection | $0.008 |
| `extract-express` | `/v1/address/extract-express` | Shipping label extraction | $0.008 |
| `search` | `/v1/address/search` | Address search | $0.008 |
| `input-search` | `/v1/address/input-search` | Address autocomplete | $0.008 |
| `similarity` | `/v1/address/similarity` | Multi-address similarity | $0.008 |
| `one-id` | `/v1/address/one-id` | Multi-source address unification | $0.008 |
| `geocode` | `/v1/address/geocode` | POI-level geocoding | $0.008 |
| `hp-geocode` | `/v1/address/hp-geocode` | Building-level geocoding | $0.008 |
| `transfer-coord` | `/v1/address/transfer-coord` | Coordinate system conversion | $0.008 |
| `classify-poi` | `/v1/address/classify-poi` | Address type classification | $0.008 |
| `predict-poi` | `/v1/address/predict-poi` | POI prediction | $0.008 |
| `asr` | `/v1/address/asr` | Voice address recognition | $0.008 |
| `inference` | `/v1/address/inference` | Conversational address inference | $0.008 |
Error Codes [#error-codes]
| HTTP Status | Code | Description |
| ----------- | ---------------------- | ------------------------------------- |
| 400 | InvalidParameter | Invalid parameter |
| 401 | missing\_api\_key | API key not provided |
| 402 | insufficient\_credits | Insufficient balance |
| 403 | Forbidden.NoPermission | No permission to access this endpoint |
| 429 | Throttling.User | Rate limit exceeded |
| 500 | InternalError | Upstream internal error |
| 504 | Timeout | Upstream request timeout |
# Smart Applications (/docs/api-reference/address/smart-application)
`similarity` — Multi-address Similarity [#similarity--multi-address-similarity]
Determine whether two addresses refer to the same location, returning a similarity score and distance info.
This endpoint may currently return 500 errors due to upstream service issues.
```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` — Multi-source Address Unification [#one-id--multi-source-address-unification]
Normalize addresses from different sources and return a unique identifier (oneID). Supports POI-level and room-level unification.
```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号万达广场"}'
```
# Smart Input (/docs/api-reference/address/smart-input)
`extract-express` — Shipping Label Extraction [#extract-express--shipping-label-extraction]
Extract name, phone, and address from shipping label text in a single call.
```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` — Address Search [#search--address-search]
Search by pinyin or Chinese characters, returning the top 5 relevant POI results.
```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` — Address Autocomplete [#input-search--address-autocomplete]
Provide detailed address suggestions for search box autocomplete. Supports pinyin, Chinese characters, and other input forms.
```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": "万达"}'
```
# Voice & Conversation (/docs/api-reference/address/voice)
`asr` — Voice Address Recognition [#asr--voice-address-recognition]
Process ASR (Automatic Speech Recognition) transcribed address text and output standardized address information. Suitable for post-processing voice-input addresses.
```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` — Conversational Address Inference [#inference--conversational-address-inference]
Identify addresses through multi-turn conversational reasoning, returning the top 3 candidate results. Suitable for smart customer service, voice assistants, and other conversational scenarios.
```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": "杭州那个阿里巴巴在的地方"}'
```
# Social Media Data API (/docs/api-reference/social-media/data-api)
Access **800+ endpoints** across **16 social media platforms** through a single API. Retrieve videos, user profiles, comments, search results, live streams, trending content, and more.
Endpoint [#endpoint]
```
GET https://api.leaper.one/v1/social-media/data/{platform}/{interface}/{action}
```
All query parameters are forwarded to the upstream provider. Responses are returned in their original format.
Quick Start [#quick-start]
```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"
```
Supported Platforms [#supported-platforms]
| Platform | Prefix | Endpoints | Features |
| ------------- | -------------- | --------- | ------------------------------------------------------- |
| Douyin | `douyin/` | 248 | Video, user, search, live, billboard, creator analytics |
| TikTok | `tiktok/` | 109 | Video, user, search, trending, comments, hashtags |
| Bilibili | `bilibili/` | 41 | Video, user, search, live, danmaku, subtitles |
| YouTube | `youtube/` | 25 | Video, channel, search, comments, playlists |
| Instagram | `instagram/` | 52 | Posts, reels, stories, user profiles, search |
| Twitter/X | `twitter/` | 28 | Tweets, user, search, trends, spaces |
| Weibo | `weibo/` | 30 | Posts, user, search, trending |
| Xiaohongshu | `xiaohongshu/` | 38 | Notes, user, search |
| Kuaishou | `kuaishou/` | 29 | Video, user, search, live |
| WeChat | `wechat/` | 8 | Public accounts, video accounts |
| Threads | `threads/` | 11 | Posts, user profiles |
| LinkedIn | `linkedin/` | 4 | Profiles, posts |
| Zhihu | `zhihu/` | 6 | Answers, articles, user |
| Lemon8 | `lemon8/` | 8 | Posts, user |
| NetEase Music | `netease/` | 12 | Songs, playlists, user |
| Reddit | `reddit/` | 9 | Posts, subreddits, comments |
| Hybrid | `hybrid/` | 2 | Auto-detect platform from URL |
For the complete list of all endpoints and their parameters, fetch the OpenAPI spec at `GET https://api.leaper.one/openapi.json` — it includes every available endpoint with full parameter definitions.
Platform Examples [#platform-examples]
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"
```
**Key Bilibili endpoints:**
| Endpoint | Description |
| ------------------------------------- | ---------------------------- |
| `bilibili/web/fetch_one_video` | Get video by URL |
| `bilibili/web/fetch_video_detail` | Get video details by BV ID |
| `bilibili/web/fetch_video_playurl` | Get video play/download URLs |
| `bilibili/web/fetch_video_comments` | Get video comments |
| `bilibili/web/fetch_video_danmaku` | Get bullet comments |
| `bilibili/web/fetch_video_subtitle` | Get subtitles |
| `bilibili/web/fetch_user_profile` | Get user profile |
| `bilibili/web/fetch_user_post_videos` | Get user's uploaded videos |
| `bilibili/web/fetch_general_search` | Search videos |
| `bilibili/web/fetch_hot_search` | Get trending searches |
| `bilibili/web/fetch_live_room_detail` | Get live room info |
| `bilibili/web/bv_to_aid` | Convert BV ID to AV ID |
Douyin [#douyin]
```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"
```
Hybrid (Auto-detect Platform) [#hybrid-auto-detect-platform]
```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"
```
Response Format [#response-format]
The general response structure is:
```json
{
"code": 200,
"data": {
// Platform-specific data
}
}
```
`code: 200` or `code: 0` indicates success.
Error Responses [#error-responses]
Invalid path (400) [#invalid-path-400]
```json
{ "error": { "message": "Invalid path", "type": "invalid_request_error" } }
```
Platform not available (403) [#platform-not-available-403]
```json
{ "error": { "message": "Platform \"admin\" is not available", "type": "invalid_request_error" } }
```
Upstream timeout (504) [#upstream-timeout-504]
```json
{ "error": { "message": "Upstream request timed out", "type": "server_error" } }
```
Upstream unavailable (503) [#upstream-unavailable-503]
```json
{ "error": { "message": "Failed to reach upstream service", "type": "server_error" } }
```
Pricing [#pricing]
**$0.01 per successful request.** Failed requests (HTTP 4xx/5xx) are not billed.
Comparison with Video Extract [#comparison-with-video-extract]
| Feature | Video Extract | Social Media Data API |
| -------- | ------------------------------------ | ----------------------------------- |
| Endpoint | `GET /v1/social-media/video/extract` | `GET /v1/social-media/data/*` |
| Input | Any social media URL | Platform-specific API path + params |
| Response | Standardized format | Raw upstream response |
| Use case | Quick video download | Full platform API access |
| Scope | Video extraction only | 800+ endpoints across 16 platforms |
| Pricing | $0.01/call | $0.01/call |
**Tip:** If you just need to download videos from a URL, use [Video Extract](/docs/api-reference/social-media/video-extract) for its simpler interface and standardized response. Use the Social Media Data API when you need the full range of platform features (user profiles, search, comments, live streams, etc.).
Notes [#notes]
* All endpoints are GET requests with query string parameters.
* Media URLs (videos, images) are typically time-limited. Download promptly after retrieval.
* Some endpoints may require platform-specific IDs. Use the appropriate search or lookup endpoint first if needed.
* For the complete endpoint catalog with all parameters, import the [OpenAPI spec](/openapi.json) into Postman or Swagger UI.
# Video Extract API (/docs/api-reference/social-media/video-extract)
Extract video download information from social media share links, including multi-quality video streams, separate audio streams, cover images, and metadata.
Endpoint [#endpoint]
```
GET https://api.leaper.one/v1/social-media/video/extract
```
Parameters [#parameters]
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------- |
| `url` | string | Yes | Video URL or share text containing a URL |
The `url` parameter accepts either a direct video URL or raw share text copied from a platform. The API automatically extracts the URL from text.
Supported Platforms [#supported-platforms]
| Platform | URL Patterns | `paramName` | Video Output | Audio Output |
| ----------- | -------------------------------------- | ----------------------- | ----------------------------- | -------------------- |
| Douyin | `v.douyin.com/*`, `*.douyin.com/*` | `url` | Multi-quality 1080p/720p/540p | Background music MP3 |
| TikTok | `*.tiktok.com/*` | `url` | Multi-quality | Background music MP3 |
| Kuaishou | `*.kuaishou.com/*`, `*.gifshow.com/*` | `url` | Multi-quality | Yes |
| Xiaohongshu | `*.xiaohongshu.com/*`, `xhslink.com/*` | `share_text` | H.264/H.265 | — |
| Instagram | `*.instagram.com/*` | `post_url` | Multi-resolution | — |
| Bilibili | `bilibili.com/video/BV*`, `b23.tv/*` | `url` (BV ID extracted) | DASH multi-stream | DASH separate |
| YouTube | `youtube.com/watch?v=*`, `youtu.be/*` | `video_id` (extracted) | 360p–4K, mp4/webm | m4a/weba |
| Twitter/X | `x.com/*/status/*`, `twitter.com/*` | `tweet_id` (extracted) | Multi-bitrate MP4 | — |
| Weibo | `weibo.com/*`, `weibo.cn/*` | `id` (extracted) | 720p/HD/LD | — |
| Xigua | `ixigua.com/*` | `item_id` (extracted) | Yes | — |
| Pipixia | `pipix.com/*`, `pipixia.com/*` | `cell_id` (extracted) | high/low | — |
"—" means audio is embedded in the video file (`audios` is an empty array). Bilibili and YouTube use DASH format with separate audio/video streams — merge with ffmpeg after download.
Request [#request]
```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"
```
Response Examples [#response-examples]
Returns multi-quality video options and background music 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 format with separate video and audio streams. Use ffmpeg to merge.
```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
```
Returns 20+ video formats (360p to 4K) and multiple audio tracks.
```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 usually includes an audio track and can be played directly. Higher resolution streams are video-only — merge with an audio stream from `audios`.
Returns multi-quality video streams.
```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": []
}
}
```
Test URLs [#test-urls]
Copy these to test with the API directly:
| Platform | Test URL |
| -------- | --------------------------------------------------------------- |
| Douyin | `https://v.douyin.com/L4FJNR3/` |
| TikTok | `https://www.tiktok.com/@bellapoarch/video/6862153058223197445` |
| Kuaishou | `https://v.kuaishou.com/dEHKhN` |
| Bilibili | `https://www.bilibili.com/video/BV1cAQqBqEpT/` |
| YouTube | `https://www.youtube.com/watch?v=dQw4w9WgXcQ` |
Response Fields [#response-fields]
| Field | Type | Description |
| --------------- | -------------- | ------------------------------------------------------------------- |
| `platform` | string | Detected platform name |
| `data` | object \| null | Normalized video data. `null` when normalization fails |
| `data.platform` | string | Platform name |
| `data.videoId` | string | Video ID on the platform |
| `data.title` | string | Video title / description |
| `data.author` | string | Author display name |
| `data.authorId` | string | Author ID on the platform |
| `data.coverUrl` | string | Cover image URL |
| `data.duration` | number | Duration in seconds |
| `data.videos` | MediaItem\[] | Available video download options |
| `data.audios` | MediaItem\[] | Available audio download options (empty array if embedded in video) |
| `raw` | object | Raw upstream response — only returned when normalization fails |
MediaItem [#mediaitem]
| Field | Type | Description |
| --------- | ------- | ---------------------------------------------------------- |
| `url` | string | Download URL |
| `quality` | string? | Quality label: `"1080p"`, `"720p"`, `"480p"`, etc. |
| `format` | string? | File format: `"mp4"`, `"webm"`, `"m4a"`, `"mp3"`, `"weba"` |
| `codec` | string? | Codec: `"avc1.640033"`, `"mp4a.40.2"`, `"opus"`, `"vp9"` |
| `width` | number? | Video width in pixels |
| `height` | number? | Video height in pixels |
| `size` | number? | File size in bytes |
Error Responses [#error-responses]
```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" }
}
```
Supported platforms: douyin, kuaishou, xiaohongshu, instagram, bilibili, youtube, twitter, weibo, xigua, pipixia.
```json
{ "error": { "message": "Failed to proxy request", "type": "server_error" } }
```
The upstream data provider is temporarily unreachable.
```json
{ "error": { "message": "Upstream request timed out", "type": "server_error" } }
```
The request took more than 30 seconds. Retry or try a different video URL.
Pricing [#pricing]
**$0.01 per successful request** (HTTP 2xx). Failed requests are not billed.
Notes [#notes]
* Video/audio URLs are time-limited (hours to days). Download promptly after retrieval.
* Douyin and TikTok share a hybrid parser — one endpoint supports both.
* Xiaohongshu supports full URLs and short links (`xhslink.com`).
* `duration` is always in seconds.
* When `data` is `null`, the `raw` field contains the unprocessed upstream response for debugging.