> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synapsai.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Classification

> Examples of text and zero-shot classification with SynapsAI Cloud

Our classification endpoints cover text, audio, image, token, video and zero-shot classification, exposed via simple JSON APIs.

## Text classification

Here is an example of text classification:

**Parameters:**

* `model`: The model ID of the model you want to use
* `inputs`: One or several texts to classify. To use text pairs, send a dict with `{"text", "text_pair"}` or a list of such dicts
* `top_k`: How many results to return for each input (optional)
* `function_to_apply`: How to convert raw logits to scores (optional, options: `sigmoid`, `softmax`, `none`)

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  model = SynapsAI("your-api-key")

  response = model.classifications.text(
      model="model-id",
      inputs=[
          "I loved this movie, it was fantastic!",
          "The service was terrible and the food was cold."
      ],
      top_k=3,
      function_to_apply="softmax",
  )

  for item in response.data:
      print("Label:", item.label, "Score:", item.score)
  ```

  ```curl title="cURL" theme={null}
  curl -X POST https://api.synapsai.cloud/v1/classifications/text \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "model-id",
          "inputs": [
            "I loved this movie, it was fantastic!",
            "The service was terrible and the food was cold."
          ],
          "top_k": 3,
          "function_to_apply": "softmax"
      }'
  ```
</CodeGroup>

## Audio classification

Here is an example of audio classification:

**Parameters:**

* `model`: The model ID of the model you want to use
* `inputs`: The audio data to classify. Can be raw waveform, bytes from an audio file, or a dict with sampling rate and raw audio
* `top_k`: The number of top labels to return (optional)
* `function_to_apply`: How to convert model outputs to scores (optional, options: `sigmoid`, `softmax`, `none`)

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  model = SynapsAI("your-api-key")

  with open("audio.wav", "rb") as f:
      audio_bytes = f.read()

  response = model.classifications.audio(
      model="model-id",
      inputs=audio_bytes,
      top_k=3,
      function_to_apply="softmax",
  )

  for item in response.data:
      print("Label:", item.label, "Score:", item.score)
  ```

  ```curl title="cURL" theme={null}
  curl -X POST https://api.synapsai.cloud/v1/classifications/audio \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "model-id",
          "inputs": {
            "array": [0.0, 0.1, 0.2],
            "sampling_rate": 16000
          },
          "top_k": 3,
          "function_to_apply": "softmax"
      }'
  ```
</CodeGroup>

## Image classification

Here is an example of image classification:

**Parameters:**

* `model`: The model ID of the model you want to use
* `inputs`: The image or list of images to classify. Can be a URL, base64 string, file path, or `PIL.Image`
* `function_to_apply`: How to convert model outputs to scores (optional, options: `sigmoid`, `softmax`, `none`)
* `top_k`: The number of top labels to return (optional)
* `timeout`: Maximum time in seconds to wait for fetching images from the web (optional)

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  model = SynapsAI("your-api-key")

  response = model.classifications.image(
      model="model-id",
      inputs=[
          "https://example.com/cat.jpg",
          "https://example.com/dog.jpg"
      ],
      top_k=5,
      function_to_apply="softmax",
  )

  for item in response.data:
      print("Label:", item.label, "Score:", item.score)
  ```

  ```curl title="cURL" theme={null}
  curl -X POST https://api.synapsai.cloud/v1/classifications/image \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "model-id",
          "inputs": [
            "https://example.com/cat.jpg",
            "https://example.com/dog.jpg"
          ],
          "top_k": 5,
          "function_to_apply": "softmax"
      }'
  ```
</CodeGroup>

## Token classification

Here is an example of token classification:

**Parameters:**

* `model`: The model ID of the model you want to use
* `inputs`: One or several texts for token classification

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  model = SynapsAI("your-api-key")

  response = model.classifications.token(
      model="model-id",
      inputs="Hugging Face is based in New York City.",
  )

  for item in response.data:
      print("Word:", item.word, "Entity:", item.entity, "Score:", item.score)
  ```

  ```curl title="cURL" theme={null}
  curl -X POST https://api.synapsai.cloud/v1/classifications/token \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "model-id",
          "inputs": "Hugging Face is based in New York City."
      }'
  ```
</CodeGroup>

## Video classification

Here is an example of video classification:

**Parameters:**

* `model`: The model ID of the model you want to use
* `inputs`: A HTTP link or local path to a video, or a list of such inputs
* `top_k`: The number of top labels to return (optional)
* `num_frames`: The number of frames sampled from the video (optional)
* `frame_sampling_rate`: The sampling rate used to select frames from the video (optional)
* `function_to_apply`: How to convert model outputs to scores (optional, options: `sigmoid`, `softmax`, `none`)

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  model = SynapsAI("your-api-key")

  response = model.classifications.video(
      model="model-id",
      inputs=["https://example.com/video.mp4"],
      top_k=5,
      num_frames=16,
      frame_sampling_rate=1,
      function_to_apply="softmax",
  )

  for item in response.data:
      print("Label:", item.label, "Score:", item.score)
  ```

  ```curl title="cURL" theme={null}
  curl -X POST https://api.synapsai.cloud/v1/classifications/video \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "model-id",
          "inputs": ["https://example.com/video.mp4"],
          "top_k": 5,
          "num_frames": 16,
          "frame_sampling_rate": 1,
          "function_to_apply": "softmax"
      }'
  ```
</CodeGroup>

## Zero-shot text classification

Zero-shot classification lets you classify text into labels that the model has not been explicitly trained on, by providing your own candidate labels.

**Parameters:**

* `model`: The model ID of the model you want to use
* `sequences`: The input text or list of texts to classify
* `candidate_labels`: List of labels to classify the text against (required)
* `hypothesis_template`: Template used to format each candidate label into a hypothesis for scoring (optional, default: `This example is {}`)
* `multi_label`: Whether multiple labels can be true for each input (optional)

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  model = SynapsAI("your-api-key")

  response = model.classifications.zero_shot.text(
      model="model-id",
      sequences=[
          "I need to return my order, it arrived damaged.",
          "The new update is amazing, great work!"
      ],
      candidate_labels=["support", "sales", "feedback", "bug"],
      hypothesis_template="This text is about {}.",
      multi_label=True,
  )

  for item in response.data:
      print("Sequence:", item.sequence)
      for label, score in zip(item.labels, item.scores):
          print("  -", label, "(", score, ")")
  ```

  ```curl title="cURL" theme={null}
  curl -X POST https://api.synapsai.cloud/v1/classifications/zero-shot \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "model-id",
          "sequences": [
            "I need to return my order, it arrived damaged.",
            "The new update is amazing, great work!"
          ],
          "candidate_labels": ["support", "sales", "feedback", "bug"],
          "hypothesis_template": "This text is about {}.",
          "multi_label": true
      }'
  ```
</CodeGroup>

## Zero-shot audio classification

Here is an example of zero-shot audio classification:

**Parameters:**

* `model`: The model ID of the model you want to use
* `audios`: One audio array or a list of audio arrays to classify
* `candidate_labels`: Candidate labels to classify the audio against (required)
* `hypothesis_template`: Template used with candidate labels (optional, default: `This is a sound of {}`)

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI
  import numpy as np

  model = SynapsAI("your-api-key")

  audio_array = np.zeros(16000)

  response = model.classifications.zero_shot.audio(
      model="model-id",
      audios=[audio_array],
      candidate_labels=["speech", "music", "noise"],
      hypothesis_template="This is a sound of {}.",
  )

  for item in response.data:
      print("Label:", item.label, "Score:", item.score)
  ```

  ```curl title="cURL" theme={null}
  curl -X POST https://api.synapsai.cloud/v1/classifications/zero-shot/audio \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "model-id",
          "audios": [[0.0, 0.1, 0.2]],
          "candidate_labels": ["speech", "music", "noise"],
          "hypothesis_template": "This is a sound of {}."
      }'
  ```
</CodeGroup>

## Zero-shot image classification

Here is an example of zero-shot image classification:

**Parameters:**

* `model`: The model ID of the model you want to use
* `image`: An image or list of images to classify (URL, base64, file path, or `PIL.Image`)
* `candidate_labels`: Candidate labels for the image (required)
* `hypothesis_template`: Template used with candidate labels (optional, default: `This is a photo of {}`)
* `timeout`: Maximum time in seconds to wait for fetching images from the web (optional)

<CodeGroup>
  ```python title="Python" theme={null}
  from synapsai import SynapsAI

  model = SynapsAI("your-api-key")

  response = model.classifications.zero_shot.image(
      model="model-id",
      image=["https://example.com/image.jpg"],
      candidate_labels=["cat", "dog", "car"],
      hypothesis_template="This is a photo of {}.",
  )

  for item in response.data:
      print("Label:", item.label, "Score:", item.score)
  ```

  ```curl title="cURL" theme={null}
  curl -X POST https://api.synapsai.cloud/v1/classifications/zero-shot/image \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "model": "model-id",
          "image": ["https://example.com/image.jpg"],
          "candidate_labels": ["cat", "dog", "car"],
          "hypothesis_template": "This is a photo of {}."
      }'
  ```
</CodeGroup>

## Object detection

Object detection uses the `/v1/images/object-detection` endpoint, not the classification routes. See the [Images](/examples/images#object-detection) page for a full example with parameters and code samples.

You can also try classification endpoints using the [Playground](https://platform.synapsai.cloud/playground). For endpoint details, see the [API reference](https://docs.synapsai.cloud/api-reference/text-classification).