Загрузка файла

Запрос

Минимальный рабочий вызов: ключ, имя файла и сами байты. Полный список заголовков — в Формате запроса, необязательные параметры — в Query-параметрах.

curl -X POST "https://app.memoai.tech/api/v1/developer/transcriptions?language=ru" \
  -H "Authorization: Bearer mk_live_your_key_here" \
  -H 'Content-Disposition: attachment; filename="standup.mp3"' \
  --data-binary @standup.mp3

import httpx

with open("standup.mp3", "rb") as f:
    resp = httpx.post(
        "https://app.memoai.tech/api/v1/developer/transcriptions",
        params={"language": "ru"},
        headers={
            "Authorization": "Bearer mk_live_your_key_here",
            "Content-Disposition": 'attachment; filename="standup.mp3"',
        },
        content=f,        # стримится с диска — работает и для 2 ГБ
        timeout=httpx.Timeout(10, write=None),  # не обрывать долгую отправку
    )
resp.raise_for_status()
t = resp.json()
print(t["uuid"], t["status"])   # "3fa85f64-…" "queued"

import { openAsBlob } from "node:fs"; // Node 20+

const res = await fetch(
  "https://app.memoai.tech/api/v1/developer/transcriptions?language=ru",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer mk_live_your_key_here",
      "Content-Disposition": 'attachment; filename="standup.mp3"',
    },
    body: await openAsBlob("standup.mp3"), // стрим, Content-Length выставится сам
  },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const t = await res.json();
console.log(t.uuid, t.status); // "3fa85f64-…" "queued"

Ответ

201 Created — файл принят и поставлен в очередь. Расшифровка идет асинхронно.

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "queued",
  "reports": []
}

Статусы и опрос

Опрашивайте GET /transcriptions/{uuid} раз в 5–10 секунд до терминального статуса:

import time

while True:
    t = httpx.get(f"{BASE}/transcriptions/{uuid}", headers=HEADERS).json()
    if t["status"] in ("completed", "failed", "insufficient_balance"):
        break
    time.sleep(10)

Частые значения error_code при failed:

Формат запроса

Файл — это тело запроса. Без multipart-форм, без JSON-оберток, без протоколов чанков:

Query-параметры

Все необязательные:

Поддерживаемые языки

auto (по умолчанию — язык определяется по аудио) или один из:

en, es, ru, zh, hi, ar, pt, bn, fr, de, ja, ko, tr, it, vi, pl, uk, nl, id, th, fa, sv, cs, ro, el, hu, da, fi, no, sk, he, ms, bg, hr, sr, sl, lt, lv, et, ta, te, mr, ur, sw, ml, kn, gu, pa, my, ne, si, km, lo, az, kk, uz, ka, hy, sq, bs, mk, is, mn, tg, tk, tt, ca, eu, gl, cy, af, tl, jw, su, yo, ha, so, am, sn, mg, ln, mt, lb, oc, br, nn, fo, sd, ps, ht, mi, haw, yi, ba, be, as, bo, sa, la

Двухбуквенные коды ISO 639-1 (плюс haw и jw). Неподдерживаемое значение вернет 422.

Свои идентификаторы

Расшифровка почти всегда относится к чему-то в вашей системе: к сделке, к звонку, к заявке. Передайте свой идентификатор при загрузке — и получите его обратно везде, вместо того чтобы держать у себя таблицу «наш id ↔ ваш».

curl -X POST 'https://app.memoai.tech/api/v1/developer/transcriptions' \
  -H 'Authorization: Bearer mk_live_your_key_here' \
  -H 'Content-Disposition: attachment; filename="call.mp3"' \
  -H 'X-External-Id: deal-A-1043' \
  -H 'X-Metadata: {"crm":"bitrix24","manager_id":17,"queue":"sales"}' \
  --data-binary @call.mp3

Оба заголовка необязательны и независимы: можно передать только один.

Что можно передавать

Не подошедшее значение отклоняется при загрузке с кодом 422, а code в ответе говорит, что именно не так: external_id_too_long, metadata_too_deep, metadata_value_invalid и так далее. Молча обрезать или игнорировать мы ничего не будем.

Что приходит обратно

Оба поля есть в GET /transcriptions/{id} и в каждом элементе списка:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "external_id": "deal-A-1043",
  "metadata": { "crm": "bitrix24", "manager_id": 17, "queue": "sales" },
  "status": "completed"
}

У расшифровок, загруженных не через API, оба поля равны null — это не ошибка.

Поиск по своим идентификаторам

Наш id знать не нужно: список фильтруется по вашим значениям.

GET /transcriptions?external_id=deal-A-1043
GET /transcriptions?metadata.queue=sales

Сравнение точное, по одному ключу за раз; это не полнотекстовый поиск. Фильтры складываются с остальными — например, ?metadata.queue=sales&status=completed.

Один идентификатор на нескольких расшифровках

X-External-Id не обязан быть уникальным. Одна сделка обычно означает несколько звонков, и все они могут нести один и тот же deal-A-1043 — тогда ?external_id=deal-A-1043 вернёт их все.

Если нужно защититься от повторной загрузки одного и того же файла, для этого есть Idempotency-Key с окном 24 часа — см. Ретраи.

Назначение автора

По умолчанию расшифровка, загруженная через API, принадлежит тому, кто создал ключ. Для команды это почти всегда не то: интеграция с CRM или телефонией загружает звонки разных менеджеров, и каждый должен видеть свои звонки в разделе «Мои встречи», получать уведомление о готовности и попадать в отчеты по людям.

Передайте владельца в заголовке X-Author. Значение типизировано — <type>:<value>:

curl -X POST "https://app.memoai.tech/api/v1/developer/transcriptions?language=ru" \
  -H "Authorization: Bearer mk_live_your_key_here" \
  -H 'Content-Disposition: attachment; filename="call-1043.mp3"' \
  -H 'X-Author: email:ivanov@company.com' \
  -H 'X-External-Id: deal-A-1043' \
  --data-binary @call-1043.mp3

Что получает автор, а что остается за ключом:

• Расшифровка принадлежит автору: она в его списке, ему приходит уведомление о готовности, в отчетах по команде она считается его. Каждый ответ возвращает владельца как author: { id, email, name }.
• Права, лимиты и списание — ключа. Проект, к которому вы привязываете запись, должен быть доступен создателю ключа; минуты списываются с workspace как обычно.
• Автор не обязан состоять в проекте, к которому вы привязали запись. Он все равно ее увидит — она его, — а администратор добавит его в проект позже. Загрузка из-за этого не отклоняется, автоматизация продолжает работать.

Если автора найти не удалось, загрузка отклоняется с 422 author_not_member, и ничего не списывается — тихого перехода на создателя ключа нет: неверно приписанный звонок заметить труднее, чем упавший. Код один и тот же и для незнакомого нам email, и для человека вне вашего workspace. Пригласите его в workspace или загрузите без X-Author и назначьте автора позже.

Ретраи

Без предосторожностей повтор загрузки, ответ на которую вы не увидели (соединение оборвалось после последнего байта), создал бы вторую расшифровку и второе списание. Заголовок Idempotency-Key решает это:

• Передавайте уникальное значение на файл (UUID идеален) с каждой попыткой.
• Если файл уже принят под этим ключом, придет 200 с оригинальным uuid вместо дубля — без двойного списания, квоты не тронуты.
• Запрос с тем же ключом, который еще в полете, вернет 409 idempotency_conflict — подождите Retry-After и повторите.
• Добавляйте джиттер: спите случайную долю Retry-After, а не ровно указанное время. Если лимит поймали сразу много клиентов, одновременное пробуждение просто воссоздаст очередь.
• Запоминается только успех (на 24 часа); после неудачной попытки ключ свободен для повтора.

curl -X POST "https://app.memoai.tech/api/v1/developer/transcriptions" \
  -H "Authorization: Bearer mk_live_your_key_here" \
  -H 'Content-Disposition: attachment; filename="standup.mp3"' \
  -H "Idempotency-Key: 7f3a2b1c-9d4e-4f5a-8b6c-1d2e3f4a5b6c" \
  --data-binary @standup.mp3

Лимиты и списание

Анти-абьюз ограничители (суточные капы на workspace, лимит одновременных загрузок) выставлены сильно выше нормального использования — если получили 429 с upload_quota_exceeded, напишите в поддержку, поднимем.

Ошибки

Полный справочник и правила ретраев — в разделе Ошибки.