Classification

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)

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 -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"
    }'

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)

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 -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"
    }'

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)

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 -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"
    }'

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

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 -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."
    }'

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)

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 -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"
    }'

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)

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 -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
    }'

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 {})

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 -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 {}."
    }'

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)

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 -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 {}."
    }'

Object detection

Object detection uses the /v1/images/object-detection endpoint, not the classification routes. See the Images page for a full example with parameters and code samples. You can also try classification endpoints using the Playground. For endpoint details, see the API reference.

Getting started

Guides

Examples

Manage

Platform

Resources

Support

Legal

Text classification

Audio classification

Image classification

Token classification

Video classification

Zero-shot text classification

Zero-shot audio classification

Zero-shot image classification

Object detection

​Text classification

​Audio classification

​Image classification

​Token classification

​Video classification

​Zero-shot text classification

​Zero-shot audio classification

​Zero-shot image classification

​Object detection

Text classification

Audio classification

Image classification

Token classification

Video classification

Zero-shot text classification

Zero-shot audio classification

Zero-shot image classification

Object detection