Skip to main content
API7.ai Logo

DigitalOcean Gradient AI

DigitalOcean Gradient AI Serverless Inference provides hosted access to foundation models without requiring you to operate model-serving infrastructure. AISIX maps the upstream model IDs to stable aliases and controls who can use them.

Prerequisites​

Before starting, prepare the following:

  • One AISIX setup:
    • For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
    • For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
  • A Gradient AI model access key or a DigitalOcean personal access token that can call Serverless Inference.
  • Access to the selected DigitalOcean Inference model.
  • curl and jq.

Configure with AISIX Cloud​

Export the AISIX Cloud connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

DigitalOcean is a community catalog provider with an OpenAI-compatible inference API. AISIX connects through the openai adapter and authenticates upstream requests with a bearer token.

Create a Provider Key​

export DIGITALOCEAN_INFERENCE_KEY="YOUR_MODEL_ACCESS_KEY"

PROVIDER_KEY_ID=$(
  curl -sS -X POST "$AISIX_CP/provider_keys" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "digitalocean-prod",
      "provider": "digitalocean",
      "api_key": "'"${DIGITALOCEAN_INFERENCE_KEY}"'",
      "api_base": "https://inference.do-ai.run/v1",
      "allowed_environments": ["'"${ENV_ID}"'"]
    }' | jq -er '.provider_key.id'
)

echo "$PROVIDER_KEY_ID"

Use digitalocean as the catalog provider ID. AISIX derives the openai adapter; sending an explicit adapter on a catalog key returns a validation error.

The API base includes /v1. AISIX appends /chat/completions for chat requests.

Create a Model​

Create an alias for a model currently available from Gradient AI:

MODEL_ID=$(
  curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "digitalocean-gpt-oss-prod",
      "model_name": "openai-gpt-oss-120b",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

Use the DigitalOcean model ID, not the original publisher repository name. Confirm current availability in the model reference before creating another alias.

Create a Caller API Key​

AISIX_API_KEY=$(
  curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "digitalocean-caller",
      "allowed_models": ["'"${MODEL_ID}"'"]
    }' | jq -er '.plaintext'
)

echo "$AISIX_API_KEY"

Configure with the Open-Source AISIX Gateway​

Export the upstream credential and choose the caller API key that applications will send to the gateway:

export DIGITALOCEAN_INFERENCE_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

Create a complete declarative resources file for this provider:

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "digitalocean-prod"
    provider: "digitalocean"
    adapter: "openai"
    api_key: ${DIGITALOCEAN_INFERENCE_KEY}
    api_base: "https://inference.do-ai.run/v1"

models:
  - display_name: "digitalocean-gpt-oss-prod"
    provider: "digitalocean"
    model_name: "openai-gpt-oss-120b"
    provider_key: "digitalocean-prod"

api_keys:
  - display_name: "digitalocean-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "digitalocean-gpt-oss-prod"

If AISIX is installed locally, validate the file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands. After the resources load, prepare the shared verification request below:

export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection​

Export the AISIX gateway origin:

# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

Send a chat-completions request through the AISIX proxy:

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "digitalocean-gpt-oss-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from DigitalOcean Gradient AI."
      }
    ]
  }'

AISIX forwards openai-gpt-oss-120b to https://inference.do-ai.run/v1/chat/completions with the DigitalOcean credential.

Reach DigitalOcean-Native API Formats​

DigitalOcean publishes native Responses and Messages endpoints on the same API base. The catalog provider key in this guide still uses the openai adapter, so normalized AISIX routes do not automatically select those native upstream formats:

AISIX routeUpstream behavior
/v1/responses with a DigitalOcean aliasUses the AISIX Responses bridge over DigitalOcean chat completions. It does not call DigitalOcean's native /v1/responses route, and Responses-only fields without a chat equivalent are ignored.
/passthrough/digitalocean/responsesCalls DigitalOcean's native Responses route. Send the DigitalOcean model ID in model, not the AISIX alias.
/v1/messages with a DigitalOcean aliasTranslates the Anthropic-shaped caller request to DigitalOcean chat completions. It does not call DigitalOcean's native /v1/messages route.
/passthrough/digitalocean/messagesCalls DigitalOcean's native Messages route. Send a DigitalOcean model ID supported by that endpoint.

The /passthrough/digitalocean paths on this page assume a passthrough route claiming that prefix with https://inference.do-ai.run/v1 as its target_url; grant the route name on the caller key's allowed_routes. The paths omit /v1 because the route's target already includes it; a duplicated leading v1 segment is stripped either way. A passthrough route does not rewrite an AISIX alias. AISIX detects chat, completions, and Responses envelopes from each request and records supported usage fields. Requests without a recognized carrier field remain opaque: buffered responses record zero tokens, while opaque SSE can still record top-level supported usage fields.

Endpoint Coverage​

RouteBehavior with a DigitalOcean catalog alias
/v1/chat/completionsSupported, including stream: true.
/v1/responsesSupported through the chat-based Responses bridge, not DigitalOcean's native Responses API.
/v1/messagesSupported through translation to chat completions. /v1/messages/count_tokens is not available because it requires an Anthropic-backed model.
/v1/embeddingsSupported when the alias targets a DigitalOcean embedding model, such as qwen3-embedding-0.6b.
/v1/audio/speechThe request reaches DigitalOcean when the alias targets a text-to-speech model such as qwen3-tts-voicedesign, but the response is not OpenAI-compatible end to end. DigitalOcean wraps base64-encoded audio in a JSON data envelope, and AISIX relays that body without decoding it into binary audio. Use /passthrough/digitalocean/audio/speech and decode data[0].b64_json when the application supports DigitalOcean's native response contract.
/v1/audio/transcriptions and /v1/audio/translationsNot available. DigitalOcean does not publish these routes.
/v1/images/generationsRejected because the normalized AISIX route accepts only the openai provider value. Call the native route through /passthrough/digitalocean/images/generations with a compatible DigitalOcean model ID.
/v1/videosNot implemented for the digitalocean provider. Submit a DigitalOcean-native video job through /passthrough/digitalocean/videos, poll it through /passthrough/digitalocean/video/generations/{job_id}, and optionally download the completed MP4 through /passthrough/digitalocean/videos/{video_id}/content.
/v1/rerankRejected because the normalized AISIX route accepts only the openai, cohere, and jina provider values.
/passthrough/digitalocean/async-invokeCalls DigitalOcean's asynchronous endpoint for supported image, audio, and text-to-speech models. Use the provider-native request format.
/passthrough/digitalocean/modelsLists the model IDs accessible to the configured DigitalOcean credential.

See Provider Compatibility for the gateway-wide endpoint matrix.

Troubleshooting​

SymptomCheck
Upstream 401 or 403Confirm the credential has inference access. For a model access key, verify its model scope and any VPC restriction; VPC-restricted callers must use the VPC-local DNS resolver.
Upstream 404Keep /v1 in api_base and verify the DigitalOcean model ID.
Model not foundQuery DigitalOcean GET /v1/models with the same upstream credential and confirm that the model access key includes the selected model.
Provider key creation returns 400Use provider: "digitalocean" without adapter.

Next Steps​

You have now connected AISIX to DigitalOcean Gradient AI and verified the model alias. Continue with these guides: