API olarak Euphona motoru

1. Dosyayı oluştur ve bir yükleme hedefi al

curl -X POST https://api.euphonaai.com/v1/files \
  -H "Authorization: Bearer $EUPHONA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filename":"take-07.wav","bytes":58210044,"content_type":"audio/wav"}'

{
  "id": "file_8Kd2mQ...",
  "object": "file",
  "status": "awaiting_upload",
  "upload": { "protocol": "...", "url": "https://files.euphonaai.com/...", "expires_at": "..." }
}

2. Baytları bize değil, files. adresine gönder

# upload.protocol alanını oku, tek bir mekanizma varsayma. Devam ettirilebilir
# yükleme mekanizması, sözleşme içindeki bir uygulama tercihidir ve büyük
# bir sürüm değişikliği olmadan değişebilir; belgede değil de bir alanda
# olmasının nedeni tam olarak bu.

3. İşi izle

curl -N https://api.euphonaai.com/v1/jobs/job_4Rb.../events \
  -H "Authorization: Bearer $EUPHONA_API_KEY"

event: job.progress
data: {"status":"analyzing","stage":"analyze","progress":{"fraction":0.4}}

event: job.completed
data: {"status":"succeeded","result":{...},"metering":{"pool":"payg","charged_minutes":3.4}}

4. Sonucu işin kendisiyle doğrula

curl https://api.euphonaai.com/v1/jobs/job_4Rb... \
  -H "Authorization: Bearer $EUPHONA_API_KEY"

{"id":"job_4Rb...","status":"succeeded","result":{...},
 "metering":{"pool":"payg","charged_minutes":3.4}}

# İş kaynağı, durum makinesinin güncel gerçeğidir: bir akış ne gösterdiyse
# ya da neyi kaçırdıysa, harekete geçmeden önce onu yeniden oku. Kopan bir
# SSE bağlantısı Last-Event-ID ile yeniden bağlanır ve hiçbir şey kaybetmez.

Bir teslimatı doğrulamak (Node.js)

import { createHmac, timingSafeEqual } from "node:crypto";

// Gövdeyi tam geldiği gibi ilet: ayrıştırılıp yeniden serileştirilmiş JSON,
// imzalanan mesaj değildir.
export function verifyEuphonaSignature(rawBody, header, secret, now = Date.now() / 1000) {
  const parts = header.split(",").map((part) => part.trim().split("="));
  const t = Number(parts.find(([key]) => key === "t")?.[1]);
  const signatures = parts.filter(([key]) => key === "v1").map(([, value]) => value);
  if (!Number.isFinite(t) || Math.abs(now - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return signatures.some((value) => {
    const given = Buffer.from(value, "hex");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}