Get Started with StreamAI
To use StreamAI as the AI provider for Cribl AI, provision the AI Gateway for your Workspace, create a client key, and configure StreamAI as the custom AI provider. For an overview of how StreamAI works, see Learn About StreamAI.
Before You Begin
You need:
- A commercial Cribl.Cloud Workspace with StreamAI enabled. For availability details, see Availability. If StreamAI doesn’t appear in the Products menu on the top bar, StreamAI isn’t enabled for your Workspace.
- The Organization Admin, Organization Owner, Workspace Admin, or Workspace Owner role. These roles can provision and delete the gateway. To view client keys, you also need at least the Read Only role on the StreamAI Worker Group. To manage client keys, you need the Editor or Admin role. See Permissions.
Step 1: Provision the AI Gateway
Each Workspace has one AI Gateway. Provisioning creates it. If you provision again, StreamAI returns the existing gateway and doesn’t create a second one.
On the top bar, select Products, and then select StreamAI.
On the welcome page, select Get Started.
StreamAI displays Provisioning StreamAI. This may take up to 5 minutes. You can leave this page. When provisioning finishes, StreamAI opens the Overview page.
If you don’t have an administrator role, the welcome page doesn’t show Get Started. It shows Ask an administrator to enable StreamAI for this Workspace. Ask an administrator to enable StreamAI for your Workspace.
Without an administrator role, you can’t read the gateway’s status. StreamAI keeps showing the welcome page, even after an administrator provisions the gateway, and you never reach the Overview page. If you have a role on the StreamAI Worker Group, you can still use the Keys page. In the StreamAI navigation, select Keys. See StreamAI Keys.
Provision by Using the API
To provision the gateway with the API, send a POST request with an empty JSON object ({}) as the body to /products/stream-ai. The request is idempotent. To check progress, send a GET request to the same path every 15 to 30 seconds. The response has an items array. An empty array means that the gateway doesn’t exist. When it exists, the item’s status is provisioning, ready, or degraded.
curl --request POST \
--url "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/products/stream-ai" \
--header "Authorization: Bearer ${token}" \
--header "Content-Type: application/json" \
--data '{}'To learn how to get a token, see Authenticate with the Cribl API.
Step 2: Create a Client Key
Each client application uses its own key. To create a key:
In the StreamAI navigation, select Keys.
Select Add Key.
Fill in the modal:
Field Description Key ID Required. A name that identifies the key, such as my-app. The name appears in the Key column.Description Optional. Text that describes the key’s purpose. Tags Optional. Labels that help you group and find keys. Enter a tag and press Enter, or separate tags with commas. Expiration How long until the key expires: 30 days (the default), 90 days, or 1 year. Select Generate Key.
Copy the key, and store it somewhere safe.
Save the Key Now
StreamAI shows the key only once. StreamAI stores only a hashed copy, so you can’t retrieve the key later. If you lose it, revoke the key and create a new one.
Keep these limits in mind:
- A key expires 30 days after creation by default. Create a replacement key before the current key expires, because an expired key is rejected with a
401error. - Each Workspace can have up to 1,000 active keys. Beyond that limit, creating a key fails with a
409error. - Revoking a key is permanent. To revoke a key, open the Actions menu for the key on the Keys page, and select Revoke. A revoked key stays in the list, with a Revoked status, for up to 90 days. StreamAI also keeps at most 1,000 revoked and expired keys, and removes the oldest first. The Keys page also shows an expired key as Revoked.
Create a Key by Using the API
To create a key with the API, send a POST request to /system/ai-gateway/client-keys on the StreamAI base URL, /api/v1/m/stream-ai, with a name. This request uses API v1, which is the default, so the response has status 202 and the key is in items[0].key. To get the key as a top-level key property, with status 201, send the x-cribl-api-version: 2 header. See API Versions. This response is the only one that contains the key.
curl --request POST \
--url "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/m/stream-ai/system/ai-gateway/client-keys" \
--header "Authorization: Bearer ${token}" \
--header "Content-Type: application/json" \
--data '{"name": "my-app"}'The list of keys includes an enabled property. This property doesn’t reflect expiration, so an expired key still shows enabled: true. To check whether a key has expired, compare its expiresAt value with the current time. For all key operations, see StreamAI REST API.
Step 3: Use StreamAI as a Custom AI Provider for Cribl AI
In a Cribl.Cloud Workspace that has StreamAI, you can configure StreamAI as the custom AI provider for Cribl AI. Cribl AI then sends its requests through the gateway for your Workspace instead of the default Cribl-managed models.
To configure StreamAI as the provider:
- Create a client key for Cribl AI.
- Open the Workspace, then select Settings (⚙).
- Select AI Settings.
- In the AI Model Providers section, select Use Custom AI Provider.
- Select the StreamAI tile. The tile is available only after you provision the gateway. If you haven’t, an administrator sees the message Provision StreamAI and create a key to connect this provider and a Provision button, which opens StreamAI in a new tab and starts provisioning. Other users see a disabled tile with no message. After you select the tile, the wizard goes straight to the connection details step.
- In ID, enter a name for the provider.
- In API key, enter the key.
- Select Test and Save.
The wizard has the following differences from the other custom AI providers.
- Endpoint: StreamAI generates the gateway URL for your Workspace. You don’t enter it, and the wizard doesn’t show it.
- Models: The wizard has no model assignment step. You don’t assign models to the Fast, Balanced, and Deep tiers. Cribl AI sends every request to
cribl/auto, and the gateway picks a model for the tier that each feature uses. If a model is unavailable, the gateway falls back to the next available model. - API: Cribl AI sends its requests to the gateway over the Chat Completions API (
/v1/chat/completions). The gateway must have at least one model available forcribl/autoon that endpoint. - Connection test: The test sends one request for each tier. If StreamAI has no model available for a tier, the test fails for that tier. Try again later, and if the test keeps failing, contact Cribl Support. If any tier fails, the Test and Save button changes to Retry.
The StreamAI tile appears only in Workspaces where StreamAI is enabled. For the other steps and limits of custom AI providers, see Configure Custom AI Providers.
Find the Gateway URL
The gateway for your Workspace has this base URL:
https://stream-ai.<workspace>.<organization>.cribl.cloud/v1Replace <workspace> and <organization> with your Workspace ID and Organization ID, as they appear in your Workspace URL. The Workspace URL has the form https://<workspace>-<organization>.cribl.cloud. For example, for the Workspace URL https://main-acme-1dge5ds.cribl.cloud, the base URL is https://stream-ai.main.acme-1dge5ds.cribl.cloud/v1. The How to connect to StreamAI banner at the top of the Keys page shows the URL with these values filled in.
The gateway host is the part of the URL before /v1. The gateway accepts requests over HTTPS and requires TLS 1.2 or higher. To check that the gateway is running, send a GET request to /health on the gateway host. This endpoint doesn’t require a key, and it returns {"status":"OK"}.
curl https://stream-ai.<workspace>.<organization>.cribl.cloud/healthWhat to Expect
- Time limit: Each request has a time budget of 120 seconds. The budget covers reading the request body and any fallback to another model in auto mode. It works as an idle timeout. If the model provider sends nothing for the rest of the budget, the gateway returns a
504error. A response that keeps sending data isn’t cut off at 120 seconds. If the provider stalls after the gateway has sent the response headers, the gateway drops the connection instead of returning a504error. The client sees a response that’s cut off. If the gateway can’t reach the model provider, or can’t get credentials for it, the gateway returns a502error. When the model returns an error, the gateway relays it with its own status code. - Headers: The gateway forwards only the
Content-Type,Content-Encoding,Content-Length,Accept,anthropic-version, andanthropic-betaheaders to the model. It removes cookies and all other client headers. - Errors: For the errors that the gateway returns when it rejects a request, see Diagnose a Failed Request.
Delete the AI Gateway
To remove the gateway from your Workspace, send a DELETE request to /products/stream-ai. You need the Organization Admin, Organization Owner, Workspace Admin, or Workspace Owner role.
curl --request DELETE \
--url "https://${workspaceName}-${organizationId}.cribl.cloud/api/v1/products/stream-ai" \
--header "Authorization: Bearer ${token}"Deleting the gateway stops all client requests, but it doesn’t delete the Workspace’s client keys. If you provision StreamAI again, every key that you didn’t revoke, and that hasn’t expired, works again. To make sure that a key can’t be used again, revoke it before you delete the gateway.