OpenAPI 仕様

Nodaro OpenAPI 仕様は、Nodaro REST API のコア部分を機械可読な形式で記述した、OpenAPI 3.1 の仕様です。稼働中のサーバーが直接配信します。Go、Rust、Python など、OpenAPI のジェネレーターがある言語で型付きのクライアントを生成するために使うほか、OpenAPI を読み取れるどのツールでも API を確認できます。TypeScript と JavaScript では、SDK がそのまま使えるクライアントです。

仕様を取得する

curl -s https://app.nodaro.ai/v1/openapi.json -o nodaro-openapi.json

仕様は公開されているため、トークンは不要です。キャッシュされる期間は 5 分間です。セルフホスティング環境も、同じパス /v1/openapi.json でその環境自身の仕様を配信します。設定 › APIトークンのページにも、仕様へのリンクがあります。

仕様が対象とする範囲

この仕様は、API の厳選された一部です。すべてのルートではなく、自動化のコア部分を記述しています。対象は次のとおりです。

共有スキーマを 4 つ定義しています。WorkflowSummary、Job、JobStatus、NodeDescriptor です。サーバーは自身のルート定義から仕様を生成するため、正確な一覧は実際のファイルを確認してください。

利用する際に知っておくべき点がいくつかあります。

• セキュリティスキームは 1 つだけです。bearerAuth は、HTTP のベアラートークンです。仕様ではフォーマットを JWT としていますが、このスキームは個人用 API トークン、OAuth アクセストークン、セッションの JWT のいずれも受け付けます。認証を参照してください。
• サーバーは相対パスです。仕様のサーバーは / なので、クライアントを作成するときに、https://app.nodaro.ai のようなベース URL を設定してください。
• ノードの検出ルートは公開されています。仕様ではすべてのパスに bearerAuth の指定がありますが、GET /v1/nodes と GET /v1/nodes/{type} は、トークンなしでも応答します。
• 生成のフィールドはすべて記載されています。POST /v1/generate-image と POST /v1/generate-video には、connectedReferences、direction、subject を含む、リクエストボディ全体が記載されています。フィールドの内容については、ノードを参照してください。

クライアントを生成する

# Go
oapi-codegen -generate types,client -package nodaro https://app.nodaro.ai/v1/openapi.json

# Rust
openapi-generator generate -i https://app.nodaro.ai/v1/openapi.json -g rust -o nodaro-rs

# Python
openapi-generator generate -i https://app.nodaro.ai/v1/openapi.json -g python -o nodaro-py

その後、クライアントにベース URL を設定し、すべてのリクエストで Authorization: Bearer <token> を送信します。それ以外は、ほかのページで説明している内容と同じです。JSON 形式のボディ、エラーにある { "error": { "code", "message" } } の形式、そしてジョブでの結果のポーリングです。

仕様に含まれないエンドポイントを呼び出す

REST API は、仕様に記載がない部分でも、どの言語からでも使えます。ベアラートークンを送り、JSON を送信して JSON を受け取るだけです。

• どのノードも、同じルートです。POST /v1/{node-type} に、ノードの設定をボディとして送ると、仕様にある 2 つだけでなく、どのノードも実行できます。ノードのフィールドは、GET /v1/nodes/{type} の inputSchema と、ノードリファレンスのそのノードのページから確認できます。
• それ以外のエンドポイントは、このドキュメントの各ページで説明しています。ワークフローや実行から、アップロードやクレジットまでです。生成したクライアントの生のリクエストメソッドか、任意の HTTP ライブラリで呼び出してください。