Skip to content
Sup

Integrating AI

Sup provides AI capabilities through the sup.ai interface. You can use AI for text generation, image generation and analysis, and structured responses.

Basic Prompting

The simplest way to use AI is with text prompts:

function main() {
  // Simple text generation (uses OpenRouter with GPT-4o-mini by default)
  return sup.ai.prompt("Write a haiku about frogs");
}

Detailed Instructions

You can provide more detailed instructions for better results. Moving your prompt to the top of your code will also make it easier to edit in the UI:

const PROMPT = `
  Write a creative story based on these requirements:
  - Set in a cyberpunk future
  - Include a plot twist
  - Maximum 3 paragraphs
  - Focus on character development
`;


function main() {
  return sup.ai.prompt(PROMPT);
}

Structured Output

Use schemas to get structured, predictable responses:

function main() {
  const response = sup.ai.prompt(
    "Analyze the sentiment of this text:",
    sup.input.text,
    {
      schema: {
        sentiment: {
          type: "string",
          enum: ["positive", "neutral", "negative"],
          description: "The overall sentiment",
        },
        confidence: {
          type: "number",
          minimum: 0,
          maximum: 1,
          description: "Confidence score",
        },
        keywords: {
          type: "array",
          items: [{ type: "string" }],
          maxItems: 5,
          description: "Key emotional words",
        },
      },
    }
  );


  return `
    Sentiment: ${response.sentiment}
    Confidence: ${response.confidence}
    Keywords: ${response.keywords.join(", ")}
  `;
}

Complex Schemas

You can create more complex schemas for detailed analysis:

function main() {
  return sup.ai.prompt("Analyze this movie review:", sup.input.text, {
    schema: {
      summary: {
        type: "string",
        maxLength: 200,
        description: "Brief summary of the review",
      },
      rating: {
        type: "number",
        minimum: 0,
        maximum: 10,
        description: "Inferred rating out of 10",
      },
      aspects: {
        type: "object",
        properties: {
          acting: { type: "string" },
          plot: { type: "string" },
          visuals: { type: "string" },
        },
        description: "Analysis of specific aspects",
      },
      pros: {
        type: "array",
        items: [{ type: "string" }],
        maxItems: 3,
        description: "Main positive points",
      },
      cons: {
        type: "array",
        items: [{ type: "string" }],
        maxItems: 3,
        description: "Main negative points",
      },
    },
  });
}

Working with Images

AI can be used to generate and edit images.

Image Generation

function main() {
  // Generate with default model (Gemini 2.5 Flash - fast)
  return sup.ai.image.create("pixel art of a rabbit in a frog costume");
}
function main() {
  // Use best quality model (OpenAI)
  return sup.ai.image.create("hyperrealistic portrait", { model: "best" });
}

Image Editing

function main() {
  // Edit an existing image
  const image = sup.input.image;
  return sup.ai.image.edit(image, "make it more colorful and add a rainbow");
}

Image Analysis

AI can analyze images and generate text about them:

function main() {
  const image = sup.input.image;
  if (!image) return "Please provide an image";


  // Basic image description
  return sup.ai.image.interpret(image, "Describe this image in detail");
}

Image Analysis Tasks

// Object detection
function detectObjects() {
  return sup.ai.prompt("List all objects in this image:", sup.input.image, {
    schema: {
      objects: {
        type: "array",
        items: [
          {
            type: "object",
            properties: {
              name: { type: "string" },
              confidence: { type: "number" },
            },
          },
        ],
      },
    },
  });
}


// Scene analysis
function analyzeScene() {
  return sup.ai.prompt("Analyze this scene:", sup.input.image, {
    schema: {
      setting: { type: "string" },
      timeOfDay: { type: "string" },
      mood: { type: "string" },
      activities: {
        type: "array",
        items: [{ type: "string" }],
      },
    },
  });
}

Working with Video

AI can generate videos from text, images, or existing videos.

Text-to-Video

function main() {
  // Generate video from text prompt
  return sup.ai.video.create("A cat playing piano");
}

Image-to-Video

function main() {
  // Animate an image
  const image = sup.input.image;
  return sup.ai.video.create("The person starts walking", image);
}

Video Options

function main() {
  // Generate with specific options
  return sup.ai.video.create(
    "Waves crashing on a beach at sunset",
    {
      model: "best",       // "fast" or "best" (default: "fast")
      duration: 6,         // 4, 6, or 8 seconds (default: 4)
      aspectRatio: "16:9", // Options: "16:9", "9:16" (default: "16:9")
      resolution: "1080p"  // Options: "720p", "1080p" (default: "720p")
    }
  );
}

Available Options:

  • model: Video generation model
    • "fast" - Veo 3.1 Fast, quicker generation (default)
    • "best" - Veo 3.1, highest quality output
    • Full model names also accepted: "veo-3.1-fast-generate-001", "veo-3.1-generate-001"
    • Legacy preview aliases are still accepted and mapped to the GA endpoints
  • duration: Video length in seconds
    • 4 - Short clip (default)
    • 6 - Medium clip
    • 8 - Longer clip
  • aspectRatio: Video dimensions
    • "16:9" - Landscape/widescreen (default)
    • "9:16" - Portrait/vertical (for mobile)
  • resolution: Video quality
    • "720p" - HD quality, faster generation (default)
    • "1080p" - Full HD quality, higher quality output

Video Extension

function main() {
  // Create initial video
  const video1 = sup.ai.video.create("Person juggling");


  // Extend or modify it
  const video2 = sup.ai.video.create("They drop all the balls", video1);


  return video2;
}

Video Analysis

AI can analyze videos and generate text descriptions:

function main() {
  const video = sup.input.video;
  if (!video) return "Please provide a video";
  return sup.ai.video.interpret(video, "Describe what happens in this video");
}

Working with Audio

AI can understand and interpret audio files, including speech transcription and audio description:

function main() {
  const audio = sup.input.audio;
  return sup.ai.audio.interpret(audio);
}

Custom Audio Analysis

Use custom prompts for specific audio analysis tasks:

function main() {
  const audio = sup.input.audio;


  // Analyze music
  const musicAnalysis = sup.ai.audio.interpret(
    audio,
    "What musical instruments and genre can you identify in this audio?"
  );


  // Focus on speech transcription
  const transcript = sup.ai.audio.interpret(
    audio,
    "Please provide an accurate transcript of all spoken words."
  );


  return { musicAnalysis, transcript };
}

Context-Aware AI

Use promptWithContext to give the AI access to conversation context:

function main() {
  // AI gets context about users, chat, and replied to message
  return sup.ai.promptWithContext("Summarize the discussion so far");
}

Advanced Features

Using Alternative AI Providers

Sup provides access to multiple AI providers through extensions:

function main() {
  // Use OpenRouter directly (access to Claude, GPT, and other models)
  return sup.ex.openrouter("anthropic/claude-3-haiku", "Write a haiku about robots");
}
function main() {
  // Use Hugging Face models directly
  return sup.ex.huggingface(
    "microsoft/DialoGPT-medium",
    "Tell me about artificial intelligence",
    sup.secret("HUGGINGFACE_API_KEY")
  );
}

Temperature Control

Adjust creativity vs. predictability:

function main() {
  // More creative (temperature 0.9)
  const creative = sup.ai.prompt("Write a story about a robot.", {
    temperature: 0.9,
  });


  // More focused (temperature 0.2)
  const focused = sup.ai.prompt("Write a story about a robot.", {
    temperature: 0.2,
  });


  return `
    Creative: ${creative}
    Focused: ${focused}
  `;
}

Best Practices

  1. Clear Instructions

    // ❌ Vague
    sup.ai.prompt("Analyze this");
    

    // ✅ Clear and specific
    sup.ai.prompt(`
      Analyze this text and provide:
      1. Main themes
      2. Key arguments
      3. Overall tone
    `);

  2. Structured Output

    Use schemas to get predictable, typed responses. Schemas use a simplified JSON Schema format where you define properties directly (not wrapped in type: "object"):

    // ❌ Unstructured
    const response = sup.ai.prompt("Is this positive?");
    

    // ✅ Structured with schema
    const response = sup.ai.prompt("Analyze sentiment:", text, {
      schema: {
        sentiment: {
          type: "string",
          enum: ["positive", "negative"],
        },
      },
    });

Web Scraping with AI

Sup provides sup.scrape to combine web scraping with AI processing:

function main() {
  // Basic scraping (returns markdown)
  const content = sup.scrape("https://example.com/article");


  // Scrape with AI processing
  const summary = sup.scrape(
    "https://example.com/article",
    "Summarize the main points of this article"
  );


  return summary;
}

Common Use Cases

// News summarization
function summarizeNews() {
  return sup.scrape(
    "https://news-site.com/article",
    `Analyze this news article and provide:
     - Main topic
     - Key facts
     - Important quotes
     - Potential bias`
  );
}


// Data extraction
function extractData() {
  return sup.scrape("https://product-page.com", {
    schema: {
      productName: { type: "string" },
      price: { type: "number" },
      features: {
        type: "array",
        items: [{ type: "string" }],
      },
      availability: {
        type: "string",
        enum: ["in stock", "out of stock", "pre-order"],
      },
    },
  });
}


// Historical events
function getHistory() {
  return sup.scrape(
    "https://en.wikipedia.org/wiki/Wikipedia:On_this_day/Today",
    "List the 3 most significant historical events from this page"
  );
}