Connect AI agents to Diarize

Setup

1. Install the SDK

   • Node.js
   • Python

   npm install @scalekit-sdk/node dotenv

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Create the Diarize connection

   In AgentKit > Connections, create a Diarize connection. The name you give it is the connection_name your code passes. See Configure connections.

   Console steps with screenshots

   Register your Diarize API key with Scalekit so it can authenticate and proxy transcription requests on behalf of your users. Diarize uses API key authentication.

   1. Get a Diarize API key

      • Sign in to diarize.io and go to Settings → API Keys.

      • Click + Create New Key, give it a name (e.g., Agent Auth), and confirm.

      • Copy the key value — store it securely, as you will not be able to view it again.

      

   2. Create a connection in Scalekit

      • In Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find Diarize and click Create.

      • Note the Connection name — you will use this as connection_name in your code (e.g., diarize).

      • Click Save.

      

   3. Add a connected account

      Connected accounts link a specific user identifier in your system to a Diarize API key. Add one in the dashboard to test. In production, each user adds their own through the authorization link: they enter their credentials on the page it opens.

      In the dashboard, to test

      • Open the connection you created and click the Connected Accounts tab → Add account.

      • Fill in:

        • Your User’s ID — a unique identifier for this user in your system (e.g., user_123)
        • API Key — the Diarize API key you copied in step 1

      • Click Create Account.

      

      From your backend, if your app already has the credentials

      For example, when users enter them on a settings page in your app:

      • Node.js
      • Python

      1
      import { ConnectorStatus } from '@scalekit-sdk/node'
      2
      
      3
      // Never hard-code API keys — read from secure storage or user input
      4
      const diarizeApiKey = getUserDiarizeKey(); // retrieve from your secure store
      5
      
      6
      const authorizationDetails = {
      7
        details: {
      8
          case: 'staticAuth',
      9
          value: { details: { token: diarizeApiKey } },
      10
        },
      11
      };
      12
      
      13
      let { connectedAccount } = await scalekit.actions.upsertConnectedAccount({
      14
        connectionName: 'diarize',
      15
        identifier: 'user_123',       // your user's unique ID
      16
        authorizationDetails,
      17
      });
      18
      
      19
      // Make sure the account is ACTIVE before the first tool call.
      20
      if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
      21
        ({ connectedAccount } = await scalekit.actions.upsertConnectedAccount({
      22
          connectionName: 'diarize',
      23
          identifier: 'user_123',
      24
          authorizationDetails,
      25
        }));
      26
      }

4. Authorize a user and make your first call

   • Node.js
   • Python

   1
   import { ScalekitClient } from '@scalekit-sdk/node'
   2
   import 'dotenv/config'
   3
   import { createInterface } from 'node:readline/promises'
   4
   
   5
   const scalekit = new ScalekitClient(
   6
     process.env.SCALEKIT_ENVIRONMENT_URL,
   7
     process.env.SCALEKIT_CLIENT_ID,
   8
     process.env.SCALEKIT_CLIENT_SECRET,
   9
   )
   10
   const actions = scalekit.actions
   11
   
   12
   const connector = 'diarize'
   13
   const identifier = 'user_123'
   14
   
   15
   // Generate an authorization link for the user
   16
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   17
   console.log('Authorize Diarize:', link)
   18
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   19
   await rl.question('Press Enter after authorizing...')
   20
   rl.close()
   21
   
   22
   // Make your first call
   23
   const result = await actions.executeTool({
   24
     connector,
   25
     identifier,
   26
     toolName: 'diarize_download_transcript',
   27
     toolInput: { job_id: 'YOUR_JOB_ID' },
   28
   })
   29
   console.log(result)

   npx tsx quickstart.mts

   Each user opens the link once and enters their Diarize credentials there. If your app already has a user's credentials, add the account from your backend instead, as the console steps above show. See Authorize a user for the full flow and statuses.

Workflows

1
import time
2

3
# Step 1: Submit a transcription job
4
create_result = actions.execute_tool(
5
    connection_name='diarize',
6
    identifier='user_123',
7
    tool_name="diarize_create_transcription_job",
8
    tool_input={
9
        "url": "https://www.youtube.com/watch?v=example",
10
        "language": "en",   # optional — omit for auto-detection
11
        "num_speakers": 2,  # optional — improves speaker diarization
12
    },
13
)
14
job_id = create_result.data["id"]
15
estimated_seconds = create_result.data.get("estimatedTime", 120)
16
deadline = time.time() + estimated_seconds * 2
17
print(f"Job {job_id} submitted. Estimated: {estimated_seconds}s")
18

19
# Step 2: Poll until complete
20
while True:
21
    if time.time() > deadline:
22
        raise TimeoutError(f"Job {job_id} timed out after {estimated_seconds * 2}s")
23
    time.sleep(15)
24
    status_result = actions.execute_tool(
25
        connection_name='diarize',
26
        identifier='user_123',
27
        tool_name="diarize_get_job_status",
28
        tool_input={"job_id": job_id},
29
    )
30
    status = status_result.data["status"]
31
    print("Status:", status)
32
    if status == "COMPLETED":
33
        break
34
    if status == "FAILED":
35
        raise RuntimeError(f"Job {job_id} failed")
36

37
# Step 3: Download the diarized transcript
38
transcript_result = actions.execute_tool(
39
    connection_name='diarize',
40
    identifier='user_123',
41
    tool_name="diarize_download_transcript",
42
    tool_input={"job_id": job_id, "format": "json"},
43
)
44
# handle the transcript_result

1
// Step 1: Submit a transcription job
2
const createResult = await actions.executeTool({
3
  connector: 'diarize',
4
  identifier: 'user_123',
5
  toolName: 'diarize_create_transcription_job',
6
  toolInput: {
7
    url: 'https://www.youtube.com/watch?v=example',
8
    language: 'en',   // optional — omit for auto-detection
9
    num_speakers: 2,  // optional — improves speaker diarization
10
  },
11
});
12
const jobId = createResult.data.id;
13
const estimatedSeconds = createResult.data.estimatedTime ?? 120;
14
const deadline = Date.now() + estimatedSeconds * 2 * 1000;
15
console.log(`Job ${jobId} submitted. Estimated: ${estimatedSeconds}s`);
16

17
// Step 2: Poll until complete
18
let status = 'PENDING';
19
while (status !== 'COMPLETED' && status !== 'FAILED') {
20
  if (Date.now() > deadline) throw new Error(`Job ${jobId} timed out after ${estimatedSeconds * 2}s`);
21
  await new Promise(r => setTimeout(r, 15_000));
22
  const statusResult = await actions.executeTool({
23
    connector: 'diarize',
24
    identifier: 'user_123',
25
    toolName: 'diarize_get_job_status',
26
    toolInput: { job_id: jobId },
27
  });
28
  status = statusResult.data.status;
29
  console.log('Status:', status);
30
}
31
if (status === 'FAILED') throw new Error(`Job ${jobId} failed`);
32

33
// Step 3: Download the diarized transcript
34
const transcriptResult = await actions.executeTool({
35
  connector: 'diarize',
36
  identifier: 'user_123',
37
  toolName: 'diarize_download_transcript',
38
  toolInput: { job_id: jobId, format: 'json' },
39
});
40
// handle the transcriptResult