Dedicated Inference

共通規約

• Base URL: BASE_API_URL
• Path: /bff/v1/ddi/{orgIdentifier}/workspaces/{workspaceIdentifier}/{action}
• Method: すべてPOST。
• サービス固有ヘッダー: X-Region: <region> (regionが空またはallの場合、デフォルトhanoi-vn)
• 共通ヘッダー (apiClient): X-Org-Id、X-Workspace-Id、X-User-Id
• Body: 常にpayloadでラップ: { "payload": { ... } }。パラメータなしのactionは{}を送信。
• Response: { "data": <payload>, "meta": { trace_id, org_id, ws_id, region_code } }
• StreamアクションはaxiosではなくfetchをJで直接使用し、Accept: text/event-stream、credentials: includeを指定。

エンドポイント一覧

モデルカタログ & HuggingFace

#	Action	Payload	用途
1	ddi.model-catalog-list	{ status: "active", query?, page?, page_size?, filters?: [{ column: "category_code", value }] }	モデルカタログ一覧
2	ddi.model-catalog-category-list	— ({})	カテゴリ一覧
3	ddi.model-catalog-get	{ id }	モデルカタログ詳細
4	ddi.hf-model-search	{ query?, pipeline_tag?, library?, sort?, limit?, cursor? }	HuggingFaceモデル検索

デプロイフォーム用カタログ

#	Action	Payload	用途
5	ddi.catalog-deploy-tiers-list	—	ティア一覧
6	ddi.catalog-gpu-skus-list	—	GPU SKU一覧
7	ddi.catalog-runtime-images-list	—	ランタイムイメージ一覧（テンプレート）
8	ddi.catalog-regions-list	—	デプロイリージョン一覧

エンドポイント

#	Action	Payload	用途
9	ddi.endpoint-create	{ body: IDeployEndpointPayloadBody }	エンドポイントのデプロイ
10	ddi.endpoint-list	{ page, size, sort_by ("created_at"), sort_order ("asc") }	エンドポイント一覧
11	ddi.endpoint-get	{ container_id }	エンドポイント詳細
12	ddi.endpoint-start	{ container_id }	起動
13	ddi.endpoint-stop	{ container_id }	停止
14	ddi.endpoint-restart	{ container_id }	再起動（「retry」にも使用）
15	ddi.endpoint-delete	{ container_id }	削除
16	ddi.endpoint-logs	{ container_id }	最新ログスナップショット（string[]）
17	ddi.endpoint-logs-stream	{ container_id, container, follow: true, tail_lines }	ログストリーム（SSE）
18	ddi.endpoint-metrics-get	{ endpoint_id, from, to, step_seconds? }	メトリクス履歴
19	ddi.endpoint-healthsummary-get	{ endpoint_id, from?, to? }	ヘルスサマリー

ゲートウェイAPIキー

#	Action	Payload	用途
20	ddi.gateway-api-key-list	{ endpoint_id }	キー一覧
21	ddi.gateway-api-key-create	{ endpoint_id, name, allowed_models[] }	キー作成（sk-vgw-*）；エンドポイントがrunning状態であること
22	ddi.gateway-api-key-revoke	{ endpoint_id, api_key_id }	キーの失効

プレイグラウンド

#	Action	Payload	用途
23	ddi.playground-completion-send	{ endpoint_id, system_prompt, messages[{role, content}], temperature, top_p, max_tokens, stream: false }	チャット補完（非ストリーミング）
24	ddi.playground-capabilities	{ endpoint_id }	エンドポイントが対応するタスク
25	ddi.playground-invoke	{ endpoint_id, task, payload: {...} }	タスクの実行
26	ddi.playground-invoke-stream	{ endpoint_id, task, payload: {...} }	タスクのストリーム実行（SSE）
27	ddi.playground-job-get	{ endpoint_id, generation_id }	非同期ジョブステータス取得
28	ddi.playground-examples	{ page, page_size }	プレイグラウンド用サンプル画像

リクエストボディ

9. ddi.endpoint-create

{
  "payload": {
    "body": {
      "name": "my-endpoint",
      "instance_type": "H100",
      "container_group": "",
      "purpose": "SERVICE",
      "description": "",
      "resource": { "cpu": 0, "ram": 0, "gpu": 1, "vram": 0, "temp_disk": 0, "gpu_type": "H100" },
      "tags": { "is_ddi_container": true },
      "container_settings": [{
        "enable_ssh": false,
        "authorized_keys": [],
        "image_setting": { "image_url": "...", "image_tag": "latest", "image_user": "", "image_password": "", "fptcloud_official": true },
        "volume_settings": [{ "volume_type": "TEMP_DISK", "mount_path": "/data", "resource": {}, "tags": { "is_ddi_container": true } }],
        "advance_setting": {
          "http_ports": [{ "container_port": 8000 }],
          "tcp_ports": [],
          "container_envs": [{ "key": "HF_TOKEN", "value": "..." }],
          "startup_cmd": { "cmd": [], "args": [] },
          "healthchecks": []
        }
      }]
    }
  }
}

25 / 26. ddi.playground-invoke(-stream)

task ∈ chat, vision, embeddings, decision, t2i, iedit, i23d, t2s, t2m, t2v, asr, wm, v2v, icomp。内部payloadはタスクによって異なる — 利用可能なタスクはddi.playground-capabilitiesから取得。

レスポンス

Action	Response (data)
ddi.model-catalog-list	{ items: [{ id, hf_model_id, display_name, short_description, parameters_display, context_length_display, license, badge_code, sort_order, status_code, categories[], provider_name, from_price, image_url, created_at, updated_at }], total, page, page_size }
ddi.model-catalog-category-list	{ items: [{ code, display_name, sort_order, created_at }] }
ddi.model-catalog-get	カタログアイテムと同じ + benchmarks[], hardware_profiles[], cache_profiles[], custom_config, suggest_engine
ddi.hf-model-search	{ items: [{ id, author, hf_url, downloads, likes, pipeline_tag, library_name, tags[], gated (none|auto|manual), params, last_modified, created_at, deployable{status (compatible|incompatible|unverified), reason, runtime_hint (vllm|diffusers)} }], next_cursor, stale }
ddi.catalog-deploy-tiers-list	{ items: [{ id, name, gpuLabel, gpuOptionId, replicas, autoscale, concurrentUsers, tokensPerSecond, pricePerHour }] }
ddi.catalog-gpu-skus-list	{ items: [{ gpu_sku_code, display_name, gpu_model, vram_gb, gpus_per_node, regions[], status, hourly_price{amount_micros, currency, display}, max_gpus_per_request, flavor, resource, price{estimate, currency_code}, available }] }
ddi.catalog-runtime-images-list	{ items: [{ runtime_image_id, runtime_engine, image, tag, digest, status, default }] }
ddi.catalog-regions-list	{ items: [{ region_code, display_name, status }] }
ddi.endpoint-list	{ items: Endpoint[], total, page, size, sort_by, sort_order }; Endpoint: id, name, status, instance_type, purpose, container_group, tenant_id, endpoint_id, container_settings[{ image_setting, advance_setting{ startup_cmd, http_ports[{container_port, domain_name, name, status}], container_envs } }], billing_plan{billing_type, billing_level, cost_estimate, currency_code}, created_at, updated_at, created_by_email
ddi.endpoint-get	Endpoint + description, deleted, version, org_id, ws_id
ddi.endpoint-logs	string[]（生のログ行）
ddi.endpoint-metrics-get	{ points: [{ bucket_start, request_count, rpm, error_count, error_rate, prompt_tokens, completion_tokens, total_tokens, avg_latency_ms, avg_ttft_ms, ttft_p50/p95/p99_ms, latency_p50/p95/p99_ms, tokens_per_second }], available_from, summary{ request_count, throughput_per_sec, p99_latency_ms }, step_seconds, source (playground|scrape) }
ddi.endpoint-healthsummary-get	{ status, uptime_30d_pct, uptime_30d_tracked, last_check_at, auto_recoveries_30d, auto_recoveries_tracked, mttr_seconds_avg_30d, mttr_tracked, metrics_supported }
ddi.gateway-api-key-list	{ items: [{ id, name, key_prefix (マスク済み), status, created_at, revoked_at }] }
ddi.gateway-api-key-create	{ api_key_id, key, name, created_at } (keyはシークレット、一度だけ表示)
ddi.playground-completion-send	{ text, latencyMs, promptTokens, completionTokens, cost }
ddi.playground-capabilities	{ engine, models[], served_model, supported_tasks: [{ id, input (text|image|audio|video), output (text|image|audio|video|vector|3d), enabled, streamable, reason }] }
ddi.playground-job-get	{ id, status (queued|running|succeeded|failed|unknown), result{ url, format, bytes }, error (stringまたは{code, message}), timings }
ddi.playground-examples	{ items: [{ id, image_url }], total, page, page_size }
start / stop / restart / delete / create / revoke	レスポンスボディは使用しない。

列挙型 (Enum)

• エンドポイントstatus: CREATING、RUNNING、STOPPED、PROCESSING、FAILED、DELETING、DELETED
• purpose: SERVICE
• ddi.endpoint-metrics-get.source: playground (プレイグラウンドからのメトリクス)、scrape (コンテナのPrometheus)

注意事項

• ログストリーム (ddi.endpoint-logs-stream): SSE; 各バッチ { event: "log_lines" | "stream_ended", batch_seq, container_id, container, lines[] }。
• プレイグラウンドストリーム (ddi.playground-invoke-stream): SSE; エラーはJSON { detail | error | message } を返す。
• scaleEndpointとupdateEndpointModelは現在BFFなし（FEはno-op）。
• Serverless Inferenceドキュメント: docs/serverless-inference/api-endpoints.md。

エラーコード

エラー形式

エラー時、HTTPステータス ≠ 2xx でbodyは以下の形式:

{ "code": "SI-KEYS-00004", "message": "...", "params": { "field": "name" }, "role_based": false, "statusCode": 400 }

• role_based: true — 呼び出し元のロール（MANAGEMENT / WS_ADMIN / MEMBER）とparams.quotaLevelによってメッセージが異なる。
• HTTP 401 — クライアントはログアウトしてログインページにリダイレクトする。

共通エラーコード (billing / quota / gateway)

Code	意味
INSUFFICIENT_BALANCE	クレジット不足（role-based）。MANAGEMENTロールは自動でトップアップモーダルを開く。
INSUFFICIENT_PERMISSIONS	この操作を実行する権限がない。
EQ-RESOURCE-00001	クォータに達した（role-based、params.quotaLevelによる: Organization / Workspace / Service）。
EQ-RESOURCE-SYSTEM-LIMIT	リソースのクォータに達した（params.name）。
BFF-CREATING-CONCURRENCY	このワークスペース/サービスで別のリソースが作成中。完了後に再試行。
route_not_found	エンドポイントが存在しない。
method_not_allowed	メソッドが間違っている。POSTのみ使用可能。
request_too_large	ボディが64 KBを超えている。
invalid_token	トークンが無効または期限切れ。
gateway_internal_error	ゲートウェイ内部エラー。
upstream_unavailable	バックエンドサービスが一時的に利用不可。
gateway_timeout	バックエンドサービスがタイムアウト。

Dedicated Inference 固有エラーコード（DDI-*）

Code	メッセージ
DDI-AUTH-00001	Authentication required. Please sign in and try again.
DDI-AUTH-00002	You do not have permission to perform this action.
DDI-AUTH-00003	Re-authentication is required. Please sign in again to continue.
DDI-AUTH-00004	Internal authentication failed.
DDI-COMMON-00001	Too many requests. Please try again in {{retry_after}} seconds.
DDI-EXTERNAL-00001	The service is temporarily unavailable. Please try again later.
DDI-RESOURCE-00001	The requested resource was not found.
DDI-RESOURCE-00002	A conflict occurred with the current state of the resource. Please refresh and try again.
DDI-RESOURCE-00003	No access credential found for this endpoint. Please redeploy the endpoint.
DDI-RESOURCE-00004	The endpoint control token is outdated. Please redeploy the endpoint to re-sync.
DDI-RESOURCE-00005	The endpoint is not ready yet. Please wait a moment and try again.
DDI-SYSTEM-00001	The GPU Container service is not configured. Please contact support.
DDI-SYSTEM-00002	An unexpected error occurred. Please try again later.
DDI-VALIDATION-00001	The request is invalid. Please check your input and try again.

注記

DDIエンドポイントはGPU Container上で動作するため、GPU Containerのエラーコードが返される場合もあります。