# AI Builder Space speech-to-text API (file transcription)

## Basics

- Base URL: `https://space.ai-builders.com/backend/v1`
- Auth: every request carries the HTTP header `Authorization: Bearer <your API key>` (keys look like `sk_...`). An invalid key returns 401 with the body `{"detail":{"code":"invalid_api_key","message":"Invalid API key."}}`.

## Recommended: Grok file transcription

`POST https://space.ai-builders.com/backend/v1/audio/grok-transcription`

The request body is `multipart/form-data`:

| Field | Required | Description |
|---|---|---|
| `audio_file` | yes | The audio file to upload. The format is inferred from the file extension. Supported: M4A/AAC, WAV, MP3, OGG/Opus, FLAC, MP4, MKV, WebM, raw PCM. |
| `language` | no | BCP-47 language hint, e.g. `en`. If omitted, the language is detected automatically. |
| `terms` | no | Comma-separated vocabulary list (names, jargon). At most 100 terms, each at most 50 characters. |
| `format` | no | Inverse text normalization; only takes effect when `language` is also set. |
| `diarize` | no | Speaker labels. |
| `simple` | no | When `true`, only `{"text": "..."}` is returned. The full result is returned by default. |

This endpoint does not accept a free-form prompt.

### Response

With `simple=true`:

```json
{"text": "So this afternoon, I went over the deployment with Jackson and Sorsa. I mean, the service is sitting on Coyab right now, ..."}
```

Default (full result):

```json
{
  "request_id": "b32116c2-...",
  "text": "So this afternoon, I went over the deployment with Jackson and Sorsa. ...",
  "detected_language": "en",
  "duration_seconds": 20.8,
  "words": [{"start": 0.08, "end": 0.3, "text": "So", "confidence": null, "speaker": null}],
  "segments": [{"start": 0.08, "end": 20.6, "text": "...", "speaker": null}],
  "billing": {"duration_seconds": 20.8, "duration_hours": 0.0058, "total_cost": 0.00058, "provider": "grok_stt"}
}
```

The transcript is in the `text` field.

### curl example

```bash
curl -s https://space.ai-builders.com/backend/v1/audio/grok-transcription \
  -H "Authorization: Bearer $AI_BUILDER_TOKEN" \
  -F audio_file=@memos/example.wav \
  -F language=en \
  -F simple=true
```

## The other one: OpenAI-compatible transcription

`POST https://space.ai-builders.com/backend/v1/audio/transcriptions`, compatible with OpenAI's transcriptions endpoint (multipart fields `file` and `model`). The transcript is in the `text` field of the returned JSON.