Create Deployment

POSThttps://{organization}.blackbox.ai/dedicated/create-deployment

Provision a new dedicated GPU deployment of an open-source model.

Create a new dedicated deployment. Pick a model_name from GET /dedicated/templates and a gpu_type / gpu_count / region combination that the template lists as available.

Headers

Authorizationstringrequired

API Key of the form Bearer <api_key>. Any valid API key can create deployments; they are scoped to the caller's account.

Content-Typestringrequired

Must be set to application/json.

Request Body

model_namestringrequired

Template name to deploy. Must exactly match a name returned by GET /dedicated/templates.

Example: "openai/gpt-oss-20b"

flavor_namestringdefault: base

Flavor variant of the template (e.g. quantization or fine-tune). Must match one of the flavors[].name entries on the template. Defaults to "base".

gpu_typestringrequired

GPU SKU to run the deployment on. Must match one of the available_configurations.gpu_configurations[].gpu_type values for the chosen flavor.

Example: "gpu-h100-sxm"

gpu_countintegerrequired

Number of GPUs per replica. Must be listed as valid for the chosen gpu_type.

Range: 1 – 64.

regionstringrequired

Region to provision GPUs in. Must be listed under the chosen gpu_type configuration.

Example: "eu-north1"

descriptionstring

Free-form description for your own reference. Maximum 512 characters.

scalingobject

Autoscaling policy for the deployment.

Scaling Object

min_replicasinteger

Minimum number of replicas kept warm. Set to 0 to allow scale-to-zero when idle.

max_replicasinteger

Maximum number of replicas the deployment can scale up to.

Response

deployment_idstring

UUID identifying the deployment. Use this with /dedicated/edit and /dedicated/delete.

modelstring

Client-facing model id to pass in /chat/completions requests. Format: dedicated/<sanitized-slug>-<12char-suffix>.

Example: "dedicated/openai/gpt-oss-20b-Ab3xY9K1mN2p"

model_namestring

The template name the deployment was created from.

statusstring | null

Current lifecycle status (e.g. "provisioning", "running", "failed"). May be null immediately after creation.

scalingobject

The effective scaling policy (echoes the request, or defaults if omitted).

Scaling Object

min_replicasinteger

Minimum warm replicas.

max_replicasinteger

Maximum replicas.

descriptionstring | null

Description supplied at creation, or null if none was provided.

created_atstring

ISO 8601 timestamp of when the deployment was created.

updated_atstring

ISO 8601 timestamp of the last update to the deployment.

Request Example

curl -X POST https://{organization}.blackbox.ai/dedicated/create-deployment \
  -H "Authorization: Bearer $BLACKBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "openai/gpt-oss-20b",
    "flavor_name": "base",
    "gpu_type": "gpu-h100-sxm",
    "gpu_count": 1,
    "region": "eu-north1",
    "description": "Prod inference for docs assistant",
    "scaling": {
      "min_replicas": 1,
      "max_replicas": 4
    }
  }'

import os
import requests

response = requests.post(
    "https://{organization}.blackbox.ai/dedicated/create-deployment",
    headers={
        "Authorization": f"Bearer {os.environ['BLACKBOX_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model_name": "openai/gpt-oss-20b",
        "flavor_name": "base",
        "gpu_type": "gpu-h100-sxm",
        "gpu_count": 1,
        "region": "eu-north1",
        "description": "Prod inference for docs assistant",
        "scaling": {"min_replicas": 1, "max_replicas": 4},
    },
)

print(response.json())

const response = await fetch("https://{organization}.blackbox.ai/dedicated/create-deployment", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model_name: "openai/gpt-oss-20b",
    flavor_name: "base",
    gpu_type: "gpu-h100-sxm",
    gpu_count: 1,
    region: "eu-north1",
    description: "Prod inference for docs assistant",
    scaling: { min_replicas: 1, max_replicas: 4 },
  }),
});

const data = await response.json();
console.log(data);

Response Example

{
  "deployment_id": "9c8b7a6d-5e4f-3a2b-1c0d-ef1234567890",
  "model": "dedicated/openai/gpt-oss-20b-Ab3xY9K1mN2p",
  "model_name": "openai/gpt-oss-20b",
  "status": "provisioning",
  "scaling": {
    "min_replicas": 1,
    "max_replicas": 4
  },
  "description": "Prod inference for docs assistant",
  "created_at": "2026-07-10T14:22:05Z",
  "updated_at": "2026-07-10T14:22:05Z"
}

Error Codes

Status	Error	Description
400	`invalid_request`	Missing/invalid body, unknown `model_name`, or unsupported `gpu_type` / `gpu_count` / `region` combination for the template.
401	`unauthorized`	Missing or invalid API key.
429	`rate_limited`	Deployment-creation rate limit exceeded for the account. Retry with backoff.
502	`deployment_failed`	Provisioning failed downstream. The deployment record is rolled back; safe to retry.