Run a model through the API

Introduction

The /api/generate endpoint allows you to create media by sending a request with specific parameters. This guide will walk you through the process of using this endpoint, including how to set up your request and handle responses.

Prerequisites

Before you start, ensure you have the following:

• An API key for authentication. If you don't have one, you can create one here.
• A running instance of the backend server.

Making a Request to /api/generate

To generate media, you need to send a POST request to the /api/generate endpoint. Here’s how to do it:

1. Set Up Your Request

You can use tools like curl, Postman, or fetch in Node.js to set up your API request. Make sure to include your API key in the request headers for authentication.

2. Define the Request Payload

Your request should include the necessary fields, such as the model you want to use, the input parameters for media generation, and an optional webhook URL for notifications.

Example payload structure:

{
  "model": "playground-v2",
  "input": {
    "prompt" : "Astronaut in a jungle, cold color palette, muted colors, detailed, 8k"
  },
  "webhook": "https://your-server.com/api/webhook"
}

3. Send the Request

Here’s an example of how to send a request using fetch in Node.js:

const fetch = require('node-fetch');

const createMedia = async () => {
  const response = await fetch('https://api.artificialstudio.ai/api/generate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      model: "playground-v2",
      input: {
        prompt: "Astronaut in a jungle, cold color palette, muted colors, detailed, 8k"
      },
      webhook: "https://your-server.com/api/webhook"
    })
  });

  const data = await response.json();
  console.log(data);
};

createMedia();

4. Handle the Response

The response from the /api/generate endpoint will include details about the media creation process. If successful, you will receive information about the generated media, including its ID and status.

Example response:

{
  "_id": "media_id",
  "status": "pending",
  "model": "playground-v2",
  "output": null
}

Setting Up Webhooks

If you included a webhook URL in your request, your server will receive notifications about the status of the media generation. Here’s how to handle webhook notifications:

1. Configure Webhook URL

Ensure that the webhook URL you provided is publicly accessible and can handle POST requests.

2. Handle Webhook Notifications

Set up an endpoint on your server to receive webhook notifications. The payload will include details about the media generation status.

Example webhook payload:

{
  "_id": "media_id",
  "status": "success",
  "output": "https://files.artificialstudio.ai/...",
  "model": "playground-v2",
  "type": "image",
  "payload": {
    "prompt": "A beautiful sunset over the ocean"
  },
  "error": null
}

3. Verify Webhook Data

For security, verify the data received in the webhook to ensure it originates from your backend server.

Example using Express:

app.post("/api/webhook", (req, res) => {
  console.log(req.body);
  res.send("Webhook received");
});

Conclusion

You are now equipped to use the /api/generate endpoint to create media. Make sure to handle responses and webhook notifications appropriately. For further assistance, refer to the API Documentation or contact support.