← 開発者ガイド

Direct API integration

SDK を使わず、プレーンな HTTP で API を呼び出す — どの言語でも可能です。curl の例付きで、匿名と認証済みの正確なリクエスト/レスポンスの形を示します。

SDK なし、どの言語でも — これは API を直接呼び出すための正確な HTTP コントラクトです。 JavaScript を使っているなら、SDK がこれ（送信、ポーリング、エラー処理）をすべてラップしてくれます — プレーンな Web ページ統合 か、まだガイドを選んでいない場合は 統合パスを選ぶ を参照してください。

以下の各例には、この環境の実際の API ベース URL が示されています — そのままコピーして使って ください。その後に余分なパスセグメントを付け足さないでください。

2 つの異なるエンドポイント、2 つの認証モードを持つ 1 つの URL ではない

これらは2 つの別個の HTTP エンドポイントです。同じツールに対しても異なるレスポンスの形を 返します — どちらを前提に組んでいるかを把握しておいてください。

匿名 — POST /tools/:slug/run + GET /tools/runs/:ticketId

資格情報は不要です。ツールのスラッグを使います。レスポンスのフィールドは、公開 Tool Portal が 1 つの汎用レンダラーであらゆるツールを描画できるように、すべてのツールにわたって result.text （およびトークン/レイテンシのメタデータ）に正規化されます。IP ごとにレート制限されます。匿名経路の エラーテーブルについては下記の エラー を参照してください（特に、この経路は本物の ブラウザを必要とします — 403 に関する注記を参照）。

curl -X POST "https://api.quravin.com/tools/translate/run" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": { "text": "Hello", "target_language": "de" }
  }'

Response (202):

{ "ticket_id": "01J...ULID", "status": "QUEUED" }

ポーリング:

curl "https://api.quravin.com/tools/runs/01J...ULID"

完了後のレスポンス:

{
  "ticket_id": "01J...ULID",
  "status": "DONE",
  "mode": "pipeline",
  "pipeline_id": "translate-string",
  "result": { "text": "Hallo", "model": "gpt-4o-mini", "latency_ms": 812 },
  "created_at": "2026-07-10T12:00:00.000Z",
  "updated_at": "2026-07-10T12:00:02.000Z"
}

result.translation ではなく result.text である点に注意してください — 匿名経路は常に text に正規化します。

認証済み — POST /tickets + GET /tickets/:id

x-api-key: <key> または Authorization: Bearer <jwt> が必要です（どちらの入手方法についても 認証モードを選ぶ を参照してください）。pipeline_id を 使い、各パイプラインの生の、正規化されていない出力の形を返します — translate-string の場合、 それは text ではなく translation です。各ツールの pipeline_id と本来の出力フィールドに ついては ツールリファレンス を参照してください。

静的な API キーの場合:

curl -X POST "https://api.quravin.com/tickets" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "mode": "pipeline",
    "pipeline_id": "translate-string",
    "inputs": { "text": "Hello", "target_language": "de" }
  }'

session JWT の場合（認証モードを選ぶ の POST /auth/token で発行したもの）— ボディは同一で、ヘッダーのみが変わります:

curl -X POST "https://api.quravin.com/tickets" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-jwt>" \
  -d '{
    "mode": "pipeline",
    "pipeline_id": "translate-string",
    "inputs": { "text": "Hello", "target_language": "de" }
  }'

どちらも同じレスポンス（202）を返します:

{ "ticket_id": "01J...ULID", "status": "QUEUED" }

ポーリング — API キーの場合:

curl "https://api.quravin.com/tickets/01J...ULID" \
  -H "x-api-key: <your-api-key>"

ポーリング — session JWT の場合:

curl "https://api.quravin.com/tickets/01J...ULID" \
  -H "Authorization: Bearer <your-jwt>"

完了後のレスポンス:

{
  "ticket_id": "01J...ULID",
  "status": "DONE",
  "mode": "pipeline",
  "pipeline_id": "translate-string",
  "pipeline_version": "v3",
  "result": { "translation": "Hallo", "applied_terms": [] },
  "created_at": "2026-07-10T12:00:00.000Z",
  "updated_at": "2026-07-10T12:00:02.000Z"
}

失敗した場合:

{
  "ticket_id": "01J...ULID",
  "status": "FAILED",
  "mode": "pipeline",
  "pipeline_id": "translate-string",
  "error": "Ticket failed: <reason>",
  "created_at": "2026-07-10T12:00:00.000Z",
  "updated_at": "2026-07-10T12:00:02.000Z"
}

チケットのキャンセル — DELETE /tickets/:id

キャンセルをリクエストします（cancel.flag を書き込むことで実現します）。自分の資格情報が 作成したチケットしかキャンセルできません — operator スコープを持つ API キーは任意のチケットを キャンセルできますが、JWT/webtoken 呼び出し元は自分自身のチケットのみです（それ以外は 403）。

curl -X DELETE "https://api.quravin.com/tickets/01J...ULID" \
  -H "x-api-key: <your-api-key>"

# or with a session JWT:
curl -X DELETE "https://api.quravin.com/tickets/01J...ULID" \
  -H "Authorization: Bearer <your-jwt>"

Response:

{ "ticket_id": "01J...ULID", "status": "CANCELED" }

キャンセルされたチケットに対する GET /tickets/:id のポーリングは、上記の DONE/FAILED と同じ形を返しますが、status: "CANCELED" になります。

自分のチケット一覧の取得 — GET /tickets

自分自身の identity にスコープされたチケットを返します — JWT/webtoken の呼び出し元は常に 自分自身のチケットを取得します。任意のユーザー/アプリのチケットを調べるために ?user= / ?app= を渡せるのは、operator スコープの API キーのみです。

curl "https://api.quravin.com/tickets?limit=20" \
  -H "Authorization: Bearer <your-jwt>"

Query parameters:

Response:

{ "tickets": [ { "ticket_id": "01J...ULID", "status": "DONE", "...": "..." } ] }

公開の「try it」ウィジェットから本番の統合へ移行する際に押さえておくべき重要な点： 出力のフィールド名が変わります — 匿名の result.text から、認証済みではパイプライン固有の フィールドになります。translate の場合、それは result.translation です。

エラー

どのエラーが返ってくるかはどう呼び出しているか によって決まります — 匿名呼び出しと認証済み 呼び出しでは検証方法が異なります。一方の経路のエラー挙動がもう一方にも当てはまると考えないでください。

匿名で呼び出す場合（API キーなし）

公開されているすべてのツールが対象で、IP ごとにレート制限されます。

Important: この経路では、呼び出しが受け付けられる前に inputs が各ツールのスキーマに照らして 検証されることはありません — 必須フィールドの欠落や無効な値があっても 400 にはなりません。代わりに 実行自体が失敗し、結果をポーリングした際にそれが分かります。API キーを取得したら、事前に検証を行う 下記の認証済み経路に切り替えてください。

API キーまたは session token で呼び出す場合

あなたがアクセス権を持つツールすべてが対象です。

資格情報の仕組みや 401/403/429 の認証判定についてさらに詳しくは、認証モードを選ぶ を参照してください。各ツールの入力、有効な値、出力の形に ついては、ツールリファレンス を参照してください。