Base¶

APIClient¶

class client.APIClient(credentials=None, project_id=None, space_id=None, verify=None, httpx_client=HttpClientConfig(timeout=Timeout(connect=10, read=1800, write=1800, pool=1800), limits=Limits(max_connections=10, max_keepalive_connections=10, keepalive_expiry=5)), async_httpx_client=HttpClientConfig(timeout=Timeout(connect=10, read=1800, write=1800, pool=1800), limits=Limits(max_connections=10, max_keepalive_connections=10, keepalive_expiry=5)), **kwargs)[source]¶

The main class of ibm_watsonx_ai. The very heart of the module. APIClient contains objects that manage the service reasources.

To explore how to use APIClient, refer to:

Setup - to check correct initialization of APIClient for a specific environment.
Core - to explore core properties of an APIClient object.

Parameters:

url (str) – URL of the service
credentials (Credentials) – credentials used to connect with the service
project_id (str, optional) – ID of the project that is used
space_id (str, optional) – ID of deployment space that is used
verify (bool, optional) – certificate verification flag, deprecated, use Credentials(verify=…) to set verify
httpx_client (httpx.Client, HttpClientConfig, optional) –
A customizable httpx.Client for ModelInference, Embeddings and methods related to the deployments management and scoring. The httpx.Client is used to improve performance across deployments, foundation models, and embeddings. This parameter accepts two types of input:
- A direct instance of httpx.Client()
- A set of parameters provided via the HttpClientConfig class
Example:
```
from ibm_watsonx_ai.utils.utils import HttpClientConfig

limits=httpx.Limits(
    max_connections=5
)
timeout = httpx.Timeout(7)
http_config = HttpClientConfig(timeout=timeout, limits=limits)
```
If not provided, a default instance of httpx.Client is created.

Note

If you need to adjust timeouts or limits, using HttpClientConfig is the recommended approach. When the proxies parameter is provided in credentials, httpx.Client will use these proxies. However, if you want to create a separate httpx.Client, all parameters must be provided by the user.
async_httpx_client (httpx.AsyncClient, HttpClientConfig, optional) –
A customizable httpx.AsyncClient for ModelInference. The httpx.AsyncClient is used to improve performance of foundation models inference. This parameter accepts two types of input:
- A direct instance of httpx.AsyncClient
- A set of parameters provided via the HttpClientConfig class
Example:
```
from ibm_watsonx_ai.utils.utils import HttpClientConfig

limits=httpx.Limits(
    max_connections=5
)
timeout = httpx.Timeout(7)
http_config = HttpClientConfig(timeout=timeout, limits=limits)
```
If not provided, a default instance of httpx.AsyncClient is created.

Note

If you need to adjust timeouts or limits, using HttpClientConfig is the recommended approach. When the proxies parameter is provided in credentials, httpx.Client will use these proxies. However, if you want to create a separate httpx.Client, all parameters must be provided by the user.

Example:

from ibm_watsonx_ai import APIClient, Credentials

credentials = Credentials(
    url = "<url>",
    api_key = IAM_API_KEY
)

client = APIClient(credentials, space_id="<space_id>")

client.models.list()
client.deployments.get_details()

client.set.default_project("<project_id>")

...

get_headers(content_type='application/json', include_user_agent=False)[source]¶

Get HTTP headers used during requests.

Parameters:

content_type – value for Content-Type header, defaults to application/json
include_user_agent – whether the result should include User-Agent header, defaults to False

Returns:

headers used during requests

Return type:

dict

set_headers(headers)[source]¶

Method which allows refresh/set new User Request Headers.

Parameters:: headers (dict) – User Request Headers

Examples

headers = {
    'Authorization': 'Bearer <USER AUTHORIZATION TOKEN>',
    'User-Agent': 'ibm-watsonx-ai/1.0.1 (lang=python; arch=x86_64; os=darwin; python.version=3.10.13)',
    'Content-Type': 'application/json'
}

client.set_headers(headers)

set_token(token)[source]¶

Method which allows refresh/set new User Authorization Token.

Note

Using this function will cause that token will not be automatically refreshed anymore, if password or apikey were passed. The user needs to take care of token refresh using set_token function from that point in time until they finish using the client instance.

Parameters:: token (str) – User Authorization Token

Examples

client.set_token("<USER AUTHORIZATION TOKEN>")

Credentials¶

class credentials.Credentials(*, url=None, api_key=None, name=None, iam_serviceid_crn=None, token=None, projects_token=None, username=None, password=None, instance_id=None, version=None, bedrock_url=None, platform_url=None, proxies=None, verify=None)[source]¶

This class encapsulate passed credentials and additional params.

Parameters:

url (str) – URL of the service
api_key (str, optional) – service API key used in API key authentication
name (str, optional) – service name used during space creation for a Cloud environment
iam_serviceid_crn (str, optional) – service CRN used during space creation for a Cloud environment
token (str, optional) – service token, used in token authentication
projects_token (str, optional) – service projects token used in token authentication
username (str, optional) – username, used in username/password or username/api_key authentication, applicable for ICP only
password (str, optional) – password, used in username/password authentication, applicable for ICP only
instance_id (str, optional) – instance ID, mandatory for ICP
version (str, optional) – IBM Cloud Pak® for Data two-digit version, if not provided the version will be recognized automatically for IBM Cloud Pak® for Data 4.8 release and higher.
bedrock_url (str, optional) – Bedrock URL, applicable for ICP only
proxies (dict, optional) – dictionary of proxies, containing protocol and URL mapping (example: { “https”: “https://example.url.com” })
verify (bool, optional) – certificate verification flag

Example of create Credentials object

IBM watsonx.ai for IBM Cloud

from ibm_watsonx_ai import Credentials

# Example of creating the credentials using an API key:
credentials = Credentials(
    url = "https://us-south.ml.cloud.ibm.com",
    api_key = IAM_API_KEY
)

# Example of creating the credentials using a token:
credentials = Credentials(
    url = "https://us-south.ml.cloud.ibm.com",
    token = "***********"
)

IBM watsonx.ai software

import os
from ibm_watsonx_ai import Credentials

# Example of creating the credentials using username and password:
credentials = Credentials(
    url = "<URL>",
    username = "<USERNAME>",
    password = "<PASSWORD>",
    instance_id = "openshift"
)

# Example of creating the credentials using username and apikey:
credentials = Credentials(
    url = "<URL>",
    username = "<USERNAME>",
    api_key = IAM_API_KEY,
    instance_id = "openshift"
)

# Example of creating the credentials using a token:
access_token = os.environ['USER_ACCESS_TOKEN']
credentials = Credentials(
    url = "<URL>",
    token = access_token,
    instance_id = "openshift"
    version = "5.0" # optional
)

static from_dict(credentials, _verify=None)[source]¶

Create a Credentials object from dictionary.

Parameters:: credentials (dict) – credentials in the dictionary
Returns:: initialised credentials object
Return type:: Credentials

Example:

from ibm_watsonx_ai import Credentials

credentials = Credentials.from_dict({
    'url': "<url>",
    'apikey': IAM_API_URL
})

to_dict()[source]¶

Get dictionary from the Credentials object.

Returns:: dictionary with credentials
Return type:: dict

Example:

from ibm_watsonx_ai import Credentials

credentials = Credentials.from_dict({
    'url': "<url>",
    'apikey': IAM_API_KEY
})

credentials_dict = credentials.to_dict()