TealfabricLibrary

AI21 Labs API Connector Guide

The AI21 Labs connector lets Tealfabric workflows generate, paraphrase, and summarize text using Jurassic models (J2-Ultra, J2-Mid, and J2-Light). It is suited for controllable generation, long-form drafting, and content variation tasks where temperature, stop sequences, and model tier affect cost and quality.

Document information
FieldValue
Canonical URL/docs/04_connecting-systems/connectors/a/ai21-labs
Version (published date)2026-06-17
Tagsconnectors, reference, ai21-labs
Connector IDai21-labs-1.0.0

Configuration and authentication

Configure the connector with your AI21 Labs API key and default model settings. The connector uses API key authentication via Authorization: Bearer.

  • api_key (required): API key from AI21 Labs Studio.
  • model (optional): default j2-mid. Options include j2-ultra, j2-mid, and j2-light.
  • timeout_seconds (optional): request timeout in seconds; default 30.

Use test after configuration to confirm credentials before production workflows.

Runtime note: The current backend-next package validates api_key and returns a scaffold placeholder response until operation-specific HTTP logic is implemented. The examples below show the intended callData contract.

Generate text with complete

Use complete for prompt-based text generation with optional temperature, top_p, and stop sequences.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function completePrompt(integrationId: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "complete",
      prompt: "Write a professional email to a client about a project delay.",
      max_tokens: 500,
      temperature: 0.7,
      top_p: 0.9,
      stop: ["\n\n", "END"],
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}
curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "complete",
    "prompt": "The future of artificial intelligence is",
    "max_tokens": 200,
    "temperature": 0.7
  }'

{
  "success": true,
  "data": {
    "text_count": 1,
    "completions": [
      {
        "data": {
          "text": "...generated text...",
          "tokens": []
        },
        "finishReason": "stop"
      }
    ]
  },
  "metadata": {
    "processing_time_ms": 842
  }
}

Generate chat responses with chat

Use chat for message-based conversations. Provide messages with role and content, and optional system instructions.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function askAi21(integrationId: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "chat",
      messages: [
        { role: "user", content: "What is machine learning?" },
      ],
      system: "You are a helpful science educator. Explain concepts clearly.",
      max_tokens: 300,
      temperature: 0.8,
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}
{
  "success": true,
  "data": {
    "text_count": 1,
    "response": "Machine learning is a subset of artificial intelligence...",
    "outputs": [
      {
        "text": "...response text...",
        "finishReason": "stop"
      }
    ]
  },
  "metadata": {
    "processing_time_ms": 612
  }
}

Paraphrase and summarize

Use paraphrase to generate alternative phrasings and summarize to condense longer text.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function paraphraseText(integrationId: string, text: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "paraphrase",
      text,
      style: "general",
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

async function summarizeText(integrationId: string, text: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "summarize",
      text,
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

Test connectivity with test

Use test to validate api_key configuration with a minimal API call.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function testAi21Connection(integrationId: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ operation: "test" }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

Reliability and model strategy

  • Use j2-light for fast, low-cost tasks; j2-mid for general automation; j2-ultra for highest-quality output.
  • Set max_tokens explicitly to control cost and latency.
  • Implement exponential backoff for HTTP 429 responses and transient timeouts.
  • Always check success in responses and log metadata.processing_time_ms for monitoring.

Failed requests return a structured error:

{
  "success": false,
  "error": {
    "code": "UNKNOWN",
    "message": "Error message describing what went wrong",
    "retriable": false
  },
  "metadata": {
    "processing_time_ms": 123,
    "execution_id": "corr-12345"
  }
}

Additional resources