Skip to main content
API7.ai Logo
Version: Dev

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",
      "apis": {
        "responses": {}
      },
      "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 the selected endpoint path to this base.

The apis.responses declaration sends Responses requests to DigitalOcean's native endpoint on the same API base instead of translating them through Chat Completions.

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"

For a new gateway, use this complete resources file. For an existing gateway, merge the entries into its current file, preserving its other resources:

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"
    apis:
      responses: {}

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:

# AISIX_PROXY has no trailing slash or endpoint path
# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

Send a Responses request through the AISIX proxy:

curl -sS -X POST "$AISIX_PROXY/v1/responses" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "digitalocean-gpt-oss-prod",
    "input": "Say hello from DigitalOcean Gradient AI."
  }'

AISIX forwards openai-gpt-oss-120b to DigitalOcean's native Responses endpoint with the configured credential, then restores the AISIX alias in the response.

Use Native Messages Through Passthrough​

The provider key above already sends Responses requests to DigitalOcean's native endpoint. DigitalOcean also publishes a native Messages endpoint on the same API base. Messages remains translated unless you use the provider-native alternative below:

AISIX routeUpstream behavior
/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 without declaring the coupled surface. Send a DigitalOcean model ID supported by that endpoint. Count Tokens remains unavailable.

DigitalOcean accepts the x-api-key header that AISIX uses for native Messages, but it does not publish Count Tokens. Keep this integration on passthrough rather than declaring apis.messages, which represents both routes as one surface.

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. For the request shapes that record token usage, see Envelope Detection and Usage.

Endpoint Coverage​

RouteBehavior with a DigitalOcean catalog alias
/v1/chat/completionsSupported, including stream: true.
/v1/responsesSent to DigitalOcean's native Responses API because this guide declares apis.responses. Without the declaration, AISIX uses the chat-based Responses bridge.
/v1/messagesSupported through translation to chat completions. /v1/messages/count_tokens is unavailable because the configured provider key does not declare a native Messages surface.
/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: