コアコンセプト
このページでは、プラットフォームを支える基本的なアイデアとパターンを紹介します。これらのコンセプトを理解することで、APIを最大限に活用し、3Dプリンティングワークフローのための堅牢な連携を構築することができます。
APIベースルート
外部API呼び出しを行う場合は、https://api.quote3d.com/v2/... へ直接リクエストを送信してください（例：GET https://api.quote3d.com/v2/user）。
ソフトウェア内で、https://api.quote3d.com をAPIホスト/ベースURLとして設定し、/v2/user、/v2/file、/v2/quotes などのv2パスを呼び出してください。
1. 認証とセキュリティ
すべてのAPIエンドポイントは、Quote3D APIトークンを使用した認証が必要です。外部呼び出しには、https://api.quote3d.com/v2 ベースルートを使用してください。Authorization: Bearer <token> または X-API-Token として送信してください。Quote3Dダッシュボードからトークンを生成し、機密を保持してください。
リマインダー：APIトークンを安全に保管してください。公開したり、バージョン管理システムにコミットしたりしないでください。
2. アカウント管理
専用のエンドポイントを通じて、アカウント、アップロード、および使用状況統計を管理します:
GET /v2/userアカウントの詳細を取得GET /v2/user/uploadsアカウントにアップロードしたファイルを、最新のものから古いものの順にリスト表示します。GET /v2/quota見積もりとストレージの使用量を含む、現在の割り当て制限を取得GET /v2/usageエンドポイント統計、材料の使用量、および時間ベースのトレンドを含む、詳細な使用状況分析を取得
3. ファイル管理
3Dモデルファイル（STL、3MF、OBJ形式）のアップロード、ダウンロード、および管理：
- 新しいファイルをパブリックアップロードルートでアップロードするための、一時的なupload_idを取得します。:
GET /v2/file/upload-id- 新しいファイルをパブリックアップロードルートでアップロードするための、一時的なupload_idを取得します。 - このルートは認証を必要としません。クライアント側で使用して、ファイルをストレージに直接アップロードできます。:
POST /v2/file/public/{upload_id}- このルートは認証を必要としません。クライアント側で使用して、ファイルをストレージに直接アップロードできます。パブリックアップロードルートを使用すると、大きなファイルをバックエンドサーバーにルーティングする必要がなくなります。これにより、APIトークンが公開されるのを防ぎ、サーバーの負荷を軽減できます。
- サーバー側からファイルをアップロードします（認証が必要です。バックエンドからアップロードしたい場合に利用します）。:
POST /v2/file— サーバー側からファイルをアップロードします（認証が必要です。バックエンドからアップロードしたい場合に利用します）。 - file_idを使用してファイルをダウンロードします。:
GET /v2/file/{file_id}— file_idを使用してファイルをダウンロードします。 - 不要になったファイルを削除します。:
DELETE /v2/file/{file_id}— 不要になったファイルを削除します。
4. 部品情報と技術分析
モデルが印刷可能かどうかを確認し、部品寸法と高度なテクニカルメトリクスを取得します:
POST /v2/printability/{file_id}インスタント分析 – 見積もりを生成する前に、寸法、体積、表面積、幾何学的整合性（オープンエッジ/非多様体）を確認します。
Quote3Dは単なる寸法確認に留まりません。モデルの多様体（manifold）としての整合性を分析し、3Dプリントにおいて重要な定着リスクを評価します。これらのメトリクスは、PrintabilityとQuoteの両方のレスポンスで提供されます。
5. 見積もり操作
3Dプリントの見積もりを即座に生成し、見積もり履歴を管理します。
- 3Dモデルの非同期見積もり計算を開始します。ジョブIDを返します。ジョブエンドポイントを使用して、完了した結果を取得してください。:
POST /v2/file/quote/{file_id}— 3Dモデルの非同期見積もり計算を開始します。ジョブIDを返します。ジョブエンドポイントを使用して、完了した結果を取得してください。 - 別の非同期見積もりエンドポイントです。ステータスを確認し、完了した結果を取得するために使用できるジョブIDを返します。:
POST /v2/file/quote/{file_id}/async— 別の非同期見積もりエンドポイントです。ステータスを確認し、完了した結果を取得するために使用できるジョブIDを返します。 - 非同期見積もりジョブのステータスを確認します。進捗率と完了ステータスを返します。:
GET /v2/jobs/{job_id}— 非同期見積もりジョブのステータスを確認します。進捗率と完了ステータスを返します。 - ページネーションをサポートして、すべての見積もり履歴を取得します。:
GET /v2/quotes— ページネーションをサポートして、すべての見積もり履歴を取得します。 - 特定の見積もりの詳細情報を取得します。:
GET /v2/quotes/{quote_id}— 特定の見積もりの詳細情報を取得します。 - 履歴から見積もりを削除します。:
DELETE /v2/quotes/{quote_id}— 履歴から見積もりを削除します。
非同期ワークフロー: POST /v2/file/quote/{file_id} 最初にジョブIDを返します。完了したコンパクトな結果には GET /v2/jobs/{job_id} for the compact completed result, and GET /v2/quotes/{quote_id} for the stored detailed quote payload when available.
見積もりリクエストパラメータ
見積もりを生成する際に、リクエストボディでカスタム構成を指定できます。指定しないパラメータはすべて、ダッシュボードのスライスプロファイル設定から自動的に取得されます。これにより、他の設定をデフォルトのままにして、見積もりごとに特定の設定を上書きできます。
重要：リクエストにパラメータを提供しない場合、APIはダッシュボードのスライスプロファイル（プリンタープロファイル、マテリアルプロファイル、またはグローバル設定）の値を適用します。一貫した見積もりのために、ダッシュボードでデフォルトプロファイルをセットアップしてください。また、ダッシュボードの特定のプリンタープロファイルですべてのパラメータを設定し、リクエストで 'printer_id' を渡すだけで、それらの設定を個別に渡すことなく即座に適用できます。
設定の優先順位: V2 APIリクエストで送信された値は、選択されたユーザープロファイルの値よりも優先されます。まだ値が欠落しているフィールドは、ユーザー/グローバルデフォルトプロファイルにフォールバックします。
ルートパラメータ
| パラメータ | タイプ | 説明 |
|---|---|---|
| printer_id | string | オプション。デフォルトのプリンターの代わりに使うプリンターのID。 |
| quantity | number | オプション。製造する数量（デフォルト：1）。 |
数量とバッチ生産のロジック
当社のシステムは、指定された'quantity'に基づいて高度なパッキングアルゴリズムを使用します。
- FDMテクノロジー：パーツは、スペースがある限り、造形板（X軸とY軸）に並べて配置されます。
- SLAテクノロジー：パーツは、レジン槽（X軸とY軸）に並べて配置されます。
- SLSテクノロジー：パーツは、粉末ベッドの容量を最大限に活用するために、すべての軸（X、Y、Z）に積み重ねることができます。
この最適化されたパッキングにより、複数のパーツを1つのバッチに収めることができれば、予熱、冷却、レイヤー変更などの固定費は必要なバッチごとにのみ適用されます。これにより、大量注文に対して非常に現実的で費用対効果の高い価格設定が保証されます。
printer_config
プリンター構成パラメータ。すべてのフィールドはオプションであり、指定しない場合はデフォルトのプリンタープロファイルの値が使用されます。
| パラメータ | タイプ | 説明 |
|---|---|---|
| bed_size_x | number | Build volume X dimension (mm) |
| bed_size_y | number | Build volume Y dimension (mm) |
| bed_size_z | number | Build volume Z dimension (mm) |
| nozzle_diameter | number | Nozzle diameter (mm) |
| nozzle_count | number | Number of nozzles |
| print_speed | number | Default print speed (mm/s) |
| max_print_speed | number | Maximum print speed (mm/s) |
| travel_speed | number | Travel speed (mm/s) |
| first_layer_speed | number | First layer speed (mm/s) |
| layer_height | number | Layer height (mm) |
| min_layer_height | number | Minimum layer height (mm) |
| max_layer_height | number | Maximum layer height (mm) |
| perimeters | number | Number of perimeters/walls |
| top_solid_layers | number | Top solid layers count |
| bottom_solid_layers | number | Bottom solid layers count |
| min_wall_count | number | Minimum wall count |
| max_wall_count | number | Maximum wall count |
| fill_density | number | Infill density (0-100%) |
| infill_pattern | string | Infill pattern. Options: rectilinear, alignedrectilinear, zigzag, crosszag, lockedzag, line, grid, triangles, trihexagon, cubic, adaptivecubic, supportcubic, honeycomb, honeycomb3d, lateralhoneycomb, gyroid, monotonic, monotonicline, lightning. Default: rectilinear |
| support_material | boolean | Enable support material |
| support_overhang_angle | number | Support overhang angle (degrees) |
| support_density | number | Support density (0-100%) |
| acceleration_print | number | Print acceleration (mm/s²) |
| acceleration_travel | number | Travel acceleration (mm/s²) |
| acceleration_retraction | number | Retraction acceleration (mm/s²) |
| jerk_print | number | Print jerk (mm/s) |
| jerk_travel | number | Travel jerk (mm/s) |
| jerk_retraction | number | Retraction jerk (mm/s) |
| min_hotend_temp | number | Minimum hotend temperature (°C) |
| max_hotend_temp | number | Maximum hotend temperature (°C) |
| min_bed_temp | number | Minimum bed temperature (°C) |
| max_bed_temp | number | Maximum bed temperature (°C) |
| hourly_cost | number | Machine hourly cost |
| SLA専用 | ||
| sla_exposure_time | number | SLA: レイヤーごとの露光時間 (秒) |
| sla_bottom_exposure_time | number | SLA: ベースライン露光時間 (秒) |
| sla_bottom_layer_count | number | SLA: ボトムレイヤーの数 |
| sla_lift_distance | number | SLA: リフト距離 (mm) |
| sla_lift_speed | number | SLA: リフト速度 (mm/s) |
| sla_retract_speed | number | SLA: リトラクト速度 (mm/s) |
| sla_cleaning_cost | number | SLA：プリントごとの固定洗浄費用（IPA、消耗品） |
| SLS 専用 | ||
| sls_laser_speed | number | SLS: レーザー速度 (mm/s) |
| sls_hatch_spacing | number | SLS: ハッチ間隔 (mm) |
| sls_layer_thickness | number | SLS: レイヤー厚 (mm) |
| sls_layer_recoat_time | number | SLS: レイヤー再コーティング時間 (秒) |
| sls_preheat_time | number | SLS: 予熱時間 (秒) |
| sls_cooling_time | number | SLS: 冷却時間 (秒) |
| sla_light_off_delay | number | SLA: Light-off delay for each layer (seconds). |
| sla_transition_layer_count | number | SLA: Number of transition layers. |
| sla_drain_holes | array | SLA: Drainage holes configuration to prevent suction cups. |
| sls_bb_multiplier | number | SLS Bounding Box cost multiplier. |
| max_volumetric_flow | number | Maximum volumetric flow rate in mm³/s. |
material_config
マテリアル構成パラメータ。すべてのフィールドはオプションであり、指定しない場合はデフォルトのマテリアルプロファイルの値が使用されます。
マテリアルプロファイル統合：filament_typeパラメータは、ダッシュボードのマテリアルプロファイルにあるマテリアル名と一致する必要があります。filament_type（例："PLA"、"ABS"、"PETG"）を指定すると、APIは密度、温度、リトラクション設定、価格を含む、そのマテリアルプロファイルからすべてのプロパティを自動的にロードします。
価格の正確性：正確なコスト計算のためには、マテリアルプロファイルでprice_per_kgとprice_per_gramの両方を設定してください。APIはこれらの値を使用して、プリントに使用される実際のフィラメント重量に基づいて材料コストを計算します。これらの値がプロファイルに設定されていない場合は、APIリクエストで上書きできます。
例：ダッシュボードにprice_per_kg：20.0とprice_per_gram：0.02の"PLA"マテリアルプロファイルがある場合、リクエストで{"filament_type": "PLA"}を送信するだけで、すべての価格が自動的に計算されます。
| パラメータ | タイプ | 説明 |
|---|---|---|
| filament_type | string | Filament type (PLA, ABS, PETG, etc.) |
| color | string | オプション：色の名前（例：'白'、'黒'、'#FFFFFF'）。注：SLA / SLSテクノロジーの場合、色は'post_processing'が'painted'に設定されている場合にのみ適用されます。 |
| density | number | Material density (g/cm³) |
| diameter | number | Filament diameter (mm) |
| powder_bulk_density | number | SLS: Bulk density of loose powder in g/cm³. Used for reusable powder and refresh calculations. |
| temperature | number | Print temperature (°C) |
| print_temp_min | number | Minimum print temperature (°C) |
| print_temp_max | number | Maximum print temperature (°C) |
| bed_temperature | number | Bed temperature (°C) |
| bed_temp_min | number | Minimum bed temperature (°C) |
| bed_temp_max | number | Maximum bed temperature (°C) |
| fan_speed | number | Fan speed (0-100%) |
| min_fan_speed | number | Minimum fan speed (0-100%) |
| retraction_distance | number | Retraction distance (mm) |
| retraction_speed | number | Retraction speed (mm/s) |
| price_per_kg | number | Price per kilogram |
| price_per_gram | number | Price per gram |
| support_cost_multiplier | number | Support material cost multiplier |
| sls_refresh_factor | number | SLS Powder Refresh cost factor (e.g. 1.2). |
| max_volumetric_flow | number | Material specific volumetric flow limit in mm³/s. |
| min_layer_time | number | Minimum layer time in seconds for cooling. |
quote_config
見積価格の構成パラメータ。すべてのフィールドはオプションであり、指定しない場合はデフォルトのグローバル設定の値が使用されます。通貨はデフォルトでダッシュボードの設定になります（例：'USD'、'TRY'、'EUR'）。
| パラメータ | タイプ | 説明 |
|---|---|---|
| currency | string | Currency code (USD, TRY, EUR, GBP, JPY, CNY, RUB). Defaults to your dashboard preference. |
| tax_rate | number | Tax rate percentage (0-100) |
| fixed_fee | number | Fixed fee per quote |
| energy_cost_per_kwh | number | Energy cost per kWh |
| hollowing | string | SLA/レジン: 'solid' (ソリッド), '2mm' または '3mm' (デフォルト: 'solid') |
| post_processing | string | SLA/SLS: 'standard' (標準), 'sanding' (サンディング), 'painting' (塗装), または 'painted' (塗装済み) (デフォルト: 'standard') |
| enable_batch_system | boolean | Enable/disable batch calculation system (default: true) |
| material_wastage_factor | number | Factor for calculating material wastage (e.g. 1.10 for 10% wastage). |
ヒント: 見積もりは自動的にアカウントに保存され、APIの履歴エンドポイントからいつでも確認できます。
6. プリンターと見積もりプロファイル
正確な見積もりを得るために、プリンターの設定と価格を設定します。APIリクエストでパラメータを指定しない場合に自動的に使用されるデフォルトプロファイルは、ダッシュボードのスライスプロファイルセクションで管理できます。
プロファイルタイプ
- プリンタープロファイル - ベッドサイズ、ノズル径、印刷速度、レイヤー高さ、加速度、ジャーク、温度など、実際のプリンターに一致するようにプリンター設定を構成します。これをダッシュボードでデフォルトプロファイルとして設定すると、特定のパラメータを上書きしない限り、すべての見積もりリクエストに使用されます。
- マテリアルプロファイル - 使用する各マテリアルの材料特性（フィラメントタイプ、密度、直径、温度、ファン速度、リトラクション設定、価格）を設定します。APIは、リクエストで指定したfilament_typeに一致するマテリアルプロファイルを自動的に使用します。
- グローバル設定 - 税率、固定料金、エネルギーコスト、デフォルトの通貨など、グローバルな見積もり設定を構成します。これらの設定は、リクエストで上書きされない限り、すべての見積もりに適用されます。
ベストプラクティス：デフォルトプロファイルはダッシュボードのスライスプロファイルセクションで設定してください。これにより、すべてのパラメータを指定せずに簡単な見積もりリクエストを作成でき、APIは構成されたデフォルトを自動的に使用します。必要に応じて、リクエストごとにパラメータを上書きすることもできます。
プロファイルのマージ方法
見積もりリクエストを行うと、APIは次の優先順位でリクエストパラメータとダッシュボードプロファイルをマージします。
- リクエストパラメータ - APIリクエストで明示的に提供する値が最優先されます
- ユーザープロファイル - ユーザー固有のプロファイルをデフォルトとして設定している場合、次にそれが使用されます
- グローバルプロファイル - ユーザープロファイルが存在しない場合、システムはグローバルデフォルトにフォールバックします
つまり、ダッシュボードプロファイルの設定を維持しながら、必要なパラメータ（例：layer_heightまたはfill_densityのみ）を上書きできます。
7. Webhooks
アカウントでイベントが発生したときにリアルタイム通知を受け取ります:
POST /v2/webhooks- 新しいWebhookエンドポイントを作成GET /v2/webhooks- すべてのWebhookをリスト表示GET /v2/webhooks/{webhook_id}- Webhookの詳細と配信統計を取得PUT /v2/webhooks/{webhook_id}- Webhook設定を更新DELETE /v2/webhooks/{webhook_id}- Webhookを削除
サポートされているイベント: quote.completed, quote.failed, job.status_changed, widget.added_to_cart, file.uploaded. Webhookには、セキュリティ検証のためのHMAC-SHA256署名が含まれています。
8. 分析とレポート
APIの使用状況と見積もり統計に関する分析情報をご覧ください。
GET /v2/analytics/quotes- 総見積もり数、平均価格、材料使用量の傾向など、包括的な見積もり統計を取得できます。GET /v2/analytics/popular- 最も人気のある材料とプリンター構成を確認できます。GET /v2/analytics/cost-trends- 日次、週次、または月次でグループ化して、経時的なコストトレンドを分析します。GET /v2/analytics/export- 見積もりと使用状況データをCSVまたはJSON形式でエクスポートします。
9. レート制限とクォータ
Quote3Dは、公平な利用とシステム安定性を確保するためにレート制限を使用しています。
- レート制限はAPIトークンごとに適用され、エンドポイントによって異なります
- レート制限の情報は、レスポンスヘッダーに含まれています。
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset - レート制限に達すると、Retry-Afterヘッダーとともに429 Too Many Requestsレスポンスが返されます。
- 見積もりとストレージの月間クォータは、お客様のサブスクリプションプランに基づいています
ベストプラクティス: APIに過負荷をかけないように、レート制限エラーを処理する際に指数バックオフを実装してください。
10. RESTful、バージョン管理されたAPI
- すべてのエンドポイントはバージョン管理されています (例: /v2/)
- 標準的なHTTPメソッドを使用します:
- スキーマとドキュメントについては、OpenAPI 3.1.0標準に準拠しています
- APIの変更履歴は次の場所で確認できます: