Ittybit

Overview

The Description Task automatically generates a title, description, and keyword tags for an image, video, or audio file.

It uses AI to analyze the content and create concise, human-readable metadata suitable for cataloging, search, or recommendation features.

When complete, it creates an Intelligence file with kind: "description" and a .json output containing the generated fields.

Example Output

{
  "id": "file_abcdef123456",
  "object": "intelligence",
  "kind": "description",
  "title": "Sunset over the Alps",
  "description": "A scenic photo of a mountain range with orange clouds and warm evening light. Ideal for travel or nature collections.",
  "tags": ["sunset", "mountains", "nature", "travel", "landscape"],
  "language": "en",
  "confidence": 0.94,
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z"
}

Creating a Description Task

You can create a Description task from any uploaded file or public URL.

import { IttybitClient } from "@ittybit/sdk";

const ittybit = new IttybitClient({
  apiKey: process.env.ITTYBIT_API_KEY!
});

const task = await ittybit.tasks.create({
  kind: "description",
  url: "https://example.com/photo.jpg",
  description: "Generate title and tags for an image",
  webhook_url: "https://your-app.com/description-webhook"
});

console.log("Task created:", task.id);
console.log("Status:", task.status);

When processing completes, ittybit will create an Intelligence file and send the results to your webhook_url, if provided.

Webhook Example

app.post("/description-webhook", async (req, res) => {
  const { kind, status, results } = req.body || {};

  if (kind !== "description" || status !== "completed") {
    return res.status(200).send("Not a completed Description task");
  }

  console.log("Generated title:", results.title);
  console.log("Description:", results.description);
  console.log("Tags:", results.tags);

  res.status(200).send("Metadata saved");
});

This structure mirrors real-world implementations like

Auto-generate titles, descriptions, and tags for Supabase uploads.

File Structure

Property	Type	Description
id	string	Unique ID for the Intelligence file.
object	string	Always `intelligence`.
kind	string	Always `description`.
title	string	Generated title for the file.
description	string	AI-generated summary or caption of the content.
tags	array	List of keyword tags inferred from the file.
language	string	Detected or target language code (ISO 639-1).
confidence	number	Average confidence score for generated metadata.
created / updated	string (ISO 8601)	Timestamps for creation and update.

Supported Inputs

Description tasks support the following input types:

Image files (.jpg, .jpeg, .png, .webp)
Video files (.mp4, .mov, .webm)
Audio files (.mp3, .wav, .m4a)

Common Use Cases

Automatic media cataloging
SEO-friendly titles and tags
AI-generated captions for galleries or feeds
Metadata enrichment for content management systems

Example Workflow Automation

You can include Description tasks in Automations to process all new media files:

{
  "name": "Auto-describe new uploads",
  "trigger": {
    "kind": "event",
    "event": "media.created"
  },
  "workflow": [
    { "kind": "description", "ref": "ai-description" }
  ],
  "status": "active"
}

This setup automatically generates titles, descriptions, and tags for each uploaded media item.

Description

On this page