APIドキュメント
APIドキュメント
APIキーですべてのAI機能を呼び出し、従量課金、数行のコードで統合。
認証
すべてのAPIリクエストに Authorization ヘッダーの含める必要があります。
Authorization: Bearer sk-xxxxxxxxxxxxxxxxAPIキーはコンソールの「APIキー」ページで取得。1アカウントにつき1キー。リセットはコンソールから行え、リセット後の旧キーは即座に無効化されます。
タスク作成
POST
https://nsfwrouter.xyz/api/v1/tasks/create
AIタスクをGPUクラスタに送信して実行。タスクは非同期処理され、タスクIDが返却されます。照会APIまたはWebhookで結果を取得。
リクエストパラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| tool_id | int | はい | ツールID、ツールリストから取得 |
| params | object | はい | タスクパラメータ、JSONオブジェクト、フィールドはツールに依存 |
| webhook_url | string | いいえ | タスク完了時のコールバック通知URL |
| priority | int | いいえ | タスク優先度 1-10、デフォルト 5 |
| idempotency_key | string | いいえ | べき等キー、重複送信を防止 |
| execution_options | object | いいえ | 実行オプション、JSONオブジェクト |
リクエスト例
curl -X POST https://nsfwrouter.xyz/api/v1/tasks/create \
-H "Authorization: Bearer sk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"tool_id": 1,
"params": {
"image": "https://example.com/photo.jpg",
"prompt": "a beautiful landscape"
},
"webhook_url": "https://your-server.com/webhook"
}'レスポンス例
{
"code": 0,
"message": "success",
"data": {
"task": {
"id": 123,
"status": 0,
"consume_coins": 5
},
"message": "task_submitted"
}
}呼び出し前にアカウント残高を検証、残高不足の場合は insufficient_coins エラーを返します。タスク送信成功後、コインは即座に扣除されます。
タスク詳細照会
GET
https://nsfwrouter.xyz/api/v1/tasks/query
タスクIDでタスクの詳細とステータスを照会。タスク処理中はGPUクラスタの最新ステータスを同期取得、10秒以内の重複照会はデータベースのキャッシュ結果を返し、リモートリクエストを繰り返しません。
照会パラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| id | int | はい | タスクID |
レスポンス例
{
"code": 0,
"message": "success",
"data": {
"task": {
"id": 123,
"status": 1,
"task_output_json": [
{
"type": "image",
"url": "https://cdn.example.com/outputs/abc123.png",
"file_name": "abc123.png",
"file_size": 1024000,
"mime_type": "image/png",
"width": 1024,
"height": 1024
}
],
"consume_coins": 5,
"created_at": 1718200000,
"completed_at": 1718200015
}
}
}タスクステータス値
| status | 意味 |
|---|---|
| 0 | 処理中 |
| 1 | 完了 |
| -1 | キャンセル |
| -2 | 失敗 |
タスク一覧
GET
https://nsfwrouter.xyz/api/v1/tasks
現在のアカウントのタスク一覧をページネーション照会、ツール、ステータス、時間範囲での絞り込みに対応。
照会パラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|---|---|---|
| page | int | いいえ | ページ番号、デフォルト 1 |
| page_size | int | いいえ | ページサイズ、デフォルト 20、最大 50 |
| tool_id | int | いいえ | ツールで絞り込み |
| status | int | いいえ | ステータスで絞り込み（0/1/-1/-2） |
| days | int | いいえ | 照会期間（日）、デフォルト 30 |
レスポンス例
{
"code": 0,
"message": "success",
"data": {
"list": [
{
"id": 123,
"tool_id": 1,
"status": 1,
"task_output_json": [
{
"type": "image",
"url": "https://cdn.example.com/outputs/abc123.png",
"file_name": "abc123.png",
"file_size": 1024000,
"mime_type": "image/png",
"width": 1024,
"height": 1024
}
],
"error": null,
"consume_coins": 5,
"created_at": 1718200000,
"completed_at": 1718200015
},
{
"id": 122,
"tool_id": 3,
"status": 0,
"task_output_json": [],
"error": null,
"consume_coins": 10,
"created_at": 1718199000,
"completed_at": 0
}
],
"page": 1,
"page_size": 20
}
}task_output_json item フィールド説明
| フィールド | 型 | 説明 |
|---|---|---|
| type | string | 結果タイプ：image または video |
| url | string | 結果ファイルのCDN URL |
| file_name | string | ファイル名 |
| file_size | int | ファイルサイズ（バイト） |
| mime_type | string | MIMEタイプ、例：image/png、video/mp4 |
| width | int | 幅（ピクセル） |
| height | int | 高さ（ピクセル） |
アカウント残高
GET
https://nsfwrouter.xyz/api/v1/account/balance
現在のアカウントのコイン残高、総チャージ額、総消費額を照会。
レスポンス例
{
"code": 0,
"message": "success",
"data": {
"remain_coins": 5000,
"total_coins": 10000,
"used_coins": 5000
}
}Webhookコールバック
タスク作成時に webhook_url を指定すると、タスクの完了、失敗、キャンセル時にそのURLへPOSTリクエストが送信されます。リクエストボディはJSON形式です。
コールバックリクエストヘッダー
Content-Type: application/json
Accept: application/json
User-Agent: OpenAPI-Webhook/1.0コールバックリクエストボディ
{
"event": "task.finished",
"task": {
"id": 123,
"status": 1,
"task_output_json": [
{
"type": "image",
"url": "https://cdn.example.com/outputs/abc123.png",
"file_name": "abc123.png",
"file_size": 1024000,
"mime_type": "image/png",
"width": 1024,
"height": 1024
}
],
"consume_coins": 5,
"created_at": 1718200000,
"completed_at": 1718200015
}
}サーバーは受信成功を示すHTTP 2xxステータスコードを返す必要があります。非2xxレスポンスやタイムアウト（10秒）の場合、システムは自動リトライを最大5回まで実行、指数バックオフ戦略（60s → 120s → 240s → 480s → 960s）。
エラーコード
すべてのエラーレスポンスは統一フォーマット：{"code": エラーコード, "message": "エラー識別子", "data": {}}
| エラーコード | message | 説明 |
|---|---|---|
| 20001 | api_key_required | APIキーが指定されていません |
| 20001 | invalid_api_key | 無効なAPIキー |
| 20001 | ip_not_allowed | IPがホワイトリストにありません |
| 20001 | permission_denied | アクセス権限がありません |
| 30001 | tool_not_found | ツールが見つかりません |
| 30001 | task_not_found | タスクが見つかりません |
| 30001 | insufficient_coins | コイン残高不足 |
| 30001 | task_submit_failed | タスク送信失敗 |
| 30001 | task_query_failed | タスク照会失敗 |
| 30001 | task_already_exists | タスクは既に存在します（べき等ヒット） |
| 40001 | tool_id_required | tool_idパラメータが不足しています |
| 40001 | param_error | パラメータエラー |
| 40001 | webhook_url_invalid | webhook_urlの形式が不正です |
| 40001 | params_must_be_json_object_or_array | paramsはJSONオブジェクトまたは配列である必要があります |
| 40001 | execution_options_must_be_json_object_or_array | execution_optionsはJSONオブジェクトまたは配列である必要があります |
エラーコード範囲
| 範囲 | カテゴリ |
|---|---|
| 1xxxx | システムレベルエラー |
| 2xxxx | 認証エラー |
| 3xxxx | 業務ロジックエラー |
| 4xxxx | パラメータエラー |
| 5xxxx | 外部依存エラー |