Convilyn 使い方ガイド

APIキー

APIキーを使うと、別のアプリ — Ainalyn デスクトップアプリ、コマンドライン、ご自身の連携 — があなたの Convilyn アカウントで処理を実行できるようになります。キーは Web アプリの 設定 → API、または完全版の API コンソール で管理します。

APIキーの用途

キーは、あなたに代わって行われる呼び出しを認証します。これにより、ブラウザの外で Convilyn を利用できます。

  • Ainalyn デスクトップアプリ — キーを貼り付けてアプリをアカウントに接続します（Convilyn と Ainalyn を参照）。
  • コマンドライン — convilyn CLI は環境変数からキーを読み取ります。
  • ご自身の連携 — Convilyn API を呼び出すあらゆるスクリプトやサービス。

キーはあなたに代わって処理を実行するため、パスワードと同じように扱ってください。 それを持つ人は誰でも、あなたのクレジットを消費できます。

キーを作成する

  1. 設定 → API を開きます（先にサインインしてください）。
  2. キーを作成 を選び、後で識別できる名前を付けます — 例えば「My desktop」など。
  3. キーのスコープ (scopes) と、必要に応じて有効期限 (expiry) を選びます（いずれも後述）。デフォルトはフルアクセス・無期限で、個人用キーに適しています。
  4. 完全なキーをコピーします。キーは ck_ で始まり、一度だけ表示されます。二度と確認できなくなるため、安全な場所に保管してください。

スコープ

スコープはキーで実行できる操作を制限します。

  • 読み取り (Read) — 読み取り専用アクセス：ワークフローの一覧、ステータス確認、結果のダウンロード、使用状況の閲覧。
  • 書き込み (Write) — クレジットを消費するワークフローの実行。

新しいキーはデフォルトでフルアクセス（読み取り＋書き込み）です。レポート用や読み取り専用の自動化にしか使わないキーには 読み取り のみを選べます。クレジットを消費できないため、万一漏えいしても課金は発生しません。

有効期限

キーに任意の有効期限を設定できます。期限を過ぎると、キーは自動的に認証されなくなります。空欄のままにすると無期限のキーになります。

キーを使う

Authorization ヘッダーに Bearer トークンとしてキーを送ります。

curl https://convilyn.corenovus.com/api/v1/workflows/catalog \
  -H "Authorization: Bearer ck_your_key"

ck_your_key を、作成したキーに置き換えてください。Python SDK、convilyn CLI、REST API を含むプログラム向けの全機能については、開発者向けドキュメントを参照してください。

キーを管理する

設定 → API から次の操作ができます。

  • キーをローテーション — 新しいシークレットを発行し、その間も古いキーは短い猶予期間（24 時間）動作し続けるため、停止なしで新しいキーへ切り替えられます。猶予期間が過ぎると古いキーは自動的に無効になります。
  • 単一のキーを失効 — 直ちに動作しなくなり、元に戻せません。
  • すべて失効 — キーの漏えいが疑われる場合のインシデント対応用コントロールです。

使用状況を確認する

各キーのアクティビティが記録されるため、費用と状態を把握できます。

  • 使用状況 — キーごとのリクエスト数・エラー数・消費クレジット（プリセットまたはカスタム期間）。
  • リクエストログ — 最近の API 呼び出し（メソッド、エンドポイント、ステータス、所要時間、コスト）を確認。
  • レート制限 — 各エンドポイントカテゴリでキーごとに適用されるリクエスト上限。

プランと提供状況

API アクセスは Free を含むすべてのプランに含まれます。プラン間の違いはクレジットと上限のみで、機能に差はありません。キーで行うクラウド呼び出しは、Web アプリと同じクレジット残高から消費されます。

Webhook

HTTPS エンドポイントを登録すると、ジョブ完了時に Convilyn がそこへ POST するため、ポーリングなしで結果に反応できます。

  • イベント — job.completed と job.failed。
  • 署名付き — 各配信には X-Convilyn-Signature ヘッダー（ペイロードの HMAC-SHA256）が付き、受信側が Convilyn からのものであることを検証できます。署名シークレットは hook 作成時に一度だけ表示されます。
  • 信頼性 — 配信に失敗すると指数バックオフで再試行し、繰り返し失敗するとデッドレターキューへ移します。配信はジョブから分離されているため、受信側が遅い・失敗してもジョブ本体が遅れることはありません。
  • テスト可能 — 本番で使う前に、hook へサンプルイベントを送ってエンドポイントを確認できます。

webhook の作成・管理（シークレットの表示、hook の有効化／無効化、テストイベントの送信）は API コンソール で行います。

API コンソール

管理機能をフルに使うには、スタンドアロンの API コンソール を利用してください — Convilyn アカウントでサインインします。上記のすべてを一か所にまとめ、より詳細なビューを提供します。

  • キー — 作成・ローテーション・失効、範囲と有効期限の設定。
  • 使用状況 — プリセットまたはカスタム期間の分析と、キーごとの内訳。
  • リクエストログ — 最近の API 呼び出しをページ送りで確認。
  • レート制限 — 各エンドポイントカテゴリのキーごとの上限。
  • Webhook — 送信 webhook の登録・テスト・管理。

Web アプリの 設定 → API は要点（キー、使用状況、デスクトップアプリ）のクイックビューで、コンソールは完全な体験です。

次に読むページ