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

# LLM Multimodal Helpers

> One-call vision, audio, and video analysis with structured JSON output. No prompts required.

These helpers wrap multimodal LLMs with hidden system prompts so you can get
structured output from a single URL. The hidden prompts are not configurable
and never returned. Output is always strict JSON.

The underlying models powering each helper are an internal implementation
detail of AdSkull's multimodal stack — tuned for cost and latency, swapped
transparently over time, and not part of the public contract. The `model`
field in helper responses is a stable, generic label (`adskull-vision`,
`adskull-audio`, `adskull-video`) and is safe to log or store.

## Endpoints

| Method | Endpoint                   | Purpose                                                  |
| ------ | -------------------------- | -------------------------------------------------------- |
| `POST` | `/v1/llm/vision/describe`  | Describe an image + tag + OCR.                           |
| `POST` | `/v1/llm/audio/transcribe` | Transcribe audio with optional timestamps / diarization. |
| `POST` | `/v1/llm/video/describe`   | Summarize a video, list shots, OCR on-screen text.       |

You can override the underlying model per request via the `model` field with
any AdSkull model from `GET /v1/llm/models` that supports the relevant
modality. Override only when you need a specific public model's behavior —
the default backend is already optimized for the helper's task.

## Vision

```bash theme={"theme":"github-dark"}
curl https://api.adskull.io/v1/llm/vision/describe \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image_url": "https://example.com/ad.jpg", "detail": "long" }'
```

Response:

```json theme={"theme":"github-dark"}
{
  "id": "llm_...",
  "object": "vision.description",
  "model": "adskull-vision",
  "description": "Iced coffee can on a marble counter…",
  "tags": ["coffee", "product photography", "minimalist"],
  "ocr_text": "COLD BREW",
  "usage": { "input_tokens": 3120, "output_tokens": 187, "cached_tokens": 0, "millicredits_charged": 612, "credits_charged": 0.612 }
}
```

Parameters:

| Field       | Type                        | Required | Notes                                                                                                             |
| ----------- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `image_url` | string                      | Yes      | Public HTTPS URL. SSRF-validated.                                                                                 |
| `model`     | string                      | No       | Optional override. Any image-capable model from `GET /v1/llm/models`. Leave unset to use AdSkull's tuned default. |
| `detail`    | `auto` \| `short` \| `long` | No       | Length hint.                                                                                                      |
| `language`  | string                      | No       | Output language. Default `en`.                                                                                    |

## Audio

```bash theme={"theme":"github-dark"}
curl https://api.adskull.io/v1/llm/audio/transcribe \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audio_url": "https://example.com/podcast.mp3", "diarize": true, "timestamps": "sentence" }'
```

Response:

```json theme={"theme":"github-dark"}
{
  "id": "llm_...",
  "object": "audio.transcription",
  "model": "adskull-audio",
  "transcript": "Welcome back to the show…",
  "language_detected": "en",
  "segments": [
    { "start": 0.0, "end": 2.4, "speaker": "A", "text": "Welcome back to the show." }
  ],
  "usage": { ... }
}
```

Parameters: `audio_url` (required), `model`, `language` (default `auto`),
`diarize` (default `false`), `timestamps` (`none` | `sentence` | `word`).

## Video

```bash theme={"theme":"github-dark"}
curl https://api.adskull.io/v1/llm/video/describe \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "video_url": "https://example.com/ad.mp4", "detail": "long" }'
```

Response:

```json theme={"theme":"github-dark"}
{
  "id": "llm_...",
  "object": "video.description",
  "model": "adskull-video",
  "summary": "30-second iced coffee ad…",
  "duration_seconds": 30,
  "shots": [
    { "start": 0, "end": 4, "description": "Logo intro on white." },
    { "start": 4, "end": 12, "description": "Hands pouring ice into glass." }
  ],
  "on_screen_text": ["COLD BREW", "TRY IT"],
  "spoken_transcript": "Sometimes you just need a cold one…",
  "usage": { ... }
}
```

Parameters: `video_url` (required), `model`, `detail`, `frame_sample_rate`.

<Note>
  The hidden system prompts are versioned by AdSkull; we may improve them over time but the
  output schema is part of our public contract and won't change without a
  deprecation window.
</Note>