---
url: /docs/asr_text.md
description: >-
  Speech-to-text API. Transcribe audio and return punctuated plain text only,
  without any timeline.
---

# ASR\_TEXT API Documentation

## 🌐 Language Switch

[中文版](/docs/asr_text.zh) | [English](/docs/asr_text)

## Interface Information

```
POST /openapi/autosubrt/v1/asr/text
```

::: warning This is the speech recognition service
The base URL of this interface is `https://autosubrt.jcaigc.cn`, which is a different service (and a different path prefix) from CapCut Mate (`https://capcut-mate.jcaigc.cn`).

```
Full URL = https://autosubrt.jcaigc.cn + /openapi/autosubrt/v1/asr/text
```

:::

## Function Description

Speech recognition: transcribe audio into **punctuated plain text** and return it directly, with no timeline at all. Use it when you only need the copy, since the response body is minimal.

For sentences plus per-character timelines use [ASR](/docs/asr); for an SRT subtitle file use [ASR SRT](/docs/asr_srt).

Punctuation is restored by a dedicated punctuation model (Whisper is unreliable on Chinese punctuation), so `text` **always carries punctuation**.

## Request Parameters

```json
{
  "audio_url": "https://example.com/audio.mp3",
  "apiKey": "123e4567-e89b-12d3-a456-426614174000"
}
```

### Parameter Description

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| audio\_url | string | ✅ | - | Audio file URL, must be downloadable by the server |
| apiKey | string | Required when billing is on | - | A valid UUID; get one at https://jcaigc.cn |

### Parameter Details

#### audio\_url

* **Type**: string
* **Description**: The server downloads this URL before transcribing, so it must be a **direct, publicly reachable link** (not a page that requires login)
* **Format**: Any common audio or video file: wav, mp3, m4a, aac, flac, ogg; video files such as mp4 and mov also work (the audio track is extracted server-side)
* **Limit**: 100MB per file (server-side `FILE_SIZE_LIMIT`, 104857600 bytes by default)

#### apiKey

* **Type**: string
* **Description**: Must be a valid UUID; required while billing is enabled (it is by default), and the account balance must be **greater than 1**

## Response Format

### Success Response (200)

```json
{
  "code": 0,
  "message": "Success",
  "data": {
    "text": "你们应该都听过啊，羊毛羊绒当中的软黄金。"
  }
}
```

### Response Field Description

| Field | Type | Description |
|-------|------|-------------|
| code | int | 0 means success; see the error codes below otherwise |
| message | string | Human-readable message, Chinese by default, English when `Accept-Language: en` is sent |
| data.text | string | The full transcript, **always punctuated**; an empty string when no speech was recognized |

### Error Response

```json
{
  "code": 2003,
  "message": "Download file failed"
}
```

Error bodies contain **no** `data` field; every error is returned with HTTP 200, so check `code` instead of the status code.

## Usage Examples

### cURL Examples

```bash
curl -X POST https://autosubrt.jcaigc.cn/openapi/autosubrt/v1/asr/text \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/audio.mp3",
    "apiKey": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

### Python Example

```python
import requests

resp = requests.post(
    "https://autosubrt.jcaigc.cn/openapi/autosubrt/v1/asr/text",
    json={
        "audio_url": "https://example.com/audio.mp3",
        "apiKey": "123e4567-e89b-12d3-a456-426614174000",
    },
    timeout=600,
)

result = resp.json()
if result["code"] != 0:
    raise RuntimeError(result["message"])

print(result["data"]["text"])
```

## Billing

This interface is charged by **audio duration** and shares the same points system as CapCut Mate.

| Item | Description |
| --- | --- |
| Price | **0.00022 points / second** |
| Basis | Actual audio duration in seconds, as reported by the recognition engine |
| When charged | Only after a **successful** recognition; failures are not charged |
| Balance gate | The account must hold **more than 1** point before the call, otherwise it is rejected (2035) |

| Audio duration | Cost (points) |
| --- | --- |
| 10 seconds | 0.002200 |
| 60 seconds | 0.013200 |
| 1 hour | 0.792000 |

`apiKey` must be a valid UUID and can be obtained at <https://jcaigc.cn>.

## Error Code Description

| Error Code | Error Message | Description | Solution |
|------------|---------------|-------------|----------|
| 1001 | Parameter validation failed | apiKey is not a valid UUID | Check the request parameters |
| 2001 | Failed to recognize audio | Audio could not be decoded, model not loaded, or audio\_url returned 401/403/404 | Try a playable file or a reachable direct link |
| 2002 | File size exceeds the limit | Audio is larger than 100MB | Compress or trim it and retry |
| 2003 | Download file failed | Network or server error during download, still failing after retries | Make sure it is a public direct download link |
| 2005 | Download file timeout | Overall download timed out | Use a faster source or a smaller file |
| 2035 | Insufficient account balance | The account needs more than 1 point to keep using the service | Recharge and retry |
| 2036 | Invalid apiKey | apiKey missing while billing is enabled | Get an apiKey at https://jcaigc.cn |
| 9997 | Server is busy | Concurrency limit reached; the request was not queued | Retry later |
| 9998 | Internal server error | Unexpected internal error | Contact technical support |
| 9999 | Unknown error | Points service unavailable, etc. | Retry later |

## Notes

1. **`audio_url` is not URL-validated**: passing an empty or non-URL string does not return 1001, it fails during download with 2003.
2. **Text only**: the response carries no timing information. Use [ASR](/docs/asr) when you need sentences and per-character timelines.
3. **When no speech is recognized** the call succeeds and `data.text` is an empty string.
4. **Repeated calls are charged repeatedly**; do not blindly retry after a timeout.

## Workflow

1. Validate apiKey and account balance (while billing is enabled)
2. Download the audio/video behind `audio_url` into a server-side temp directory
3. Run speech recognition and restore punctuation with the punctuation model
4. Charge by audio duration after a successful recognition
5. Return the plain text, then delete the temp file

## Related Interfaces

* [ASR](/docs/asr)
* [ASR SRT](/docs/asr_srt)
* [Align Text To Audio](/docs/asr_text_align)

***

📚 **Project Resources**\
**GitHub**: <https://github.com/Hommy-master/autosubrt>