Describe an image

Create a reviewed image-to-production-notes Block with owned media and host-controlled vision execution.

Use runtime: "capability" with operation: "image.describe" when a Block must inspect one image and return plain text. This is the portable boundary for visual analysis: the Block declares its image input, analysis instructions, output, tests, and license; StillMade owns image loading, provider credentials, model/payment selection, approval, accounting, and the retained execution record.

The downloaded SDK includes examples/describe-image.stillmade.json and packages/block-sdk/image-description-example.js.

{
  "manifest": {
    "schemaVersion": 1,
    "sdkVersion": "0.1.0",
    "id": "example.describe-image",
    "version": "1.0.0",
    "name": "Describe an image",
    "description": "Turn one owned image into concise production-ready visual notes.",
    "kind": "task",
    "runtime": "capability",
    "entry": "src/capability.json",
    "license": "MIT",
    "inputs": {"image": {"type": "image", "primary": true}},
    "outputs": {"description": {"type": "text", "primary": true, "role": "visual_description"}},
    "permissions": {"project": [], "capabilities": ["image.describe"], "network": [], "filesystem": [], "secrets": []},
    "ui": [{"control": "asset", "port": "image"}]
  },
  "capability": {
    "schemaVersion": 1,
    "operation": "image.describe",
    "image": {"$input": "image"},
    "instruction": "Describe only visibly supported subject matter, composition, lighting, color, texture, camera feel and visual style. Return concise production-ready plain text.",
    "maxTokens": 700,
    "output": "description"
  },
  "tests": [{
    "name": "Blue image",
    "input": {"image": {"width": 1, "height": 1, "data": [20, 80, 200, 255]}},
    "expectations": {"description": {"kind": "text", "minLength": 20, "maxLength": 32768, "includes": ["blue"]}}
  }]
}

Declare exactly one image input (or one image[] input to describe or compare one to four images together, in order) and one text output. The descriptor contains exactly schemaVersion, operation, image, instruction, maxTokens, and output. image.$input names the declared image port. Instructions must contain 1–8,000 characters and maxTokens must be 1–4,096. Provider names, endpoints, keys, payment settings, arbitrary URLs, and executable code do not belong in the descriptor.

Fixture inputs may use bounded RGBA pixels for offline contract validation. Real runs use a persistent image reference selected through StillMade. The trusted host requires the referenced media to belong to the signed-in account, reads and bounds the stored bytes, canonicalizes the image to PNG, and sends that image through the exact approved provider request. Block code never receives credentials or storage access.

Tests describe nondeterministic text expectations: kind:"text", ordered minLength and maxLength, and up to eight literal includes phrases. They do not contain fabricated descriptions presented as provider evidence. Offline validation and packaging inspect the contract and report that live review remains required. In StillMade, the creator runs every fixture and a separate sample, reviews the output, and confirms the import.

prepareCapabilityInvocation returns {operation:"image.describe",image,instruction,maxTokens}. The host returns the named text output through the same capability result, quote, review, project execution, cancellation, failure, and receipt flow used by other hosted Blocks. A completed text record proves the exact package, input, selection, and output passed validation; it does not prove that every sentence is factually correct, so the user reviews the description before using it downstream.