TranscritorAi API

すべてのAPIエンドポイントと、その機能、ログインが必要かどうかを一覧表示します。同じデータは下記の自動生成された形式でも利用できます。

Swaggerで開く

ベースURLはこのサイト自体のアドレスです(同一オリジン。別のAPIドメインはありません)。

「ログインが必要」と表示されたエンドポイントには、Authorization: Bearer ヘッダーが必要です。トークンは POST /api/auth/login または POST /api/auth/registrar が返すものと同じです。API はサイトと同じアカウントを使うため、プラン、クレジット、履歴、ストレージは共有されます。

2段階認証のアカウント:POST /api/auth/login は requer_2fa: true と desafio(チャレンジ)を返します。チャレンジと6桁のコードを POST /api/auth/login/2fa に送るとトークンを受け取れます。サイトではセッションはHttpOnlyクッキーに保存され、スクリプト用のAPIは引き続き Authorization: Bearer を使います。

Contabilização: cada arquivo ou link custa 1 crédito, descontado no envio (primeiro da cota mensal do plano, depois do saldo avulso). Vídeo custa 1 crédito a cada 5 min, áudio a cada 10 min e PDF/DOCX/TXT a cada 100 páginas. Falhas e cancelamentos devolvem os créditos; "pular" um arquivo já processado e reprocessar uma falha não cobram. Consulte GET /api/usuarios/eu/capacidade antes de enviar.

開発者向けAPI(v1)

APIキーを使うと、お客様のシステムの中から文字起こしできます。キーは「マイアカウント」の「オプション」タブで作成します。呼び出しはアカウントのAPIプランのクレジット枠を使い、結果は「マイファイル」にも表示されます。

キーは Authorization: Bearer tr_live_... で送ります。/api/v1 でのみ有効です。サイトのログインはそこでは使えず、キーもほかのAPIでは使えません。

処理は非同期です。作成するとすぐに id と status: queued が返ります。進み具合は GET で確認するか、終了時にWebhookで受け取ります。テキストは result.text に入ります。

例:文字起こしを作成する

curl -X POST https://transcritorai.com/api/v1/transcriptions \
  -H "Authorization: Bearer tr_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"source": {"type": "url", "url": "https://exemplo.com/reuniao.mp4"}, "metadata": {"id": "123"}}'

# 202 Accepted
{"id": "...", "status": "queued", "metadata": {"id": "123"}, ...}

curl https://transcritorai.com/api/v1/transcriptions/ID -H "Authorization: Bearer tr_live_SUA_CHAVE"
# {"status": "completed", "result": {"text": "..."}, ...}

Webhookの通知には X-Transcritor-Signature: t=...,v1=... ヘッダーが付きます。これはシークレット(whsec_...、「マイアカウント」の「オプション」タブ)による t.本文 のHMAC-SHA256です。署名を確認し、t が古い通知は拒否してください。公開されたhttpsアドレスのみ使えます。システムが2xxを返さない場合は最大4回再試行します。その後は GET で確認してください。

Webhookの署名を確認する

import hashlib, hmac, time

def aviso_valido(segredo, cabecalho, corpo_bytes):
    partes = dict(p.split("=", 1) for p in cabecalho.split(","))
    esperado = hmac.new(segredo.encode(), partes["t"].encode() + b"." + corpo_bytes, hashlib.sha256).hexdigest()
    recente = abs(time.time() - int(partes["t"])) < 300
    return recente and hmac.compare_digest(esperado, partes["v1"])

毎分のリクエスト上限はプランによって決まり、1キーごとに適用されます(超えると Retry-After 付きの429)。クレジット枠を使い切ると 402 cota_esgotada が返ります。送信はアカウントごとに一度に1件です。409 envio_em_andamento が返ったら、数秒後にやり直してください。

APIのプラン

APIにはサイトとは別の専用の枠があります。クレジットはサイトと同じ単位(1ファイルにつき1クレジット、動画は5分ごと)で、毎月リセットされます。毎分のリクエスト上限は1キーごとです。APIでの用語集はStartupから使えます。

StartupとBusinessは、プラン(APIタブ)からMercado Pago経由のカードで、月額または年額(年額は月額の10か月分)でお申し込みいただけます。プランは決済が承認された後に有効になり、保存済みのカードで自動更新されます。更新が3日を超えて拒否された場合、アカウントはDeveloperに戻ります。解約は同じ画面でいつでもできます。Startupはコンプリート+APIコンボにも含まれます。Enterpriseはお問い合わせください。サポートまでご連絡ください。

ルート

  • POST /api/v1/transcriptions · POST /api/v1/transcriptions/upload: アドレス(JSON)またはファイル(multipart)から文字起こしを作成します。glossary_id、webhook_url、metadata を指定できます。
  • GET /api/v1/transcriptions/{id}: 状態(queued、processing、completed、failed、canceled)と、完了後は result.text のテキスト。
  • GET /api/v1/transcriptions: API経由で作成した文字起こしの一覧(ページ分割、テキストなし)。
  • DELETE /api/v1/transcriptions/{id}: 処理中ならキャンセルし、そのあと一覧から外します。テキストは「マイファイル」に残ります。
  • GET /api/v1/usage: プラン、月の上限、使用量、残り、追加クレジット、毎分の上限。
  • POST|GET /api/v1/webhooks · DELETE /api/v1/webhooks/{id} · GET /api/v1/webhooks/deliveries: 通知先アドレス(https)の登録と、配信履歴の確認。
  • GET|POST /api/v1/glossaries · GET|POST /api/v1/glossaries/{id}/terms: 用語集と用語の一括登録(1回で最大500件)。名前や専門用語を正しく認識させます。
  • POST|GET /api/v1/transcriptions/{id}/studio: APIからのスタジオモード:文字起こしのYouTubeチャプター(chapters)、ショーノート(show_notes)、フック(hooks)を、アカウント自身のAIキーで生成します。1キットにつきAPIクレジットを5消費し(同じエピソードの同月の他の成果物は追加なし)、Webhook(studio.completed と studio.failed)で通知します。GETで完成したキットを取得できます。