> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidnavigator.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transcribe Online Video (Async)

> Queue a speech-to-text transcription and return a `task_id` immediately.

**Use this instead of `POST /transcribe` for anything longer than ~10 minutes.** A synchronous transcription holds the HTTP connection open for the whole download and speech-to-text pass; past roughly ten minutes of audio that starts failing against client timeouts, reverse proxies and marketplace gateways. This endpoint has no duration cap.

Accepts the same body as `POST /transcribe`, plus `webhook_url`.

`include_usage` is not accepted here: pass it on `GET /transcribe/{task_id}` once `task_status=completed`.

See https://docs.vidnavigator.com/guides/async-jobs

**Submit-time check:** the submit endpoint returns `402` instead of a `task_id` when the account has almost no credits left. A job can still fail later with `402` when the media needs more than the remaining balance. An invalid or deactivated API key is rejected with `401`, and a key without the endpoint's permission with `403`; no task is created in either case.

Transcribe an online video of **any length**. The job runs in the background: you get a `task_id` immediately, then collect the transcript by polling or through a [webhook](https://docs.vidnavigator.com/webhooks.md).

> [!NOTE]
>
> Use this endpoint instead of [`POST /transcribe`](https://docs.vidnavigator.com/api-reference/endpoint/transcribe.md) for media longer than **10 minutes**, which the synchronous endpoint rejects with `video_too_long`. It also works for short videos, so it is the safe default when you don't know the duration.

## How It Works

**1. Submit the job**

`POST /transcribe/async` with the **same body** as [`POST /transcribe`](https://docs.vidnavigator.com/api-reference/endpoint/transcribe.md), plus an optional `webhook_url`. You get `202 Accepted` with a `task_id` and a `check_status_url`.

**2. Wait for the result**

Poll `GET /transcribe/{task_id}` every few seconds while `task_status` is `processing` — polling is free — or receive a [webhook](https://docs.vidnavigator.com/webhooks.md) when the job finishes.

**3. Read the result**

On `completed`, `data.result` is identical to the synchronous response's `data` block, so the same parsing code works for both. On `failed`, `data.error` carries the same error code the synchronous endpoint would have returned.

## Billing

Billed **exactly like** [`POST /transcribe`](https://docs.vidnavigator.com/api-reference/endpoint/transcribe.md) — the async mode costs nothing extra. Charges are made in the background worker, so pass `include_usage=true` on the result request (not on the submit) to see them. A failed job has all of its charges reverted.

## Submit the job

`POST https://api.vidnavigator.com/v1/transcribe/async`

| Parameter         | Type    | Required | Description                                                                                                                                                                                                                                                                      |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `video_url`       | string  | Yes      | URL of the video to transcribe. For Instagram carousel posts, append `?img_index=N` to select a specific video.                                                                                                                                                                  |
| `transcript_text` | boolean | No       | When `true`, returns the transcript as a single plain-text string.                                                                                                                                                                                                               |
| `all_videos`      | boolean | No       | For Instagram carousel posts only. When `true`, transcribes all videos in the post.                                                                                                                                                                                              |
| `webhook_url`     | string  | No       | Where to POST the result when the job finishes. Overrides the account default set in [Studio → API](https://vidnavigator.com/studio/api); pass `""` to opt this job out of the default. Must be a public `https` URL. See [Webhooks](https://docs.vidnavigator.com/webhooks.md). |

> [!NOTE]
>
> `include_usage` is not accepted on the submit request — pass it on the poll request instead.

```bash cURL
curl -X POST "https://api.vidnavigator.com/v1/transcribe/async" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.instagram.com/reel/C86ZvEaqRmo/",
    "webhook_url": "https://example.com/hooks/vidnavigator"
  }'
```

```python Python
import time
import requests

BASE = "https://api.vidnavigator.com"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}

task = requests.post(
    f"{BASE}/v1/transcribe/async",
    headers=HEADERS,
    json={"video_url": "https://www.instagram.com/reel/C86ZvEaqRmo/"},
).json()["data"]

while True:
    job = requests.get(BASE + task["check_status_url"], headers=HEADERS).json()["data"]
    if job["task_status"] != "processing":
        break
    time.sleep(5)

if job["task_status"] == "completed":
    for segment in job["result"]["transcript"]:
        print(f'[{segment["start"]:.2f}s - {segment["end"]:.2f}s] {segment["text"]}')
else:
    print("Failed:", job["error"]["error"], job["error"]["message"])
```

```javascript JavaScript
const BASE = 'https://api.vidnavigator.com';
const HEADERS = { 'X-API-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' };

const { data: task } = await (await fetch(`${BASE}/v1/transcribe/async`, {
  method: 'POST',
  headers: HEADERS,
  body: JSON.stringify({ video_url: 'https://www.instagram.com/reel/C86ZvEaqRmo/' })
})).json();

let job;
do {
  await new Promise(r => setTimeout(r, 5000));
  ({ data: job } = await (await fetch(BASE + task.check_status_url, { headers: HEADERS })).json());
} while (job.task_status === 'processing');

if (job.task_status === 'completed') {
  job.result.transcript.forEach(s => console.log(`[${s.start}s] ${s.text}`));
} else {
  console.error('Failed:', job.error.error, job.error.message);
}
```

### Response (202 Accepted)

```json
{
  "status": "success",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_status": "processing",
    "job_type": "transcribe",
    "expires_at": "2026-09-23T13:00:00Z",
    "check_status_url": "/v1/transcribe/550e8400-e29b-41d4-a716-446655440000",
    "webhook_url": "https://example.com/hooks/vidnavigator",
    "message": "Transcription job accepted."
  }
}
```

| Status | `error`                                     | Description                                                            |
| ------ | ------------------------------------------- | ---------------------------------------------------------------------- |
| `400`  | `missing_parameter`, `invalid_parameter`, … | Invalid request.                                                       |
| `401`  | —                                           | Invalid or deactivated API key.                                        |
| `402`  | `limit_exceeded`                            | Less than 60 seconds of transcription credit left. No task is created. |
| `403`  | —                                           | The API key lacks permission for this endpoint.                        |
| `429`  | `too_many_active_jobs`                      | Too many jobs already running for this account.                        |

## Get the result

> [!NOTE]
>
> The playground above only covers the submit request. Call the result endpoint with cURL or your HTTP client.

`GET https://api.vidnavigator.com/v1/transcribe/{task_id}`

| Parameter       | In    | Required | Description                                                                               |
| --------------- | ----- | -------- | ----------------------------------------------------------------------------------------- |
| `task_id`       | path  | Yes      | The `task_id` returned by `POST /transcribe/async`.                                       |
| `include_usage` | query | No       | When `true` and `task_status=completed`, attaches a `usage` block with the final charges. |

Polling is **free**. Poll every few seconds while `task_status` is `processing`. Results are kept for **1 hour after the job finishes**, and reading a task doesn't delete it.

```bash cURL
curl "https://api.vidnavigator.com/v1/transcribe/550e8400-e29b-41d4-a716-446655440000?include_usage=true" \
  -H "X-API-Key: YOUR_API_KEY"
```

On `completed`, `data.result` is **identical** to the `data` block of the [synchronous response](https://docs.vidnavigator.com/api-reference/endpoint/transcribe.md) (`video_info` + `transcript`, or `carousel_info` + `videos` when `all_videos=true`).

```json
{
  "status": "success",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_status": "completed",
    "job_type": "transcribe",
    "request": { "video_url": "https://www.instagram.com/reel/C86ZvEaqRmo/", "transcript_text": false, "all_videos": false },
    "created_at": "2026-09-23T12:00:00Z",
    "started_at": "2026-09-23T12:00:01Z",
    "completed_at": "2026-09-23T12:00:40Z",
    "expires_at": "2026-09-23T13:00:40Z",
    "check_status_url": "/v1/transcribe/550e8400-e29b-41d4-a716-446655440000",
    "webhook": { "status": "delivered", "attempts": 1, "response_status": 200, "last_error": null, "delivered_at": "2026-09-23T12:00:41Z" },
    "result": {
      "video_info": { "title": "A Reel Interesting Video", "duration": 58.5, "url": "https://www.instagram.com/reel/C86ZvEaqRmo/" },
      "transcript": [
        { "text": "This is the first sentence of the video.", "start": 0.5, "end": 3.2 }
      ]
    },
    "error": null
  }
}
```

On `failed`, `data.result` is `null` and `data.error` carries the same code the synchronous endpoint would have returned, e.g. `{ "error": "transcript_not_available", "message": "...", "http_status": 404 }`. All charges are reverted.

| Status | `error`          | Description                                                                        |
| ------ | ---------------- | ---------------------------------------------------------------------------------- |
| `404`  | `task_not_found` | Unknown `task_id`, expired, owned by another account, or not a transcription task. |

## Webhook

Pass `webhook_url` on the submit request, or configure a default endpoint in [Studio → API](https://vidnavigator.com/studio/api), to be called back when the job finishes. See [Webhooks](https://docs.vidnavigator.com/webhooks.md) for the payload and signature verification, and [Async Jobs](https://docs.vidnavigator.com/guides/async-jobs.md) for the full workflow.

## OpenAPI

````yaml POST /transcribe/async
openapi: 3.0.3
info:
  title: VidNavigator Developer API
  version: 1.0.0
servers:
  - url: https://api.vidnavigator.com/v1
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /transcribe/async:
    post:
      summary: Transcribe a video asynchronously (long videos)
      description: |-
        Queue a speech-to-text transcription and return a `task_id` immediately.

        **Use this instead of `POST /transcribe` for anything longer than ~10 minutes.** A synchronous transcription holds the HTTP connection open for the whole download and speech-to-text pass; past roughly ten minutes of audio that starts failing against client timeouts, reverse proxies and marketplace gateways. This endpoint has no duration cap.

        Accepts the same body as `POST /transcribe`, plus `webhook_url`.

        `include_usage` is not accepted here: pass it on `GET /transcribe/{task_id}` once `task_status=completed`.

        See https://docs.vidnavigator.com/guides/async-jobs

        **Submit-time check:** the submit endpoint returns `402` instead of a `task_id` when the account has almost no credits left. A job can still fail later with `402` when the media needs more than the remaining balance. An invalid or deactivated API key is rejected with `401`, and a key without the endpoint's permission with `403`; no task is created in either case.
      operationId: transcribeVideoAsync
      tags:
        - Transcripts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - video_url
              properties:
                video_url:
                  type: string
                  format: uri
                  description: URL of the video to transcribe. For Instagram carousel posts and Snapchat highlights, append ?img_index=N to select a specific video.
                  example: https://www.youtube.com/watch?v=long-podcast
                transcript_text:
                  type: boolean
                  default: false
                  description: When true, returns the transcript as a single plain-text string instead of an array of segments.
                all_videos:
                  type: boolean
                  default: false
                  description: For Instagram carousel posts and Snapchat highlights only. When true, transcribes ALL videos in the post.
                webhook_url:
                  type: string
                  format: uri
                  description: Where to POST the result when the job finishes. Overrides the account-level default configured in Studio → API. Pass an empty string to opt this job out of that default. Must be a publicly reachable https URL — private, loopback and link-local hosts are rejected. See https://docs.vidnavigator.com/guides/webhooks
                  example: https://example.com/hooks/vidnavigator
      responses:
        "202":
          description: Job accepted and started.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AsyncJobAccepted"
        "400":
          $ref: "#/components/responses/BadRequest"
        "402":
          description: Insufficient credits to queue the job; no task is created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  error:
                    type: string
                    enum:
                      - limit_exceeded
                  error_code:
                    type: string
                    enum:
                      - limit_exceeded
                  message:
                    type: string
        "429":
          description: Too many jobs already running for this account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  error:
                    type: string
                    enum:
                      - too_many_active_jobs
                  message:
                    type: string
        "500":
          $ref: "#/components/responses/InternalServerError"
components:
  schemas:
    AsyncJobAccepted:
      type: object
      description: 202 response from an async submit endpoint.
      properties:
        status:
          type: string
          enum:
            - success
        data:
          type: object
          properties:
            task_id:
              type: string
              description: Identifier to poll with.
              example: 550e8400-e29b-41d4-a716-446655440000
            task_status:
              type: string
              enum:
                - processing
            job_type:
              type: string
              enum:
                - transcribe
                - extract_video
                - tweet_statement
                - watch
            expires_at:
              type: string
              format: date-time
              description: Results are deleted after this time. Until the job finishes this is a provisional submit-time bound; on completion it is pushed out to finish time + 1 hour.
            check_status_url:
              type: string
              description: Relative URL to poll for status and the result.
              example: /v1/transcribe/550e8400-e29b-41d4-a716-446655440000
            webhook_url:
              type: string
              nullable: true
              description: The URL this job's result will be POSTed to, or null if no webhook applies.
            message:
              type: string
            docs_url:
              type: string
  responses:
    BadRequest:
      description: Bad request - invalid parameters. On /transcribe the `error` field may be `missing_parameter`, `unsupported_platform`, `unsupported_url`, `invalid_url`, `request_body_required`, `video_too_long`, or `no_videos_found` (the post carries no video).
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
              message:
                type: string
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - metadata_fetch_failed
                  - audio_extraction_failed
                  - transcription_failed
                  - internal_server_error
              message:
                type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication. Include your VidNavigator API key in the X-API-Key header.
````
