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 setverify

• httpx_client (httpx.Client,HttpClientConfig,optional) –

  A customizablehttpx.Client for ModelInference, Embeddings and methods related to the deployments management and scoring.Thehttpx.Client is used to improve performance across deployments, foundation models, and embeddings. This parameter accepts two types of input:

  • A direct instance ofhttpx.Client()

  • A set of parameters provided via theHttpClientConfig class

  Example:

  fromibm_watsonx_ai.utils.utilsimportHttpClientConfiglimits=httpx.Limits(max_connections=5)timeout=httpx.Timeout(7)http_config=HttpClientConfig(timeout=timeout,limits=limits)

  If not provided, a default instance ofhttpx.Client is created.

  Note

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

• async_httpx_client (httpx.AsyncClient,HttpClientConfig,optional) –

  A customizablehttpx.AsyncClient for ModelInference. Thehttpx.AsyncClient is used to improve performance of foundation models inference. This parameter accepts two types of input:

  • A direct instance ofhttpx.AsyncClient

  • A set of parameters provided via theHttpClientConfig class

  Example:

  fromibm_watsonx_ai.utils.utilsimportHttpClientConfiglimits=httpx.Limits(max_connections=5)timeout=httpx.Timeout(7)http_config=HttpClientConfig(timeout=timeout,limits=limits)

  If not provided, a default instance ofhttpx.AsyncClient is created.

  Note

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

Example:

fromibm_watsonx_aiimportAPIClient,Credentialscredentials=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_copy()[source]¶

Prepares clean copy of APIClient. The clean copy contains no token, password, api key data. It is usedin AI services scenarios, when the client is used in deployed code, and can be reused between users.

The copy needs to be set with current user token in the inner function of AI service.

Returns:

APIClient which is 2-level copy of the current one, without user secrets

Return type:

APIClient

Example:

defdeployable_ai_service(context,params={"k1":"v1"},**kwargs):# importsfromibm_watsonx_aiimportCredentials,APIClientfromibm_watsonx_ai.foundation_modelsimportModelInferencetask_token=context.generate_token()outer_context=contextclient=APIClient(Credentials(url="https://us-south.ml.cloud.ibm.com",token=task_token))# operations with clientdefgenerate(context):user_client=client.get_copy()user_client.set_token(context.generate_token())# operations with user_clientreturn{'body':response_body}returngeneratestored_ai_service_details=client._ai_services.store(deployable_ai_service,meta_props)

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

Get HTTP headers used during requests.

Parameters:

• content_type – value forContent-Type header, defaults toapplication/json

• include_user_agent – whether the result should includeUser-Agent header, defaults toFalse

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, ifpassword orapikey were passed.The user needs to take care of token refresh usingset_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>")

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

fromibm_watsonx_aiimportCredentials# 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

importosfromibm_watsonx_aiimportCredentials# 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)

staticfrom_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:

fromibm_watsonx_aiimportCredentialscredentials=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:

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