---
title: "Describe / caption an image (sync)"
method: POST
path: "/v1/images/describe"
tags: ["Images"]
---

# Describe / caption an image (sync)

`POST /v1/images/describe`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/images/describe`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://contentmaschine.ai/api/oauth/authorize`, token URL `https://contentmaschine.ai/api/oauth/token`)

Generate a natural-language description or caption (e.g. alt text) for an image in your library.
Synchronous - the description is returned directly in the response.

## Request body

- object
  - `file_uuid` string, required: UUID of an image already in your library.
  - `prompt` string: Optional instruction to steer the description.

## Response `200`

Description generated

- object
  - `success` boolean
  - `data` object
    - `text` string: The generated caption/description.
    - `generation_id` integer
    - `credits_used` number
    - `processing_time_ms` integer

## Other responses

- `401`: Missing or invalid API key
- `402`: Insufficient credits
- `403`: File belongs to another user
- `404`: Source file not found
- `default`: Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.

---

[API](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api.md) · [All operations](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/revisions/28c74f46051c?raw)