Replicate Getting Started: API Integration Guide (2026)

Getting started overview

Integrating with Replicate involves a series of steps designed to enable developers to run open-source machine learning models through an API. The process begins with account creation, followed by the generation of an API token for authentication. Once credentials are in place, developers can use client libraries or direct HTTP requests to interact with various models hosted on the platform. Replicate abstracts away the underlying infrastructure, allowing users to focus on model selection and data processing rather than GPU management or deployment complexities.

The platform provides a comprehensive API reference alongside SDKs for multiple programming languages including Python, JavaScript, and Go, facilitating integration into diverse development environments. This getting started guide focuses on the initial setup and making a first successful API call, which is a prerequisite for more advanced use cases such as model fine-tuning or custom model deployment.

Quick Reference Guide

Create an account and get keys

To begin using Replicate, the first step is to create a user account. This can be done directly through the Replicate website. Account creation typically involves providing an email address or using an existing GitHub account for authentication. Upon successful registration, users gain access to the Replicate dashboard, where they can manage their projects, view usage, and access API tokens.

API tokens are essential for authenticating requests made to the Replicate API. These tokens serve as a secure credential that links API calls to your account and ensures proper billing and access control. Replicate's authentication mechanism relies on these tokens, which should be treated as sensitive information similar to passwords. According to Replicate's authentication guide, API tokens are typically found in the account settings or developer section of the Replicate dashboard after logging in. It is recommended to store these tokens securely and avoid hardcoding them directly into application code, especially for production environments.

Once you have your API token, it is typically passed in the Authorization header of HTTP requests or configured within the SDK of your chosen programming language. For instance, when using the Python client, the token can be set as an environment variable (REPLICATE_API_TOKEN) to avoid direct exposure within the codebase. This practice aligns with general API security best practices, as outlined in resources like the AWS security credentials best practices, which emphasize minimizing the risk of credential compromise.

Your first request

After setting up your Replicate account and obtaining an API token, the next step is to make your first request to run a model. Replicate provides client libraries (SDKs) for several languages, simplifying interaction with the API. For this guide, we will demonstrate examples using Python and JavaScript, which are among the primary language examples listed by Replicate.

Python Example

To use the Replicate Python client, first install it via pip:

pip install replicate

Then, you can make a prediction. Ensure your API token is set as an environment variable (REPLICATE_API_TOKEN).

import replicate
import os

# Ensure your API token is set as an environment variable:
# export REPLICATE_API_TOKEN="r8_YOUR_API_TOKEN_HERE"

# Example: Running a text-to-image model (Stable Diffusion)
# Replace 'stability-ai/stable-diffusion' with the model ID you want to use.
# You can find model IDs and their inputs/outputs on the Replicate website.
model_id = "stability-ai/stable-diffusion:ac732df83cea7fff18b47247d0d2dab6606fb89f21e892d7fd8ff785ffce4cbe"
input_data = {
    "prompt": "a photo of an astronaut riding a horse on mars",
    "width": 768,
    "height": 768
}

try:
    print(f"Running model {model_id} with input: {input_data}")
    output = replicate.run(
        model_id,
        input=input_data
    )
    print("Prediction output:")
    for item in output:
        print(item)
except replicate.exceptions.ReplicateError as e:
    print(f"Error making prediction: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

This Python script calls a specified model with input parameters and prints the returned output. The model ID and input parameters vary depending on the model chosen. You can explore available models and their required inputs on the Replicate model exploration page.

JavaScript Example

For JavaScript, install the Replicate Node.js client:

npm install replicate

Then, set your API token as an environment variable (REPLICATE_API_TOKEN) and execute your prediction:

import Replicate from "replicate";

const replicate = new Replicate({
  auth: process.env.REPLICATE_API_TOKEN,
});

async function runPrediction() {
  try {
    // Example: Running a text-to-image model (Stable Diffusion)
    // Replace 'stability-ai/stable-diffusion' with the model ID you want to use.
    const model_id = "stability-ai/stable-diffusion:ac732df83cea7fff18b47247d0d2dab6606fb89f21e892d7fd8ff785ffce4cbe";
    const input_data = {
      prompt: "a photo of an astronaut riding a horse on mars",
      width: 768,
      height: 768,
    };

    console.log(`Running model ${model_id} with input:`, input_data);
    const output = await replicate.run(
      model_id,
      { input: input_data }
    );
    console.log("Prediction output:", output);
  } catch (error) {
    console.error("Error making prediction:", error);
  }
}

runPrediction();

Similar to the Python example, this JavaScript code initiates a prediction request. The model_id and input_data must correspond to the model you intend to use. The output will typically be a URL to the generated image or other model-specific results.

Common next steps

After successfully making your first request to Replicate, several common next steps can enhance your integration and leverage more of the platform's capabilities:

1. Explore More Models: Replicate hosts a wide array of open-source models. Experiment with different categories like image generation, natural language processing, or audio synthesis to find models relevant to your application.
2. Asynchronous Predictions: For long-running tasks, switch to asynchronous prediction methods. Replicate supports webhook callbacks to notify your application upon completion, which is crucial for maintaining responsiveness in web applications. The Replicate Python async guide provides details on implementing this.
3. Manage Model Versions: Models on Replicate often have multiple versions. Ensure you are using the correct version for stability and reproducibility in your applications. The API allows specifying exact model versions.
4. Error Handling and Retries: Implement robust error handling (e.g., catching ReplicateError exceptions in Python) and retry mechanisms, especially for transient network issues or rate limiting. This aligns with general best practices for handling API errors.
5. Monitor Usage and Costs: Regularly check your Replicate dashboard for API usage statistics and billing information. Replicate operates on a pay-as-you-go pricing model, so monitoring helps manage expenses.
6. Deploy Custom Models: If existing open-source models do not meet your needs, Replicate provides tools to deploy your own custom machine learning models. This involves containerizing your model and pushing it to Replicate.
7. Integrate with Webhooks: For real-time updates on prediction status, configure webhooks. This allows Replicate to send POST requests to a specified URL in your application when a prediction is complete or encounters an error. Replicate webhook documentation explains the setup.

Troubleshooting the first call

When making your initial API call to Replicate, various issues can arise. Here are common problems and their potential solutions:

• Authentication Errors (401 Unauthorized):
  • Issue: The API token is missing, incorrect, or expired.
  • Solution: Double-check that your REPLICATE_API_TOKEN environment variable is correctly set and contains the exact token from your Replicate API tokens page. Ensure there are no leading or trailing spaces.
• Invalid Model ID or Version (404 Not Found):
  • Issue: The specified model ID or version does not exist or is misspelled.
  • Solution: Verify the model ID and its exact version string against the Replicate model explorer or the model's specific page on the Replicate website. Model IDs are case-sensitive.
• Incorrect Input Parameters (400 Bad Request):
  • Issue: The input provided to the model does not match its expected schema (e.g., wrong data type, missing required fields).
  • Solution: Consult the specific model's page on Replicate for its input schema. Ensure all required parameters are present and data types (e.g., string, integer, float) are correct.
• Rate Limiting (429 Too Many Requests):
  • Issue: You've sent too many requests in a short period.
  • Solution: Implement exponential backoff and retry logic in your application. Replicate's API has rate limits to ensure fair usage.
• Network Issues:
  • Issue: Connectivity problems prevent your application from reaching the Replicate API servers.
  • Solution: Check your internet connection. Temporarily disable VPNs or firewalls if they might be interfering. Verify the Replicate API status page if available.
• Environment Variable Not Loaded:
  • Issue: The REPLICATE_API_TOKEN environment variable is set but not being picked up by your script.
  • Solution: Ensure your script is run in an environment where the variable is active. For example, if you set it in your shell, make sure the script is executed in that same shell session. In Python, you can explicitly retrieve it with os.environ.get("REPLICATE_API_TOKEN") to debug.