API & Embed

Charafy APIで開発しよう

AIキャラクターとの会話、音声合成、ビデオアバター、リアルタイム音声チャットをあなたのアプリに統合。10のエンドポイント、1つのAPIキー。

認証

すべてのAPIリクエストにはx-api-keyヘッダーによるAPIキーが必要です。

すべてのリクエストヘッダーにAPIキーを含めてください：

x-api-key: YOUR_API_KEY

APIキーは開発者ダッシュボードで取得できます。秘密にしてください — クライアントサイドのコードに公開しないでください。

クレジット & 料金

Charafy APIはクレジットベースの料金モデルです。クレジットを購入して、すべてのエンドポイントで利用できます。1クレジット = $0.01。

エンドポイント別コスト

エンドポイント	クレジット	USD
POST`/v1/tts`	1/ 100文字（最小1）	$0.01
POST`/v1/conversation/token`audio-only / lite	5/ 分	$0.05
POST`/v1/conversation/token`video	8/ 分	$0.08
PUT`/v1/characters/:id/avatar`	8/ リクエスト	$0.08
POST`/v1/video`	6/ 秒	$0.06
POST`/v1/voice/clone`	100/ リクエスト	$1.00

クイックスタート

数分で開始できます。キャラクター一覧の取得、音声生成、ビデオ作成、リアルタイム会話の開始まで。

# 1. List your characters
curl https://charafy.com/api/v1/characters \
  -H "x-api-key: YOUR_API_KEY"

# 2. Generate speech from text
curl -X POST https://charafy.com/api/v1/tts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"character_id": "CHAR_ID", "text": "Hello!"}' \
  --output speech.mp3

# 3. Generate a talking-head video
curl -X POST https://charafy.com/api/v1/video \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"character_id": "CHAR_ID", "text": "Hello!"}'

# 4. Start a real-time conversation
curl -X POST https://charafy.com/api/v1/conversation/token \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"character_id": "CHAR_ID", "mode": "audio-only"}'

APIエンドポイント

Characters

GET/v1/characters

無料

認証ユーザーが所有するすべてのキャラクター一覧を返します。Embed URLやアバターの状態も含みます。

リクエスト

curl https://charafy.com/api/v1/characters \
  -H "x-api-key: YOUR_API_KEY"

レスポンス 200

{
  "characters": [
    {
      "character_id": "uuid",
      "name": "Sakura",
      "language": "ja",
      "voice_id": "uuid",
      "photo_url": "https://...",
      "embed_enabled": true,
      "avatar_type": "motion",
      "embed_url": "https://charafy.com/embed/uuid"
    }
  ]
}

POST/v1/characters

無料

新しいAIキャラクターを作成します。オプションでアバター生成も可能（39クレジット）。画像はbase64データURIまたは公開URLを指定。

リクエスト

curl -X POST https://charafy.com/api/v1/characters \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sakura",
    "image": "https://example.com/photo.jpg",
    "voice_id": "VOICE_UUID",
    "language": "ja",
    "avatar_type": "motion"
  }'

リクエストボディ

パラメータ	型		説明
name	string	必須	キャラクターの表示名（1〜100文字）
image	string	必須	Base64データURI (data:image/png;base64,...) または公開画像URL
voice_id	string (uuid)	必須	使用する声のUUID（GET /v1/voicesで取得）
language	"ja" \| "en"	任意	キャラクターの言語。デフォルト: "ja"
avatar_type	"sprite" \| "motion" \| "none"	任意	生成するアバタータイプ。デフォルト: "none"（アバターなし）。"motion"または"sprite"は39クレジット
system_prompt	string	任意	性格設定のカスタムシステムプロンプト（最大10,000文字）

レスポンス 200

{
  "character_id": "uuid",
  "embed_url": "https://charafy.com/embed/uuid",
  "avatars": {
    "sprite": false,
    "motion": true
  },
  "credits_used": 8,
  "credits_remaining": 992
}

PUT/v1/characters/:id/avatar

8 クレジット/ リクエスト

既存のキャラクターのアバターを生成または再生成します。キャラクターに写真が必要です。

リクエスト

curl -X PUT https://charafy.com/api/v1/characters/CHAR_ID/avatar \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"avatar_type": "motion"}'

リクエストボディ

パラメータ	型		説明
avatar_type	"sprite" \| "motion"	必須	"sprite"はアニメーションスプライトシート、"motion"はAI生成モーションビデオ

レスポンス 200

{
  "character_id": "uuid",
  "sprite_ready": false,
  "motion_ready": true,
  "credits_used": 8,
  "credits_remaining": 992
}

PUT/v1/characters/:id/embed

無料

キャラクターのEmbed設定を更新します。埋め込みの有効化/無効化、許可オリジンの設定、利用制限の設定が可能です。

リクエスト

curl -X PUT https://charafy.com/api/v1/characters/CHAR_ID/embed \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "embed_enabled": true,
    "allowed_origins": ["https://example.com"],
    "embed_session_limit_seconds": 300,
    "embed_daily_limit_seconds": 3600
  }'

リクエストボディ

パラメータ	型		説明
embed_enabled	boolean	任意	このキャラクターのEmbedを有効化または無効化
allowed_origins	string[]	任意	許可するhttps://オリジンの配列（最大20件）。空配列 = すべて許可
embed_session_limit_seconds	number	任意	Embedセッションあたりの最大秒数（60〜3600）
embed_daily_limit_seconds	number	任意	1日あたりのEmbed合計最大秒数（60〜86400）
embed_monthly_limit_seconds	number	任意	1ヶ月あたりのEmbed合計最大秒数（3600〜2592000）
embed_max_concurrent	number	任意	同時Embedセッションの最大数（1〜100）

レスポンス 200

{
  "character_id": "uuid",
  "embed_enabled": true,
  "allowed_origins": [
    "https://example.com"
  ],
  "embed_session_limit_seconds": 300,
  "embed_daily_limit_seconds": 3600,
  "embed_monthly_limit_seconds": null,
  "embed_max_concurrent": null,
  "embed_url": "https://charafy.com/embed/uuid"
}

Voice

GET/v1/voices

無料

ユーザーが利用可能なすべての声を返します。プリセット音声とユーザー作成のクローン音声を含みます。

リクエスト

curl https://charafy.com/api/v1/voices \
  -H "x-api-key: YOUR_API_KEY"

レスポンス 200

{
  "voices": [
    {
      "voice_id": "uuid",
      "name": "Gentle Female",
      "language": "ja",
      "is_preset": true,
      "sample_url": "https://..."
    }
  ]
}

POST/v1/voice/clone

100 クレジット/ リクエスト

音声ファイルから声をクローンします。音声（5〜30秒推奨、最大10MB）をmultipart/form-dataでアップロード。

リクエスト`multipart/form-data`

curl -X POST https://charafy.com/api/v1/voice/clone \
  -H "x-api-key: YOUR_API_KEY" \
  -F "audio=@voice-sample.mp3" \
  -F "name=My Voice" \
  -F "language=ja"

リクエストボディ

パラメータ	型		説明
audio	File	必須	音声ファイル（WAV、MP3、WebMなど）。最大10MB
name	string	必須	クローン音声の名前（1〜100文字）
language	"ja" \| "en"	任意	音声の言語。デフォルト: "ja"

レスポンス 200

{
  "voice_id": "uuid",
  "name": "My Voice",
  "sample_url": "https://...",
  "credits_used": 100,
  "credits_remaining": 900
}

Text-to-Speech

POST/v1/tts

1 クレジット/ 100文字（最小1）

キャラクターの声でテキストから音声を生成します。バイナリのaudio/mpegデータを返します。

リクエスト

curl -X POST https://charafy.com/api/v1/tts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"character_id": "CHAR_ID", "text": "Hello!"}' \
  --output speech.mp3

リクエストボディ

パラメータ	型		説明
character_id	string (uuid)	必須	使用するキャラクターのUUID
text	string	必須	音声に変換するテキスト（1〜5,000文字）

レスポンス 200

Binary audio data (audio/mpeg)

Video

POST/v1/video

6 クレジット/ 秒

トーキングヘッドビデオを生成します。ジョブIDを即時返却 — GET /v1/video/:idでステータスをポーリング。

リクエスト

curl -X POST https://charafy.com/api/v1/video \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "character_id": "CHAR_ID",
    "text": "Hello, world!"
  }'

リクエストボディ

パラメータ	型		説明
character_id	string (uuid)	必須	キャラクターのUUID（写真が必要）
text	string	必須	キャラクターが話すテキスト（1〜5,000文字）
avatar_type	"sprite" \| "motion"	任意	アバタータイプ。デフォルト: "motion"。"sprite"は未対応

レスポンス 200

{
  "video_id": "uuid",
  "status": "processing",
  "poll_url": "https://charafy.com/api/v1/video/uuid",
  "credits_used": 84,
  "credits_remaining": 916
}

GET/v1/video/:id

無料

ビデオ生成ジョブのステータスを確認します。statusが"completed"または"failed"になるまでポーリング。

リクエスト

curl https://charafy.com/api/v1/video/VIDEO_ID \
  -H "x-api-key: YOUR_API_KEY"

レスポンス 200

{
  "video_id": "uuid",
  "status": "completed",
  "output_url": "https://...",
  "created_at": "2025-01-01T00:00:00Z",
  "completed_at": "2025-01-01T00:01:00Z"
}

Conversation

POST/v1/conversation/token

5 クレジット/ 分（音声: 5, 映像: 8）

キャラクターとリアルタイム音声/ビデオ会話を開始するためのセッショントークンを取得します。返却されたトークンでWebRTC接続してください。

リクエスト

curl -X POST https://charafy.com/api/v1/conversation/token \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "character_id": "CHAR_ID",
    "mode": "audio-only"
  }'

リクエストボディ

パラメータ	型		説明
character_id	string (uuid)	必須	会話するキャラクターのUUID
mode	"video" \| "audio-only" \| "lite"	任意	会話モード。デフォルト: "video"。"audio-only"は音声のみ、"lite"はアニメーションスプライト

レスポンス 200

{
  "token": "eyJ...",
  "conversation_id": "uuid",
  "mode": "audio-only",
  "session_limit_seconds": 600,
  "expires_in": 3600,
  "credits_used": 50,
  "credits_remaining": 950,
  "billing": {
    "rate_credits_per_minute": 5,
    "prepaid_credits": 50,
    "note": "Unused credits are refunded when the session ends."
  }
}

Credits

GET/v1/credits

無料

現在のクレジット残高と直近の取引履歴（最新50件）を確認します。

リクエスト

curl https://charafy.com/api/v1/credits \
  -H "x-api-key: YOUR_API_KEY"

レスポンス 200

{
  "credits_remaining": 500,
  "transactions": [
    {
      "id": "uuid",
      "amount": 1000,
      "type": "purchase",
      "description": "Credit purchase",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

エラーハンドリング

すべてのエラーは"error"フィールドを含むJSONオブジェクトを返します。一般的なHTTPステータスコード：

ステータス	説明
400	Bad Request — パラメータが無効またはJSONが不正
401	Unauthorized — APIキーが未指定または無効
402	Payment Required — クレジット残高不足
403	Forbidden — リソース制限に到達（例：現在のプランのキャラクター上限）
404	Not Found — リソースが存在しないか、あなたの所有ではありません
429	Too Many Requests — レート制限超過。少し待ってからリトライしてください
500	Internal Server Error — サーバー側でエラーが発生しました
502	Bad Gateway — 上流サービス（音声/ビデオプロバイダー）のエラー

エラーレスポンス形式：

{ "error": "Error message describing what went wrong" }

Embed（埋め込み）

1行のiframeタグで、インタラクティブなAIキャラクターを任意のWebサイトに埋め込めます。キャラクター設定またはAPIでembedを有効化してください。

<iframe
  src="https://charafy.com/embed/YOUR_CHARACTER_ID"
  width="400"
  height="600"
  frameborder="0"
  allow="microphone"
></iframe>

キャラクターのembed_enabled=trueが必要です。許可するオリジンは開発者ダッシュボードで設定してください。

ウィジェット

1行のscriptタグで、フローティングチャットボタンを任意のWebサイトに追加できます。IntercomやCrispのように、AIキャラクターとの会話を簡単に組み込めます。

フローティングモード（デフォルト）

画面の角に丸いボタンが表示されます。クリックするとボタンの上にチャットパネルが開きます。

<script
  src="https://charafy.com/widget.js"
  data-character-id="YOUR_CHARACTER_ID"
></script>

フルスクリーンモード

ボタンをクリックすると、半透明の背景とともに中央にオーバーレイが表示されます。

<script
  src="https://charafy.com/widget.js"
  data-character-id="YOUR_CHARACTER_ID"
  data-mode="fullscreen"
  data-color="#8b5cf6"
  data-position="bottom-left"
></script>

設定オプション

属性	デフォルト	説明
data-character-id	（必須）	キャラクターUUID
data-mode	"floating"	"floating" または "fullscreen"
data-theme	-	iframeに ?theme= として渡されます
data-lang	-	"en" または "ja"
data-color	"#6366f1"	ボタンの背景色
data-position	"bottom-right"	"bottom-right" または "bottom-left"
data-embed-mode	-	"video"、"audio-only"、または "lite"

JavaScript API

CharafyWidget.open()   // Open the chat panel
CharafyWidget.close()  // Close the chat panel
CharafyWidget.destroy() // Remove widget entirely

注意事項

キャラクターの embed_enabled=true が必要です。
ウィジェットはShadow DOMでスタイルを隔離しています。サイトのCSSと競合しません。
モバイル（640px以下）では、フローティングパネルが自動的にほぼ全画面に拡大します。

開発を始めよう

アカウントを作成してAPIキーを取得し、AIキャラクターをあなたのアプリに統合しましょう。

無料で登録料金を見る

Charafy APIで開発しよう

認証

クレジット & 料金

エンドポイント別コスト

クイックスタート

APIエンドポイント

Characters

リクエスト

レスポンス 200

リクエスト

リクエストボディ

レスポンス 200

リクエスト

リクエストボディ

レスポンス 200

リクエスト

リクエストボディ

レスポンス 200

Voice

リクエスト

レスポンス 200

リクエストmultipart/form-data

リクエストボディ

レスポンス 200

Text-to-Speech

リクエスト

リクエストボディ

レスポンス 200

Video

リクエスト

リクエストボディ

レスポンス 200

リクエスト

レスポンス 200

Conversation

リクエスト

リクエストボディ

レスポンス 200

Credits

リクエスト

レスポンス 200

エラーハンドリング

Embed（埋め込み）

ウィジェット

フローティングモード（デフォルト）

フルスクリーンモード

設定オプション

JavaScript API

注意事項

開発を始めよう

リクエスト`multipart/form-data`