# Create transcription (STT)

Source: https://cicora.ai/en/docs/audio-transcriptions

`POST /v1/audio/transcriptions` accepts JSON or `multipart/form-data` and returns JSON. Use a workspace API key in `Authorization: Bearer`.

## Upload a recording

Choose a model supporting `transcription` in the [Audio catalog](/en/docs/audio). The sample model accepts mono PCM WAV at 16 kHz; check the current profile before using other audio formats.

```bash
export CICORA_API_KEY="sk_..."
export AUDIO_MODEL="speechkit-stt-general"

curl --fail-with-body --silent --show-error \
  https://api.cicora.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $CICORA_API_KEY" \
  -F "model=$AUDIO_MODEL" \
  -F "file=@recording.wav;type=audio/wav" \
  -F "response_format=json" -o transcript.json
```

The default successful response contains `text`. Optional `usage` may be absent. `curl -F` sets the multipart boundary: do not set Content-Type manually.

## Send Base64 or a URL

JSON uses `input_audio` with exactly one source. For inline data, send canonical Base64 bytes without a `data:` prefix and specify `format`:

```javascript
import { readFile } from "node:fs/promises";

const response = await fetch("https://api.cicora.ai/v1/audio/transcriptions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CICORA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: process.env.AUDIO_MODEL,
    input_audio: {
      data: (await readFile("recording.wav")).toString("base64"),
      format: "wav",
    },
    response_format: "json",
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log((await response.json()).text);
```

Alternatively, provide a publicly reachable HTTP(S) URL. Replace the illustrative URL with your actual file URL:

```json
{
  "model": "speechkit-stt-general",
  "input_audio": {
    "url": "https://media.example.com/recording.wav",
    "format": "wav"
  },
  "response_format": "json"
}
```

The platform fetches and validates the file before recognition. Private/local network URLs and URLs containing credentials are not allowed. If `format` is omitted for a URL, it must be inferable from the path extension; specify it for signed or extensionless URLs. Do not send both `data` and `url`.

## Request fields

| Field                                     | Type                      | Behavior                                                                                                          |
| ----------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `model`                                   | string, required          | Public model ID supporting `transcription`                                                                        |
| `input_audio`                             | object, JSON only         | `data` + `format`, or `url` + optional `format`                                                                   |
| `file`                                    | binary, multipart only    | One audio or video file                                                                                           |
| `language`                                | string                    | Two-letter lowercase ISO-639-1 code, such as `en` or `ru`; omission requires automatic language support           |
| `response_format`                         | `json` or `verbose_json`  | Defaults to `json`                                                                                                |
| `timestamp_granularities`                 | array of `word`/`segment` | Used only with `verbose_json`; ignored with `json`                                                                |
| `diarize`                                 | boolean                   | Speaker labels; requires model support and `verbose_json`, which also enables word timestamps                     |
| `keyterms`                                | string array              | Recognition hints, only when supported; at most 1,000 terms of 1–100 characters, with possible lower model limits |
| `temperature`                             | number                    | Only within the selected model's published range                                                                  |
| `provider`, `session_id`, `user`, `trace` | objects or strings        | [Common Audio options](/en/docs/audio#compatibility-and-optional-features)                                        |

In multipart, use repeated `timestamp_granularities[]` fields for timestamps, `true`/`false` for `diarize`, and JSON strings for `provider` and `trace`. For keyterms, use a JSON array in one field: `-F 'keyterms=["Acme","SpeechKit"]'`. Repeated `keyterms[]` also works for short lists, but the request allows at most 32 text fields in total, plus one file; a JSON-array field avoids consuming one field per term. Do not send both array representations. Unsupported fields are rejected rather than silently forwarded.

## Timestamps and response

```bash
curl --fail-with-body --silent --show-error \
  https://api.cicora.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $CICORA_API_KEY" \
  -F "model=$AUDIO_MODEL" \
  -F "file=@recording.wav;type=audio/wav" \
  -F "response_format=verbose_json" \
  -F "timestamp_granularities[]=word" \
  -F "timestamp_granularities[]=segment" -o transcript.json
```

```json
{
  "text": "Hello world",
  "task": "transcribe",
  "duration": 2.4,
  "words": [
    {"word": "Hello", "start": 0.2, "end": 0.8},
    {"word": "world", "start": 0.9, "end": 1.5}
  ],
  "segments": [{"id": 0, "text": "Hello world", "start": 0.2, "end": 1.5}]
}
```

Times are seconds from the start of the audio. Additional fields such as `language`, confidence, speaker labels and entities appear only when returned by the selected model. Missing confidence is not zero confidence. Diarization identifies speakers, not their real-world identity.

## File and model limits

Multipart files and inline Base64 accept at most **25 MiB (26,214,400 bytes)** of source media. Base64 expands the JSON body; the limit applies to decoded bytes. URL imports accept at most **100 MiB (104,857,600 bytes)**. Model limits can be lower and also constrain duration, codec, sample rate and channels. The cabinet's direct upload flow has separate limits and does not increase the multipart or inline API limit.

Recognized format names are `wav`, `mp3`, `mp4`, `m4a`, `ogg`, `webm`, `flac`, `pcm`, `mov`, `mpeg` and `mpg`. This list describes input parsing, not universal model support. In particular, raw PCM lacks self-describing geometry and must pass media inspection; prefer WAV for PCM recordings.

Video is accepted when it contains a decodable audio track. The media validator extracts audio for recognition; visual content is not transcribed. For multipart video, send the actual file MIME type, for example `file=@recording.mp4;type=video/mp4`. The extracted audio must fit the selected model's profile. A silent or corrupt video is rejected.

## Troubleshooting


**The API rejects an audio file or parameters**


Check its real codec, sample rate, channel count and duration against the model's profile. Renaming an extension does not convert audio. Remove unsupported diarization, keyterms or temperature settings.


**Timestamps are missing**


Request verbose\_json and supported timestamp granularities. With json, only the compact transcript is requested; timestamps are ignored.


**A long request times out**


Keep the HTTP connection open for recognition. Check [Usage](/en/docs/usage-costs) before explicitly retrying: a timeout does not prove the supplier did no work.

## FAQ

### What is cicora.ai?

cicora.ai is a multi-model AI workspace and compatible API for chat, text, images, video, coding tools, and teams. Start with the [overview](/en.md), [documentation](/en/docs.md), or [model catalog](/en/models.md).

### How is usage billed?

Confirmed usage is charged in USD from the active workspace's prepaid balance. Use the live catalog for current model prices and the [usage guide](/en/docs/usage-costs.md) for settlement details.

### Which protocols and integrations are available?

Documentation covers OpenAI-compatible Chat Completions and Responses, Anthropic Messages, image interfaces, Claude Code, OpenCode, and Codex CLI. Compatibility does not imply support for every upstream parameter.

### Which sources are authoritative and current?

For model IDs, availability, capabilities, limits, and prices, use the [live catalog](/en/models.md). For API behavior, use the matching [documentation page](/en/docs.md). Never include API keys, private workspace data, or preview URLs in public documents.