Developer Documentation

Swiftly Public API Documentation

このドキュメントでは、Swiftlyが公開しているAPIの仕様を説明します。現在は、日本語テキストのモデレーションを行う Swiftly Safety Agent と、OpenJTalkを利用した音声合成を行う Swiftly OpenJTalk Engine を扱います。

Format HTTP JSON API / Audio Response

Audience Developers

Status Public API

Overview

Swiftly Public APIは、Swiftly本体で実際に利用している内部コンポーネントの一部を、外部の開発者からも利用できる形で公開したものです。 APIはシンプルなHTTPインターフェースとして提供され、テキスト判定、音声合成、リアルタイム再生向けPCM生成などを扱います。

このページは仕様確認を目的としたリファレンスです。マーケティングページではなく、実装時に必要なエンドポイント、リクエスト形式、レスポンス形式、制約事項を中心に記載しています。

注意: 公開APIはSwiftlyの運用に影響しない範囲で利用してください。また、Public APIにはレートリミットが設けられています。

API index

API	Base URL	Purpose	Response
Swiftly Safety Agent	`https://safety-api.swiftlybot.com`	日本語テキストの毒性判定、辞書モデレーション補助	`application/json`
Swiftly OpenJTalk Engine	`https://openjtalk-api.swiftlybot.com`	OpenJTalkによるWAV/PCM音声合成	`audio/wav` / `audio/L16` / `application/json`

Swiftly Safety Agent

Swiftly Safety Agentは、Swiftlyの辞書モデレーションで使用している日本語テキスト判定APIです。入力テキストに対して毒性スコアを算出し、設定されたしきい値に基づいて判定結果と推奨アクションを返します。

モデルには b4c0n/KAi-Toxicity-Filter を使用します。レスポンスには、リクエスト識別子、モデル情報、入力情報、判定結果、処理時間が含まれます。

Base URL

https://safety-api.swiftlybot.com

POST /v1/moderate

単一のテキストを判定します。辞書登録、ユーザー入力、短文メッセージなどの検査に利用できます。

Request body

Field	Type	Required	Description
`text`	`string`	Yes	検査対象の日本語テキスト。

Example request

curl

curl -X POST https://safety-api.swiftlybot.com/v1/moderate \
  -H "Content-Type: application/json" \
  -d '{"text":"検査したい日本語テキスト"}'

Example response

JSON

{
  "request_id": "7c9a8b8c-9c14-4b07-8f97-11b6a6d1f001",
  "model": {
    "name": "b4c0n/KAi-Toxicity-Filter",
    "revision": "latest"
  },
  "input": {
    "char_length": 14,
    "truncated": false
  },
  "result": {
    "toxic_score": 0.8731,
    "threshold": 0.75,
    "verdict": "toxic",
    "action": "block"
  },
  "timing": {
    "processing_time_ms": 18.4
  }
}

Response fields

Field	Type	Description
`request_id`	`string`	リクエストごとの識別子。ログ追跡や問い合わせ時の参照に利用できます。
`model.name`	`string`	判定に使用されたモデル名。
`input.char_length`	`number`	入力テキストの文字数。
`input.truncated`	`boolean`	入力がAPI側で切り詰められたかどうか。
`result.toxic_score`	`number`	毒性スコア。値が高いほど toxic と判定されやすくなります。
`result.threshold`	`number`	判定に使用されたしきい値。
`result.verdict`	`string`	判定結果。例: `toxic`
`result.action`	`string`	推奨アクション。例: `block`
`timing.processing_time_ms`	`number`	API側の処理時間。単位はミリ秒。

POST /v1/moderate/batch

複数のテキストをまとめて判定します。辞書候補の一括検査や、複数入力の事前フィルタリングに利用できます。

Request body

Field	Type	Required	Description
`items`	`array`	Yes	判定対象の配列。
`items[].id`	`string`	Yes	クライアント側で指定する任意の識別子。
`items[].text`	`string`	Yes	検査対象のテキスト。

Example request

curl

curl -X POST https://safety-api.swiftlybot.com/v1/moderate/batch \
  -H "Content-Type: application/json" \
  -d '{"items":[{"id":"1","text":"こんにちは"},{"id":"2","text":"検査対象"}]}'

OSS版をローカルで起動している場合は、Base URLを http://127.0.0.1:8000 に置き換えてください。

Swiftly OpenJTalk Engine

Swiftly OpenJTalk Engineは、Swiftlyの音声合成で利用しているOpenJTalkベースのAPIです。テキストを入力として受け取り、WAVまたはリアルタイム再生向けのPCMを返します。

PCM出力は signed 16-bit little-endian、48000Hz、mono で返されます。 Discord VCなど、低遅延で音声を扱う用途を想定しています。

Base URL

https://openjtalk-api.swiftlybot.com

Request model

/synthesis と /synthesis/pcm は同じJSONリクエストを受け取ります。

Field	Type	Default	Constraints	Description
`text`	`string`	-	1〜500文字	合成するテキスト。
`speaker`	`string`	`mei_normal`	`^[a-zA-Z0-9_-]{1,64}$`	使用する音声プリセットID。
`speed`	`number`	`1.0`	0.5〜2.0	読み上げ速度。

Default speakers

Speaker ID	Name
`mei_normal`	Mei Normal
`mei_happy`	Mei Happy
`mei_bashful`	Mei Bashful
`mei_angry`	Mei Angry
`mei_sad`	Mei Sad
`nitech_male`	Nitech Male

GET /health

OpenJTalkコマンド、辞書、音声ファイルが利用可能かを確認します。

Example response

JSON

{
  "ok": true
}

GET /speakers

利用可能な音声プリセットの一覧を返します。

Example request

curl

curl https://openjtalk-api.swiftlybot.com/speakers

Example response

JSON

{
  "speakers": [
    { "id": "mei_normal", "name": "Mei Normal" },
    { "id": "mei_happy", "name": "Mei Happy" },
    { "id": "mei_bashful", "name": "Mei Bashful" },
    { "id": "mei_angry", "name": "Mei Angry" },
    { "id": "mei_sad", "name": "Mei Sad" },
    { "id": "nitech_male", "name": "Nitech Male" }
  ]
}

POST /synthesis

テキストを音声合成し、WAVファイルとして返します。

Example request

curl

curl -X POST https://openjtalk-api.swiftlybot.com/synthesis \
  -H "Content-Type: application/json" \
  -d '{"text":"こんにちは、Swiftlyです。","speaker":"mei_normal","speed":1.0}' \
  --output swiftly.wav

Response

Item	Value
Content-Type	`audio/wav`
Cache Header	`X-TTS-Cache: hit` または `X-TTS-Cache: miss`

POST /synthesis/pcm

テキストを音声合成し、リアルタイム再生向けのPCMバイト列として返します。WAVヘッダーは含まれません。

Example request

curl

curl -X POST https://openjtalk-api.swiftlybot.com/synthesis/pcm \
  -H "Content-Type: application/json" \
  -d '{"text":"リアルタイム音声合成のテストです。","speaker":"mei_normal","speed":1.0}' \
  --output swiftly.pcm

Response headers

HTTP headers

Content-Type: audio/L16; rate=48000; channels=1
X-TTS-Cache: hit | miss
X-TTS-Backend: native | cli-fallback | cli
X-TTS-Audio-Format: pcm_s16le_48000_mono_v1
X-TTS-Sample-Rate: 48000
X-TTS-Channels: 1

PCM playback example

ffplay

ffplay -f s16le -ar 48000 -ac 1 swiftly.pcm

PCM format: s16le、48000Hz、mono。保存したPCMを再生・変換する場合は、フォーマットを明示してください。

Text normalization

Whitespace normalization OpenJTalk Engine

連続する空白は整理され、空行は除去されます。

Line joining OpenJTalk Engine

複数行のテキストは読み上げ向けに連結されます。必要に応じて句点が補われます。

Leading symbols OpenJTalk Engine

読み上げに適さない先頭記号は取り除かれます。記号のみの場合は代替テキストとして扱われます。

Operational Notes

Timeouts and retries

外部APIとして利用する場合、クライアント側でタイムアウトを設定してください。特に音声合成APIは入力内容やバックエンド状態によって処理時間が変化するため、アプリケーション側でリトライ、フォールバック、キューイングを設計することを推奨します。

Rate and load

公開APIは共有リソースです。短時間に大量のリクエストを送る用途では、OSS版または同等の実装を自前でホストしてください。

Compatibility

APIのレスポンスフィールドやヘッダーは、互換性に配慮しながら変更される可能性があります。実装では未知のフィールドを無視し、必要なフィールドのみを参照することを推奨します。

Recommended client behavior

Area	Recommendation
Timeout	短いテキスト判定でも、ネットワーク遅延を考慮してクライアント側タイムアウトを設定してください。
Retry	5xxまたは一時的な接続失敗に対しては指数バックオフを推奨します。
Validation	送信前に文字数、空文字、入力形式をクライアント側で検証してください。
Audio	PCMレスポンスはWAVではないため、再生時に `s16le` / `48000Hz` / `mono` を明示してください。