# Eleven Scribe v2

> Transcribe speech from audio or video, with word timings and speaker labels.

## Overview

- **Model ID**: `eleven-speech-to-text`
- **Workflow**: `elevenlabs/v1/speech-to-text`
- **Provider**: ElevenLabs
- **Category**: a2t (text)
- **Output**: Generated text.
- **Tags**: transcription, speaker labels
- **Unified endpoint**: `POST https://api.picsart.com/workflows/v1/models/execute` (model id in the body)
- **Compatibility endpoint**: `POST https://api.picsart.com/workflows/elevenlabs/v1/speech-to-text/execute` (vendor's own parameters)
- **Execution**: sync (`/execute`) returns the result in one call; async is also available
- **Model page**: https://picsart.com/api-platform/models/eleven-speech-to-text

## Pricing

Rates are in USD. Every row below is an exact rate for the settings it names — the columns are the settings that change the price for this model. Every response reports what was actually charged in `response.usage.credits`.

| Rate |
| --- |
| $0.008 / min |

Published rates. Volume pricing, invoicing and annual agreements: https://picsart.com/api-platform/contact-sales

## Authentication

The SDK and the REST API authenticate with a Picsart API key sent as a bearer token. Create a key in the console at https://picsart.com/api-platform/dashboard/api-keys, keep it in a server-side environment variable, and never ship it in browser code or commit it.

```bash
export PICSART_API_KEY="YOUR_KEY"
```

```http
Authorization: Bearer $PICSART_API_KEY
```

The CLI and the MCP server do not use an API key: `gen-ai login` signs in through the browser once per machine and stores a token locally.

## Interfaces

- **SDK** — `@picsart/ai-sdk` (TypeScript, Node 20+, ESM). Type-safe `ai.generate()` / `ai.generateText()` with per-model parameter types; polls long jobs for you.
- **REST** — the API gateway at `https://api.picsart.com`. Sync `/execute`, or async `/submit` + `/{taskId}/result`.
- **CLI** — `@picsart/gen-ai` (`gen-ai`). Generate from a terminal, quote cost before spending, emit JSON for pipelines.
- **MCP** — the same models inside Claude Code, Cursor, Windsurf and other MCP hosts. Setup: https://picsart.com/gen-ai-mcp/

```bash
npm install @picsart/ai-sdk      # SDK
npm install -g @picsart/gen-ai   # CLI (also drives the MCP server)
```

## Unified API (recommended)

One parameter set, used by the SDK and by REST alike: the names below are what `ai.generate('eleven-speech-to-text', …)` takes, and what goes inside the inner `params` of a REST call. Over REST the model id travels in the body, not the path — one workflow, `v1/models`, fronts the whole catalogue.

### Execution modes

- **Sync** — `POST /workflows/v1/models/execute` returns the result in one call. Only for jobs that finish within ~20 seconds; otherwise it times out.
- **Async** — `POST /workflows/v1/models/submit` returns a task id; poll `GET /workflows/v1/models/{taskId}/result` until `response.status` is `COMPLETED` or `FAILED`. Task statuses: `ACCEPTED` · `IN_PROGRESS` · `COMPLETED` · `FAILED`.
- **SDK** — `ai.generate()` always awaits the finished result; polling is hidden.

### Input parameters

- **`audioUrl`** (`string`, _required_): Audio or Video
  - Accepts: audio URL
- **`language`** (`string`, _optional_): Language (ISO code, optional)
  - e.g. "e.g. en, rus — omit to auto-detect"
- **`diarize`** (`boolean`, _optional_): Label Speakers
  - Default: `false`
- **`numSpeakers`** (`number`, _optional_): Speakers
  - Default: `1`
  - Range: 1–32 (step 1)
- **`timestampsGranularity`** (`string`, _optional_): Timing Detail
  - Default: `"word"`
  - Options: `word`, `character`
- **`tagAudioEvents`** (`boolean`, _optional_): Tag Audio Events
  - Default: `false`
- **`seed`** (`number`, _optional_): Seed
  - Range: 0–2147483647 (step 1)

### Input JSON Schema

The inner `params` object. Over REST it is wrapped as `{ "params": { "model": "<id>", "params": <this> } }`; the SDK takes it directly.

```json
{
  "type": "object",
  "required": [
    "audioUrl"
  ],
  "properties": {
    "audioUrl": {
      "type": "string",
      "format": "uri",
      "description": "Audio or Video"
    },
    "language": {
      "type": "string",
      "description": "Language (ISO code, optional)"
    },
    "diarize": {
      "type": "boolean",
      "default": false,
      "description": "Label Speakers"
    },
    "numSpeakers": {
      "type": "number",
      "minimum": 1,
      "maximum": 32,
      "multipleOf": 1,
      "default": 1,
      "description": "Speakers"
    },
    "timestampsGranularity": {
      "type": "string",
      "enum": [
        "word",
        "character"
      ],
      "default": "word",
      "description": "Timing Detail"
    },
    "tagAudioEvents": {
      "type": "boolean",
      "default": false,
      "description": "Tag Audio Events"
    },
    "seed": {
      "type": "number",
      "minimum": 0,
      "maximum": 2147483647,
      "multipleOf": 1,
      "description": "Seed"
    }
  },
  "additionalProperties": false
}
```

### Required parameters example

The required parameters plus the defaults that shape the output, as a REST body:

```json
{
  "params": {
    "model": "eleven-speech-to-text",
    "params": {
      "audioUrl": "https://cdn.example.com/input.mp3"
    }
  }
}
```

### Response

The body is the gateway's status envelope: the output is at `response.result`, next to the task id, its status and the credits charged. Text models return `text`.

```json
{
  "status": "success",
  "response": {
    "id": "task_abc123",
    "status": "COMPLETED",
    "result": {
      "text": "…generated text…",
      "model": "eleven-speech-to-text"
    }
  }
}
```

What `ai.generate()` / `ai.generateText()` resolve to (the envelope already unwrapped):

```json
{
  "text": "…generated text…",
  "model": "eleven-speech-to-text"
}
```

### Usage examples

#### TypeScript (SDK)

```typescript
import { createClient } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

const { text } = await ai.generateText('eleven-speech-to-text', {
  audioUrl: "https://cdn.example.com/input.mp3"
});

console.log(text);
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/v1/models/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "model": "eleven-speech-to-text",
    "params": {
      "audioUrl": "https://cdn.example.com/input.mp3"
    }
  }
}'
```

#### CLI

```bash
gen-ai login  # once per machine
gen-ai models info eleven-speech-to-text  # this model's parameters
gen-ai pricing eleven-speech-to-text  # quote before spending credits
gen-ai generate -m eleven-speech-to-text
```

## Compatibility API (vendor parameters)

Alongside the unified API, the `elevenlabs/v1/speech-to-text` workflow takes ElevenLabs's own parameters exactly as the vendor defines them — nothing renamed or reshaped. It is the shortest path onto Picsart for request bodies already written against the vendor; the trade is that a request is written for one vendor, and the result comes back in the vendor's own shape. Same authentication.

- **Endpoint**: `POST https://api.picsart.com/workflows/elevenlabs/v1/speech-to-text/execute` (sync) · `POST …/submit` + `GET …/{taskId}/result` (async)
- **SDK**: `ai.apis.run('elevenlabs/v1/speech-to-text', params, { mode })` — params forwarded verbatim

### Vendor parameters

| Parameter | Type | Required | Default | Details |
| --- | --- | --- | --- | --- |
| `audio_url` | `string` | yes | — | URL of the audio or video file to transcribe · e.g. `https://cdn.example.com/audio/input.mp3` |
| `model_id` | `string` | no | `scribe_v2` | The transcription model to use · Options: `scribe_v2` |
| `language_code` | `string` | no | — | ISO 639-1 or 639-3 language code. Omit to let the model detect the language · e.g. `en` |
| `diarize` | `boolean` | no | — | Annotate which speaker is talking in each word |
| `num_speakers` | `number` | no | — | How many speakers are in the audio. Omit to let the model decide · 1–32 |
| `timestamps_granularity` | `string` | no | — | Granularity of the returned timestamps · Options: `word`, `character` |
| `tag_audio_events` | `boolean` | no | — | Tag non-speech events such as (laughter) in the transcript |
| `temperature` | `number` | no | — | Sampling temperature. Higher values transcribe more freely · 0–2 |
| `seed` | `number` | no | — | Seed for deterministic transcription · 0–2147483647 |

### Example request body

```json
{
  "params": {
    "audio_url": "https://cdn.example.com/audio/input.mp3"
  }
}
```

### Usage examples

#### TypeScript (`ai.apis.run`)

```typescript
import { createClient, ApiRunMode } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

// Calls the 'elevenlabs/v1/speech-to-text' workflow directly — params are sent as-is.
const { result, usage } = await ai.apis.run('elevenlabs/v1/speech-to-text', {
  audio_url: "https://cdn.example.com/audio/input.mp3"
}, {
  mode: ApiRunMode.SYNC,
});

console.log(result); // workflow-specific output
console.log(usage?.credits); // amount charged, in $
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/elevenlabs/v1/speech-to-text/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "audio_url": "https://cdn.example.com/audio/input.mp3"
  }
}'
```

### Response

Over HTTP the vendor-shaped result arrives inside the gateway envelope at `response.result`:

```json
{
  "status": "success",
  "response": {
    "id": "wf_abc123",
    "status": "COMPLETED",
    "result": {
      "text": "…",
      "language_code": "…",
      "language_probability": 0,
      "words": [
        {
          "text": "…",
          "type": "…",
          "start": 0,
          "end": 0,
          "speaker_id": "wf_abc123",
          "characters": []
        }
      ],
      "audio_duration_secs": 0,
      "transcription_id": "wf_abc123"
    }
  }
}
```

`ai.apis.run()` unwraps that envelope and resolves to `{ result, usage }`:

```json
{
  "result": {
    "text": "…",
    "language_code": "…",
    "language_probability": 0,
    "words": [
      {
        "text": "…",
        "type": "…",
        "start": 0,
        "end": 0,
        "speaker_id": "wf_abc123",
        "characters": [
          {}
        ]
      }
    ],
    "audio_duration_secs": 0,
    "transcription_id": "wf_abc123"
  }
}
```

## Additional resources

- Model page: https://picsart.com/api-platform/models/eleven-speech-to-text
- Try it: https://picsart.com/api-platform/models/eleven-speech-to-text/playground
- SDK: https://picsart.com/api-platform/models/eleven-speech-to-text/sdk
- REST API (unified): https://picsart.com/api-platform/models/eleven-speech-to-text/api
- Compatibility API (vendor parameters): https://picsart.com/api-platform/models/eleven-speech-to-text/advanced
- Pricing: https://picsart.com/api-platform/models/eleven-speech-to-text/pricing
- This document: https://picsart.com/api-platform/models/eleven-speech-to-text/llms.txt
- All models: https://picsart.com/api-platform/models
- Docs — quickstart https://picsart.com/api-platform/docs/quickstart, authentication https://picsart.com/api-platform/docs/authentication, SDK https://picsart.com/api-platform/docs/sdk, REST https://picsart.com/api-platform/docs/api-reference, CLI https://picsart.com/api-platform/docs/cli, MCP https://picsart.com/api-platform/docs/mcp
- CLI reference: https://picsart.github.io/picsart-mcp-cli-docs/guide/introduction