Dedicated Inference

General conventions

• Base URL: BASE_API_URL
• Path: /bff/v1/ddi/{orgIdentifier}/workspaces/{workspaceIdentifier}/{action}
• Method: All endpoints use POST.
• Service-specific headers: X-Region: <region> (defaults to hanoi-vn if region is empty or all)
• Common headers (apiClient): X-Org-Id, X-Workspace-Id, X-User-Id
• Body: Always wrapped in payload: { "payload": { ... } }. Actions with no parameters send {}.
• Response: { "data": <payload>, "meta": { trace_id, org_id, ws_id, region_code } }
• Stream actions use fetch directly (not axios) with Accept: text/event-stream, credentials: include.

Endpoints

Model catalog & HuggingFace

#	Action	Payload	Purpose
1	ddi.model-catalog-list	{ status: "active", query?, page?, page_size?, filters?: [{ column: "category_code", value }] }	List model catalog
2	ddi.model-catalog-category-list	— ({})	List categories
3	ddi.model-catalog-get	{ id }	Model catalog details
4	ddi.hf-model-search	{ query?, pipeline_tag?, library?, sort?, limit?, cursor? }	Search models on HuggingFace

Catalog for deploy form

#	Action	Payload	Purpose
5	ddi.catalog-deploy-tiers-list	—	List tiers
6	ddi.catalog-gpu-skus-list	—	List GPU SKUs
7	ddi.catalog-runtime-images-list	—	List runtime images (templates)
8	ddi.catalog-regions-list	—	List deploy regions

Endpoint

#	Action	Payload	Purpose
9	ddi.endpoint-create	{ body: IDeployEndpointPayloadBody }	Deploy endpoint
10	ddi.endpoint-list	{ page, size, sort_by ("created_at"), sort_order ("asc") }	List endpoints
11	ddi.endpoint-get	{ container_id }	Endpoint details
12	ddi.endpoint-start	{ container_id }	Start
13	ddi.endpoint-stop	{ container_id }	Stop
14	ddi.endpoint-restart	{ container_id }	Restart (also used for "retry")
15	ddi.endpoint-delete	{ container_id }	Delete
16	ddi.endpoint-logs	{ container_id }	Latest log snapshot (string[])
17	ddi.endpoint-logs-stream	{ container_id, container, follow: true, tail_lines }	Log stream (SSE)
18	ddi.endpoint-metrics-get	{ endpoint_id, from, to, step_seconds? }	Metric history
19	ddi.endpoint-healthsummary-get	{ endpoint_id, from?, to? }	Health summary

Gateway API key

#	Action	Payload	Purpose
20	ddi.gateway-api-key-list	{ endpoint_id }	List keys
21	ddi.gateway-api-key-create	{ endpoint_id, name, allowed_models[] }	Create key (sk-vgw-*); endpoint must be running
22	ddi.gateway-api-key-revoke	{ endpoint_id, api_key_id }	Revoke key

Playground

#	Action	Payload	Purpose
23	ddi.playground-completion-send	{ endpoint_id, system_prompt, messages[{role, content}], temperature, top_p, max_tokens, stream: false }	Chat completion (non-streaming)
24	ddi.playground-capabilities	{ endpoint_id }	Tasks supported by the endpoint
25	ddi.playground-invoke	{ endpoint_id, task, payload: {...} }	Run a task
26	ddi.playground-invoke-stream	{ endpoint_id, task, payload: {...} }	Run a task (stream, SSE)
27	ddi.playground-job-get	{ endpoint_id, generation_id }	Get async job status
28	ddi.playground-examples	{ page, page_size }	Example images for playground

Request body

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. The inner payload depends on the task — retrieve available tasks from ddi.playground-capabilities.

Responses

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	Same as catalog item + 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[] (raw log lines)
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 (masked), status, created_at, revoked_at }] }
ddi.gateway-api-key-create	{ api_key_id, key, name, created_at } (key is secret, shown only once)
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 or {code, message}), timings }
ddi.playground-examples	{ items: [{ id, image_url }], total, page, page_size }
start / stop / restart / delete / create / revoke	No response body used.

Enums

• Endpoint status: CREATING, RUNNING, STOPPED, PROCESSING, FAILED, DELETING, DELETED
• purpose: SERVICE
• ddi.endpoint-metrics-get.source: playground (metrics from playground), scrape (Prometheus from container)

Notes

• Log stream (ddi.endpoint-logs-stream): SSE; each batch { event: "log_lines" | "stream_ended", batch_seq, container_id, container, lines[] }.
• Playground stream (ddi.playground-invoke-stream): SSE; errors return JSON { detail | error | message }.
• scaleEndpoint and updateEndpointModel currently have no BFF (FE uses no-op).
• Serverless Inference docs: docs/serverless-inference/api-endpoints.md.

Error codes

Error format

On error, HTTP status ≠ 2xx and the body has the following shape:

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

• role_based: true — the error message depends on the caller's role (MANAGEMENT / WS_ADMIN / MEMBER) and params.quotaLevel.
• HTTP 401 — the client logs out.

Common error codes (billing / quota / gateway)

Code	Meaning
INSUFFICIENT_BALANCE	Insufficient credits (role-based). Role MANAGEMENT auto-opens the top-up modal.
INSUFFICIENT_PERMISSIONS	The caller does not have permission to perform this action.
EQ-RESOURCE-00001	Quota reached (role-based, per params.quotaLevel: Organization / Workspace / Service).
EQ-RESOURCE-SYSTEM-LIMIT	Resource quota reached (params.name).
BFF-CREATING-CONCURRENCY	Another resource is being created in this workspace/service.
route_not_found	Endpoint does not exist.
method_not_allowed	Wrong method. Only POST is accepted.
request_too_large	Body exceeds 64 KB.
invalid_token	Token is invalid or expired.
gateway_internal_error	Internal gateway error.
upstream_unavailable	Backend service is temporarily unavailable.
gateway_timeout	Backend service timed out.

Dedicated Inference error codes (DDI-*)

Code	Message
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.

note

DDI endpoints run on GPU Container and may also return GPU Container error codes.