Replicate API Connector Guide

The Replicate API connector allows Tealfabric workflows to run machine learning models and consume prediction outputs in downstream steps. It is useful when your process needs generated media, model-driven text analysis, or other AI inference results as part of an automated business flow.

Configuration and authentication

Configure the connector with a Replicate API token from a service-owned account so model usage is auditable and environment-specific. Because model runtimes can vary significantly, set timeout_seconds high enough for your expected workload and validate access with test before production rollout.

• api_key (required): Replicate API token sent as Authorization: Token {api_key}.
• timeout_seconds (optional): Request timeout in seconds (default 120). Use higher values for long-running models.

Run predictions with predict or create

Use predict or create (aliases) to execute a model. Provide model or version plus a non-empty input object. The connector posts to POST /predictions and, when the initial response status is not terminal (succeeded, failed, or canceled), polls GET /predictions/{id} every two seconds until a terminal status or timeout.

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

async function createImagePrediction(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: "predict",
      model: "black-forest-labs/flux-schnell",
      input: {
        prompt: "Studio-style product photo of a modern espresso machine",
        num_outputs: 1,
      },
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = await response.json();
  return payload.data?.prediction;
}

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": "predict",
    "model": "black-forest-labs/flux-schnell",
    "input": {
      "prompt": "Studio-style product photo of a modern espresso machine",
      "num_outputs": 1
    }
  }'

{
  "success": true,
  "data": {
    "prediction_count": 1,
    "prediction": {
      "id": "<PREDICTION_ID>",
      "status": "succeeded",
      "output": [
        "https://replicate.delivery/pbxt/example-output.png"
      ]
    },
    "data": {
      "id": "<PREDICTION_ID>",
      "status": "succeeded",
      "output": [
        "https://replicate.delivery/pbxt/example-output.png"
      ]
    }
  }
}

Check or cancel predictions with get and cancel

Use get to fetch prediction progress and final output when your workflow needs explicit status handling. Pass prediction_id or id. Use cancel when a job is no longer needed to reduce cost and queue pressure.

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

async function getPredictionStatus(integrationId: string, predictionId: 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: "get",
      prediction_id: predictionId,
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const payload = await response.json();
  return payload.data?.prediction;
}

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": "get",
    "prediction_id": "<PREDICTION_ID>"
  }'

{
  "success": true,
  "data": {
    "prediction_count": 1,
    "prediction": {
      "id": "<PREDICTION_ID>",
      "status": "succeeded",
      "output": [
        "https://replicate.delivery/pbxt/example-output.png"
      ]
    },
    "data": {
      "id": "<PREDICTION_ID>",
      "status": "succeeded",
      "output": [
        "https://replicate.delivery/pbxt/example-output.png"
      ]
    }
  }
}

cancel uses the same response envelope as get and predict:

{
  "operation": "cancel",
  "prediction_id": "<PREDICTION_ID>"
}

Validate connectivity with test

test calls GET /account and returns endpoint details when the API token is valid.

{
  "success": true,
  "data": {
    "message": "Replicate API connection test successful",
    "details": {
      "endpoint": "https://api.replicate.com/v1"
    }
  }
}

Reliability guidance

Most production issues come from invalid model inputs, under-sized timeouts, and aggressive retry patterns during rate-limit windows. Validate model schemas before execution, capture prediction IDs for controlled polling, and apply backoff on transient failures (429 and 5xx responses are marked retriable). These patterns keep AI-enabled workflows reliable and cost-aware.

Additional resources

• Replicate HTTP API reference
• Replicate Explore
• Replicate API tokens