# PieBox Documentation (Full Content)

> This file contains all PieBox documentation for AI consumption.
> Website: https://piebox.me/docs

---

## Getting Started

URL: https://piebox.me/docs/integration/v2/getting-started

TokenHub provides a unified AI API, including:

- **LLM Chat Completions** — Fully compatible with the OpenAI format. You can use the official OpenAI SDK (Python / Node.js / Go, etc.) directly.
- **Integration Services** — Image generation, video generation, text-to-speech, speech-to-text, web search, and more.

After obtaining your API Key, follow this guide to get started. For LLM endpoints, simply change `base_url` and `api_key`. Integration services are called via REST API.

## Service Endpoints & Credentials

### Base URL

| Environment | Base URL                         |
| ----------- | -------------------------------- |
| Production  | `https://tokenhub.piegateway.me` |

### Credential Fields

After applying through the TokenHub Bot, you will receive the following credentials:

| Field       | Description                                                             |
| ----------- | ----------------------------------------------------------------------- |
| `apiKey`    | API key (starts with `sk-`), the only credential needed for daily usage |
| `appId`     | Application ID (used for HMAC signature authentication)                 |
| `appSecret` | Application secret (used for HMAC signature authentication)             |

> **API Key is recommended for most use cases.**
>
> `appId` and `appSecret` are only needed for HMAC signature authentication (server-side integration scenarios).

## Authentication

### API Key (Recommended)

Add one of the following headers to your request:

**X-API-Key Header (Recommended):**

```plaintext
X-API-Key: <your-api-key>
```

**Authorization Header:**

```plaintext
Authorization: Bearer <your-api-key>
```

### HMAC-SHA256 Signature Authentication

For server-side integration with higher security. See the "HMAC-SHA256 Authentication" documentation for details.

---

## Claude Code Setup

URL: https://piebox.me/docs/integration/v2/claude-code

Connect Claude Code to TokenHub using the API Key you received.

## Environment Variables

> **Important: Use the configuration below for Claude Code.** Replace `<your-api-key>` with your API Key and keep all other values as-is.

```bash
export ANTHROPIC_AUTH_TOKEN="<your-api-key>"
export ANTHROPIC_BASE_URL="https://tokenhub.piegateway.me"
export ANTHROPIC_MODEL="claude-opus-4-6"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-opus-4-6"
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

```

> ⚠️ **CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 must be set.** Without it, Claude Code enables experimental features (such as extended thinking) that use non-standard API formats, which will cause request parsing failures or errors when passing through the gateway.

## Setup Steps

**Step 1** — Check your shell type:

```bash
echo $SHELL

```

**Step 2** — Choose the correct config file:

- `zsh` → edit `~/.zshrc`
- `bash` → edit `~/.bash_profile`

**Step 3** — If you previously configured Claude Code / Anthropic / Bedrock, comment out the old `ANTHROPIC_*`, `CLAUDE_CODE_*`, and `AWS_*` variables to avoid conflicts.

**Step 4** — Append the full configuration from the "Environment Variables" section above to the end of your config file, replacing `<your-api-key>` with your actual API Key.

**Step 5** — Reload your config and start Claude Code:

```bash
source ~/.zshrc   # or source ~/.bash_profile
claude

```

## Verify Configuration

Check that environment variables are set:

```bash
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_MODEL

```

Verify that the API Key works:

```bash
curl -s https://tokenhub.piegateway.me/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" | head -c 200

```

If the model list is returned, the configuration is successful.

## FAQ

**Changes don't take effect** — Usually caused by not reloading the config. Run `source ~/.zshrc` or `source ~/.bash_profile`.

**Multiple old configs overriding each other** — Check your config file for duplicate `ANTHROPIC_*`, `CLAUDE_CODE_*`, or `AWS_*` entries. Comment out the old ones and reload.

---

## Chat Completions API

URL: https://piebox.me/docs/integration/v2/llm/chat-completions

## Quick Start

**cURL:**

```bash
curl -X POST https://tokenhub.piegateway.me/chat/completions \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 100
  }'

```

**TypeScript:**

```typescript
import OpenAI from "openai"

const client = new OpenAI({
  apiKey: "<your-api-key>",
  baseURL: "https://tokenhub.piegateway.me",
})

const response = await client.chat.completions.create({
  model: "claude-haiku-4-5",
  messages: [{ role: "user", content: "Hello" }],
  max_tokens: 100,
})

console.log(response.choices[0].message.content)
```

## Chat Completions Endpoint

```plaintext
POST /chat/completions

```

**Request Body (JSON):**

```json
{
  "model": "gpt-5.4-mini",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant" },
    { "role": "user", "content": "Hello" }
  ],
  "temperature": 0.7,
  "max_tokens": 1000,
  "stream": false
}
```

**Parameters:**

| Parameter     | Type    | Required | Description                                       |
| ------------- | ------- | -------- | ------------------------------------------------- |
| `model`       | string  | Yes      | Model name — use `GET /v1/models` to list options |
| `messages`    | array   | Yes      | Array of conversation messages                    |
| `temperature` | number  | No       | Randomness (0–2), default 1                       |
| `max_tokens`  | number  | No       | Maximum output tokens                             |
| `stream`      | boolean | No       | Enable streaming output, default false            |

**Response Example:**

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-5.4-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 12,
    "total_tokens": 22
  }
}
```

## List Available Models

```plaintext
GET /v1/models

```

```bash
curl https://tokenhub.piegateway.me/v1/models \
  -H "X-API-Key: <your-api-key>"

```

**Response Example:**

```json
{
  "object": "list",
  "data": [
    { "id": "gpt-5.4-mini", "object": "model" },
    { "id": "gpt-4o", "object": "model" },
    { "id": "claude-sonnet-4-20250514", "object": "model" }
  ]
}
```

## Streaming Output

Add `"stream": true` to the request body. The response will use SSE (Server-Sent Events) format:

```bash
curl -X POST https://tokenhub.piegateway.me/chat/completions \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'
```

---

## Quota & Limits

URL: https://piebox.me/docs/integration/v2/quota

## Monthly Quota

- Each user has a monthly base quota that resets automatically on the 1st of each month
- When the quota is exhausted, the API will return `402 budget_exceeded`
- You can check your current usage via the "View My Quota" feature in the TokenHub Bot

## Requesting a Top-Up

When you need more quota, submit a request through the "Request Top-Up" feature in the TokenHub Bot. It takes effect immediately after approval.

## Common Error Codes

| Status | Error Type        | Description                                                 |
| ------ | ----------------- | ----------------------------------------------------------- |
| 401    | `unauthorized`    | Invalid or missing API Key                                  |
| 402    | `budget_exceeded` | Monthly quota exhausted — request a top-up via TokenHub Bot |
| 403    | `app_disabled`    | Application has been disabled — contact your admin          |
| 429    | `rate_limited`    | Request rate exceeded — please retry later                  |

## Important Notes

1. Keep your API Key safe — do not commit it to code repositories or share it publicly
1. If you encounter issues, submit feedback through the "Report Issue" feature in the TokenHub Bot

---

## HMAC-SHA256 Authentication

URL: https://piebox.me/docs/integration/v2/hmac-auth

For server-side integration scenarios requiring higher security than API Key. For everyday use with tools like Claude Code, API Key authentication is sufficient.

## Authentication Flow & Request Headers

**Authentication Flow:**

1. Obtain `appId` and `appSecret` (select "Other" scenario when applying)
1. Build the signature string
1. Sign it with `appSecret` using HMAC-SHA256
1. Include the authentication info in request headers

**Request Headers:**

| Header          | Description                                                          |
| --------------- | -------------------------------------------------------------------- |
| `X-App-Id`      | Application ID                                                       |
| `X-Timestamp`   | Unix timestamp (seconds), valid for 5 minutes                        |
| `X-Nonce`       | Random string to prevent replay attacks — must be unique per request |
| `Authorization` | `HMAC-SHA256 {signature}`                                            |

## Signature Computation

Signature string format (fields joined with newline `\n`):

```plaintext
{HTTP_METHOD}\n{PATH}\n{TIMESTAMP}\n{NONCE}\n{APP_ID}

```

**Field Descriptions:**

| Field         | Description                       | Example                            |
| ------------- | --------------------------------- | ---------------------------------- |
| `HTTP_METHOD` | Request method (uppercase)        | `POST`                             |
| `PATH`        | Request path (no domain or query) | `/chat/completions`                |
| `TIMESTAMP`   | Current Unix timestamp (seconds)  | `1706745600`                       |
| `NONCE`       | 32-char random hex string         | `a1b2c3d4e5f67890abcdef1234567890` |
| `APP_ID`      | Application ID                    | `app_xxxxx`                        |

**Steps:**

1. Concatenate the signature string using the format above (use actual newline characters `\n`, not literal backslash-n)
1. Compute HMAC-SHA256 using `appSecret` as the key
1. Convert the result to a lowercase hexadecimal string

## Code Examples

### Node.js

```typescript
import { createHmac, randomBytes } from "crypto"

const APP_ID = "<your-app-id>"
const APP_SECRET = "<your-app-secret>"
const BASE_URL = "https://tokenhub.piegateway.me"

function computeSignature(
  method: string,
  path: string,
  timestamp: number,
  nonce: string,
  appId: string,
  appSecret: string,
): string {
  const signatureString = `${method}\n${path}\n${timestamp}\n${nonce}\n${appId}`
  return createHmac("sha256", appSecret).update(signatureString).digest("hex")
}

function generateAuthHeaders(method: string, path: string) {
  const timestamp = Math.floor(Date.now() / 1000)
  const nonce = randomBytes(16).toString("hex")
  const signature = computeSignature(method, path, timestamp, nonce, APP_ID, APP_SECRET)

  return {
    "X-App-Id": APP_ID,
    "X-Timestamp": timestamp.toString(),
    "X-Nonce": nonce,
    Authorization: `HMAC-SHA256 ${signature}`,
    "Content-Type": "application/json",
  }
}

// Usage example
const path = "/chat/completions"
const headers = generateAuthHeaders("POST", path)

const response = await fetch(`${BASE_URL}${path}`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "claude-haiku-4-5",
    messages: [{ role: "user", content: "Hello" }],
    max_tokens: 100,
  }),
})

const result = await response.json()
console.log(result)
```

### Bash

```bash
#!/bin/bash
APP_ID="<your-app-id>"
APP_SECRET="<your-app-secret>"
BASE_URL="https://tokenhub.piegateway.me"
METHOD="POST"
API_PATH="/chat/completions"
TIMESTAMP=$(date +%s)
NONCE=$(openssl rand -hex 16)

# Build signature string
SIGNATURE_STRING=$(printf "%s\n%s\n%s\n%s\n%s" "$METHOD" "$API_PATH" "$TIMESTAMP" "$NONCE" "$APP_ID")

# Compute HMAC-SHA256 signature (compatible with macOS and Linux)
SIGNATURE=$(echo -n "$SIGNATURE_STRING" | openssl dgst -sha256 -hmac "$APP_SECRET" | sed 's/^.*= //')

curl -X POST "{BASE_URL}{API_PATH}" \
  -H "X-App-Id: ${APP_ID}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "Authorization: HMAC-SHA256 ${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 100
  }'

```

## WebSocket Authentication

WebSocket connections also support HMAC-SHA256 signature authentication:

**Method 1: Headers (Recommended)**

```typescript
const ws = new WebSocket("wss://tokenhub.piegateway.me/ws/...", {
  headers: generateAuthHeaders("GET", "/ws/..."),
})
```

**Method 2: Query Parameters (for browser environments)**

```typescript
const params = new URLSearchParams({
  "X-App-Id": APP_ID,
  "X-Timestamp": timestamp.toString(),
  "X-Nonce": nonce,
  Authorization: `HMAC-SHA256 ${signature}`,
})
const ws = new WebSocket(`wss://tokenhub.piegateway.me/ws/...?${params}`)
```

## Security Constraints & Error Codes

**Security Constraints:**

| Constraint         | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| Timestamp validity | 5 minutes (300 seconds) — expired requests will be rejected |
| Nonce replay guard | Same nonce can be used at most 3 times, expires after 300s  |
| Signature case     | Signature must be a lowercase hexadecimal string            |

**HMAC Authentication Error Codes:**

| Status | Error Type             | Description                                                       |
| ------ | ---------------------- | ----------------------------------------------------------------- |
| 401    | `missing_auth_headers` | Required authentication headers are missing                       |
| 401    | `invalid_timestamp`    | Timestamp expired (more than 5 minutes)                           |
| 401    | `nonce_reused`         | Nonce has been reused (replay protection)                         |
| 401    | `invalid_app`          | appId does not exist                                              |
| 401    | `invalid_signature`    | Signature verification failed — check appSecret and string format |
| 403    | `app_disabled`         | Application has been disabled                                     |

---

## Integration Services Overview

URL: https://piebox.me/docs/integration/v2/extend/overview

In addition to the OpenAI-compatible chat interface, TokenHub also provides integration services for image generation, video generation, text-to-speech, speech-to-text, search, and more.

## Base URL & Authentication

Integration services use two endpoint prefixes:

| Type      | Base URL                                    |
| --------- | ------------------------------------------- |
| HTTP API  | `https://tokenhub.piegateway.me/v2/extend`  |
| WebSocket | `wss://tokenhub.piegateway.me/ws/v2/extend` |

HTTP authentication (pick one):

```plaintext
X-API-Key: <your-api-key>

```

```plaintext
Authorization: Bearer <your-api-key>

```

WebSocket connections only support HMAC-SHA256 signature authentication (passed via query params). See the HMAC-SHA256 Authentication documentation for details.

---

---

## Image Generation

URL: https://piebox.me/docs/integration/v2/extend/image

Multiple models are supported: Seedream (lightweight, optimized for Chinese prompts), Gemini Flash/Pro, and GPT-Image-2.

## Seedream

Best for Chinese-language prompts. Ideal for Chinese-style art, anime, and everyday illustrations.

**Request:**

```plaintext
POST /v2/extend/image/seedream/generations

```

**Parameters:**

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| prompt    | string | Yes      | Image description                                      |
| size      | string | No       | Dimensions, minimum 1920×1920 (must be ≥ 3.68M pixels) |
| image     | array  | No       | Reference images (URL or base64)                       |

**Example:**

```bash
curl https://tokenhub.piegateway.me/v2/extend/image/seedream/generations \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cat playing guitar on the moon",
    "size": "2048x2048"
  }'

```

**Response:**

```json
{ "task_id": "img_gen_xxx", "model": "novita_seedream/seedream-5.0-lite" }
```

## Gemini

Versatile styles. Available in Flash (fast) and Pro (high quality).

**Request:**

```plaintext
POST /v2/extend/image/generations

```

**Parameters:**

| Parameter     | Type   | Required | Description                                                       |
| ------------- | ------ | -------- | ----------------------------------------------------------------- |
| model         | string | No       | Model name, default gemini-3.1-flash-image, or gemini-3-pro-image |
| prompt        | string | Yes      | Image description                                                 |
| size          | string | No       | Options: 0.5K, 1K, 2K, 4K                                         |
| aspect_ratio  | string | No       | Aspect ratio: 1:1, 3:2, 2:3, 3:4, 4:3, 16:9, 9:16                 |
| output_format | string | No       | Output format: image/png, image/jpeg, image/webp                  |

**Example:**

```bash
curl https://tokenhub.piegateway.me/v2/extend/image/generations \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "a cat playing guitar on the moon",
    "size": "2K"
  }'

```

## GPT-Image-2

OpenAI's image model. Best for text rendering in images.

**Request:**

```plaintext
POST /v2/extend/image/gpt_image/generations

```

**Parameters:**

| Parameter          | Type   | Required | Description                       |
| ------------------ | ------ | -------- | --------------------------------- |
| prompt             | string | Yes      | Image description                 |
| size               | string | No       | e.g. 1024x1024, 1024x1536         |
| quality            | string | No       | Quality tier: low / medium / high |
| n                  | number | No       | Number of images (default 1)      |
| background         | string | No       | Background: opaque / transparent  |
| output_format      | string | No       | Output format: png / jpeg / webp  |
| output_compression | number | No       | Compression rate (0–100)          |

**Example:**

```bash
curl https://tokenhub.piegateway.me/v2/extend/image/gpt_image/generations \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a futuristic city at sunset",
    "size": "1024x1024",
    "quality": "medium"
  }'

```

## Checking Image Generation Results

All image generation endpoints are asynchronous — they return a `task_id`, and you need to poll for the result.

**Request:**

```plaintext
GET /v2/extend/image/tasks/{task_id}
GET /v2/extend/image/seedream/tasks/{task_id}
GET /v2/extend/image/gpt_image/tasks/{task_id}

```

**Example:**

```bash
curl https://tokenhub.piegateway.me/v2/extend/image/seedream/tasks/<task_id> \
  -H "X-API-Key: <your-api-key>"

```

**Response Example:**

```json
{
  "task_id": "img_gen_xxx",
  "status": "succeeded",
  "model": "novita_seedream/seedream-5.0-lite",
  "result": {
    "images": [{ "url": "https://..." }]
  }
}
```

Status values: `pending` → `processing` → `succeeded` or `failed`

---

---

## Video Generation

URL: https://piebox.me/docs/integration/v2/extend/video

Supports text-to-video (t2v) and image-to-video (i2v).

**Request:**

```plaintext
POST /v2/extend/video/generations

```

**Parameters:**

| Parameter       | Type    | Required | Description                                                                                    |
| --------------- | ------- | -------- | ---------------------------------------------------------------------------------------------- |
| model           | string  | Yes      | Model name: seedance-2.0, seedance-2.0-fast, kling-v3.0-pro, kling-v3.0, veo-3.1, veo-3.1-fast |
| prompt          | string  | Yes      | Video description                                                                              |
| image           | string  | No       | First-frame image URL (if provided, generates image-to-video)                                  |
| duration        | number  | No       | Video duration in seconds                                                                      |
| aspect_ratio    | string  | No       | Aspect ratio: 16:9, 9:16, 1:1                                                                  |
| sound           | boolean | No       | Whether to generate sound                                                                      |
| negative_prompt | string  | No       | Negative prompt                                                                                |

**Example (text-to-video):**

```bash
curl https://tokenhub.piegateway.me/v2/extend/video/generations \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "a cat running on a grass field",
    "duration": 5
  }'
```

**Example (image-to-video):**

```bash
curl https://tokenhub.piegateway.me/v2/extend/video/generations \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3.0-pro",
    "prompt": "make the person smile and turn their head",
    "image": "https://example.com/photo.jpg",
    "duration": 5
  }'

```

**Check video generation result:**

```plaintext
GET /v2/extend/video/tasks/{task_id}

```

**Example:**

```bash
curl https://tokenhub.piegateway.me/v2/extend/video/tasks/<task_id> \
  -H "X-API-Key: <your-api-key>"

```

---

---

## Text-to-Speech (TTS)

URL: https://piebox.me/docs/integration/v2/extend/tts

## Gemini TTS (Multilingual)

Best results in English. Supports 24 common languages. Returns raw PCM audio data.

**Request:**

```plaintext
POST /v2/extend/tts/gemini/synthesize

```

**Parameters:**

| Parameter     | Type   | Required | Description                                        |
| ------------- | ------ | -------- | -------------------------------------------------- |
| text          | string | Yes      | Text to synthesize (≤ 10,000 characters)           |
| voice_name    | string | No       | Voice name (e.g. Kore, Puck, Charon)               |
| prompt        | string | No       | Voice style hint (e.g. "speak slowly and clearly") |
| language_code | string | No       | Language code (e.g. en-US, zh-CN)                  |
| temperature   | number | No       | Controls randomness                                |

**Example:**

```bash
curl https://tokenhub.piegateway.me/v2/extend/tts/gemini/synthesize \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, this is a test.", "voice_name": "Kore"}' \
  -o output.pcm

```

**Response**: Raw PCM audio stream (LINEAR16, 24kHz, mono).

Convert to a playable format with ffmpeg:

```bash
ffmpeg -f s16le -ar 24000 -ac 1 -i output.pcm output.mp3

```

## ElevenLabs TTS (High Quality)

Industry-leading audio quality. Supports 70+ languages.

**Request:**

```plaintext
POST /v2/extend/tts/elevenlabs/synthesize

```

**Parameters:**

| Parameter     | Type   | Required | Description                              |
| ------------- | ------ | -------- | ---------------------------------------- |
| text          | string | Yes      | Text to synthesize (≤ 10,000 characters) |
| voice_id      | string | Yes      | Voice ID                                 |
| language_code | string | No       | Language code                            |
| output_format | string | No       | Output format                            |

**Example:**

```bash
curl https://tokenhub.piegateway.me/v2/extend/tts/elevenlabs/synthesize \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "voice_id": "21m00Tcm4TlvDq8ikWAM"}' \
  -o output.mp3

```

---

---

## Speech-to-Text (ASR)

URL: https://piebox.me/docs/integration/v2/extend/asr

## Fast Speech-to-Text

Best for real-time voice input — the fastest option.

**Request:**

```plaintext
POST /v2/extend/asr/transcriptions

```

**Parameters:**

| Parameter   | Type    | Required   | Description                                 |
| ----------- | ------- | ---------- | ------------------------------------------- |
| model       | string  | No         | Default volc.bigasr.auc_turbo, or whisper-1 |
| audio_url   | string  | One of two | Audio file URL                              |
| audio_data  | string  | One of two | Base64-encoded audio data                   |
| enable_itn  | boolean | No         | Enable number/unit normalization            |
| enable_punc | boolean | No         | Enable punctuation                          |
| enable_ddc  | boolean | No         | Enable disfluency removal                   |

**Example:**

```bash
curl https://tokenhub.piegateway.me/v2/extend/asr/transcriptions \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volc.bigasr.auc_turbo",
    "audio_url": "https://example.com/audio.mp3"
  }'

```

**Response:**

```json
{
  "model": "volc.bigasr.auc_turbo",
  "text": "Transcribed text content",
  "duration_ms": 5000
}
```

## File-Based Transcription (Async)

Upload a complete recording for async transcription. Best for long audio files.

**Parameters:**

| Parameter           | Type    | Required | Description                         |
| ------------------- | ------- | -------- | ----------------------------------- |
| audio_url           | string  | Yes      | Audio file URL                      |
| model               | string  | No       | Model name, default volc.bigasr.auc |
| format              | string  | No       | Audio format, default mp3           |
| language            | string  | No       | Language code                       |
| enable_itn          | boolean | No       | Enable number/unit normalization    |
| enable_punc         | boolean | No       | Enable punctuation                  |
| enable_speaker_info | boolean | No       | Enable speaker identification       |
| show_utterances     | boolean | No       | Return utterance details            |

**Submit Task:**

```plaintext
POST /v2/extend/asr/tasks

```

**Example:**

```bash
curl https://tokenhub.piegateway.me/v2/extend/asr/tasks \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/long-audio.mp3"
  }'

```

**Check Result:**

```plaintext
GET /v2/extend/asr/tasks/{taskId}

```

**Example:**

```bash
curl https://tokenhub.piegateway.me/v2/extend/asr/tasks/<taskId> \
  -H "X-API-Key: <your-api-key>"

```

## Real-Time Streaming ASR (WebSocket)

For real-time conversations and voice input with low latency. Send audio chunks over WebSocket and receive recognition results in real time.

**Connection URL:**

```plaintext
GET /ws/v2/extend/asr/stream?model=volc.bigasr.sauc

```

**Authentication:** Only HMAC-SHA256 signature authentication is supported, passed via query params:

```plaintext
wss://tokenhub.piegateway.me/ws/v2/extend/asr/stream?model=volc.bigasr.sauc&X-App-Id=<app_id>&X-Timestamp=<timestamp>&X-Nonce=<nonce>&Authorization=HMAC-SHA256 <signature>

```

**Communication Protocol:**

1. After connecting, the client continuously sends binary audio data (PCM 16kHz 16-bit mono)
1. The server returns recognition results in real time as JSON
1. When finished, the client sends a text message `{"is_last": true}` to signal the end

**Optional Query Parameters:**

| Parameter   | Type    | Required | Description                          |
| ----------- | ------- | -------- | ------------------------------------ |
| model       | string  | No       | Model name, default volc.bigasr.sauc |
| enable_itn  | boolean | No       | Enable number/unit normalization     |
| enable_punc | boolean | No       | Enable punctuation                   |

**Response Message Format:**

```json
{
  "text": "Current recognition result",
  "is_final": false,
  "utterances": [{ "text": "Utterance 1", "definite": true }]
}
```

---

---

## Search

URL: https://piebox.me/docs/integration/v2/extend/search

## Real-Time Search (Serper)

Search and read real-time web content.

**Request:**

```plaintext
POST /v2/extend/web/serper/search

```

**Parameters:**

| Parameter   | Type   | Required | Description                               |
| ----------- | ------ | -------- | ----------------------------------------- |
| q           | string | Yes      | Search keywords                           |
| gl          | string | No       | Country code (e.g. us, cn)                |
| hl          | string | No       | Language (e.g. en, zh-cn)                 |
| type        | string | No       | Search type: search, images, videos, news |
| max_results | number | No       | Maximum number of results (up to 10)      |

**Example:**

```bash
curl https://tokenhub.piegateway.me/v2/extend/web/serper/search \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"q": "latest AI news 2026", "gl": "us", "hl": "en"}'

```

## Deep Search (Exa)

Semantic search for deeper, more precise results.

**Request:**

```plaintext
POST /v2/extend/web/exa/search

```

**Parameters:**

| Parameter      | Type   | Required | Description                          |
| -------------- | ------ | -------- | ------------------------------------ |
| query          | string | Yes      | Search query                         |
| type           | string | No       | Search mode: neural / keyword / auto |
| numResults     | number | No       | Number of results to return          |
| category       | string | No       | Category filter                      |
| includeDomains | array  | No       | Only search specified domains        |
| excludeDomains | array  | No       | Exclude specified domains            |

**Example:**

```bash
curl https://tokenhub.piegateway.me/v2/extend/web/exa/search \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "latest LLM research", "numResults": 5}'
```

---