Name: CLIP Features API: Batch Text and Image Embeddings
Brand: magicapi
SKU: api-magicapi-clip-feature-extraction-andreasjansson-clip-features
Availability: InStock
Author: API Market

Shashank Agarwal

# 🔢 CLIP Text and Image Embeddings API (andreasjansson CLIP Features)

## Overview
CLIP Features returns CLIP features (embeddings) from the clip-vit-large-patch14 model.

Send `inputs` as newline-separated lines. Each line is either a piece of text or an image URL starting with `http://` or `https://`. The response has one entry per line, with the original `input` and its `embedding`. In the example, every embedding is a list of 768 numbers. CLIP places text and images in the same embedding space, so a text embedding can be compared directly with an image embedding.

## Features
- **Text and images in one call**: mix text lines and image URLs in `inputs`.
- **One embedding per line**: the output keeps the order of your lines and echoes each line as `input`.
- **768-number vectors**: each embedding in the example has 768 values.
- **Shared space**: compare text and image embeddings with cosine similarity.

## Use Cases
1. **Text-to-image search**: embed your image library once, then embed a search phrase and rank images by similarity.
2. **Zero-shot labeling**: embed candidate labels such as "a photo of a dog" and "a cat" and pick the label closest to an image, as in the example.
3. **Duplicate and near-duplicate detection**: find images whose embeddings are very close.
4. **Clustering and recommendations**: group images or captions by meaning.

## Examples
### Example Input
`inputs` has four lines: three texts and one image URL.

```text
a photo of a dog
a cat
two cats with remote controls
https://blog.api.market/wp-content/uploads/2026/10/clip-features-output-api-market.jpg
```

The image on the last line:

![CLIP Features example input image: two cats lying on a pink couch with two remote controls](https://blog.api.market/wp-content/uploads/2026/10/clip-features-output-735pxhvz-api-market.jpg)

### Example Output
A list with one entry per input line. Each `embedding` has 768 numbers; only the first 3 are shown here:

```json
[
  {
    "embedding": [
      0.16265869140625,
      -0.06995393335819244,
      0.364326536655426
    ],
    "input": "a photo of a dog"
  },
  {
    "embedding": [
      0.08319822698831558,
      -0.027810707688331604,
      0.6705333590507507
    ],
    "input": "a cat"
  },
  {
    "embedding": [
      -0.028153788298368454,
      0.2641875743865967,
      -0.3605521321296692
    ],
    "input": "two cats with remote controls"
  },
  {
    "embedding": [
      -0.6105533838272095,
      1.413478136062622,
      -0.011759668588638306
    ],
    "input": "https://blog.api.market/wp-content/uploads/2026/10/clip-features-output-api-market.jpg"
  }
]
```

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `inputs` | string | No | `"a\nb"` |  | Newline-separated inputs. Each line is either text or an image URL starting with http:// or https:// |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.001 per API unit.
- **1 API unit = 1 request with up to 4 seconds of processing time.** A request that takes longer uses one unit per started 4-second block (for example, 9 seconds of processing is 3 units, $0.003).
- **Example cost**: the request below took 0.79 seconds of processing, so it used 1 API unit = **$0.001**.
- A request with many lines or large images can take longer and use more than one unit.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/clip-feature-extraction-andreasjansson-clip-features`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/clip-feature-extraction-andreasjansson-clip-features/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "75b33f253f7714a281ad3e9b28f63e3232d583716ef6718f2e46641077ea040a",
    "input": {
      "inputs": "a photo of a dog\na cat\ntwo cats with remote controls\nhttps://blog.api.market/wp-content/uploads/2026/10/clip-features-output-api-market.jpg"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "735pxhvzfhrgc0d1c71thamfzm",
  "version": "75b33f253f7714a281ad3e9b28f63e3232d583716ef6718f2e46641077ea040a",
  "status": "starting",
  "created_at": "2026-10-22T03:59:24.776Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/clip-feature-extraction-andreasjansson-clip-features/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "735pxhvzfhrgc0d1c71thamfzm",
  "status": "succeeded",
  "output": [
    {
      "embedding": [
        0.16265869140625,
        -0.06995393335819244,
        0.364326536655426
      ],
      "input": "a photo of a dog"
    },
    {
      "embedding": [
        0.08319822698831558,
        -0.027810707688331604,
        0.6705333590507507
      ],
      "input": "a cat"
    },
    {
      "embedding": [
        -0.028153788298368454,
        0.2641875743865967,
        -0.3605521321296692
      ],
      "input": "two cats with remote controls"
    },
    {
      "embedding": [
        -0.6105533838272095,
        1.413478136062622,
        -0.011759668588638306
      ],
      "input": "https://blog.api.market/wp-content/uploads/2026/10/clip-features-output-api-market.jpg"
    }
  ],
  "error": null,
  "created_at": "2026-10-22T03:59:24.776Z",
  "started_at": "2026-10-22T03:59:25.276Z",
  "completed_at": "2026-10-22T03:59:25.580Z"
}
```

`output` is a list with one object per input line, in the same order. Each object has `input` (the line you sent) and `embedding` (a list of numbers; 768 in the example, shortened to 3 here).

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example an `inputs` value that is not a string.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.
## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/clip-feature-extraction-andreasjansson-clip-features";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "75b33f253f7714a281ad3e9b28f63e3232d583716ef6718f2e46641077ea040a", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  "inputs": "a photo of a dog\na cat\ntwo cats with remote controls\nhttps://blog.api.market/wp-content/uploads/2026/10/clip-features-output-api-market.jpg"
}).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/clip-feature-extraction-andreasjansson-clip-features"

def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "75b33f253f7714a281ad3e9b28f63e3232d583716ef6718f2e46641077ea040a", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])

def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")

output = create_and_wait_for_prediction({
    "inputs": "a photo of a dog\na cat\ntwo cats with remote controls\nhttps://blog.api.market/wp-content/uploads/2026/10/clip-features-output-api-market.jpg"
})
print(output)
```

## FAQ
- **How do I send several items in one request?**
  - Put each item on its own line in `inputs`. A line that starts with `http://` or `https://` is treated as an image URL; any other line is treated as text.
- **How long is each embedding?**
  - In the example, each embedding has 768 numbers, for text and images alike.
- **Can I compare a text embedding with an image embedding?**
  - Yes. CLIP puts both in the same space; use cosine similarity to see how well a text matches an image.
- **How is a request billed?**
  - $0.001 per request that takes up to 4 seconds of processing; longer requests use one unit per started 4-second block. The four-line example took 0.79 seconds, so it cost $0.001.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, check that each image URL is reachable and try again.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


CLIP features API: get CLIP embeddings for a list of texts and image URLs in one call, one 768 number vector per line, for search and clustering.