**Cost**: 5 credits per successful call.

Image Describe supports two input modes:

1. **JSON URL mode**: send `application/json` with the existing URL field.
2. **Direct upload mode**: send `multipart/form-data` with a local image file in the `image` field. The compatible field name `file` is also accepted for the primary image. Codia checks credits before reading and uploading the file, so insufficient-credit requests return `402` without uploading anything.

Direct upload example:

```bash
curl 'https://openapi.codia.ai/v2/open/image/describe' \
  -H 'Authorization: Bearer {codia_api_key}' \
  -F 'image=@./image.png'
```

Get a description of what's in an image — the only non-image-output endpoint in the Image Processing family. Synchronous.

## What this API is for

Auto-captioning for accessibility / SEO, classification or moderation pre-screening, building alt-text at scale, feeding image context into a downstream text-only LLM. `data.description` is always a string; depending on the selected model, it may contain either a natural-language description or a JSON-formatted prompt string. For structured layout extraction, use `image_to_design` instead.

## Request

| Field | Required | Notes |
|---|---|---|
| `image_url` | yes | Public URL of the image to describe. |
| `model` | no | Model ID. Defaults to `nano_banana_2`. Also: `nano_banana_pro` (more detailed), `ideogram_v4`. |

## Response

Unique to this endpoint (not `ImageUrlListSuccess`): `data.description` is a single string.

```json
{ "code": 0, "message": "ok", "data": { "description": "A red ceramic mug on a wooden desk beside an open notebook…" } }
```

## Billing & limits

- **5 credits per request** (higher than most image endpoints — vision-language model cost).
- Synchronous.

## Errors

Standard set.

> **Sync vs. async**
> This synchronous endpoint returns the result inline — the simplest path. For production pipelines that need webhook delivery, automatic retry with idempotency, or explicit task cancellation, call `POST /v2/open/tasks` with `operation=image_describe` instead. Inputs and credit cost are identical.

Optional user-supplied key (up to 255 chars). When set, a successful (2xx) response is cached for 7 days. A retry with the same key + identical request body returns the cached response (no extra credit charged); a retry with the same key but a different body returns 409. Use to make POST safe to retry on network failures. For multipart/form-data uploads, requests are compared by form fields and file contents, so a retried upload is replayed even though the client picks a new multipart boundary.

Idempotency-Key

image_url

Vision model that captions/describes the image. Defaults to `nano_banana_2`. All supported models currently cost 5 credits per request.

| Model | Best for | Credits |
| --- | --- | ---: |
| `nano_banana_2` | Fast, accurate captions for prompt extraction (Gemini 3.1 Flash). | 5 |
| `nano_banana_pro` | Long, detailed multi-aspect descriptions (Gemini 3 Pro). | 5 |
| `ideogram_v4` | Style, composition, typography, and object details. | 5 |

model

image

Compatible source image file field (deprecated: use `image` instead).

file

Source image URL when not uploading image

A photorealistic close-up photograph captures an amber glass dropper bottle sitting centrally on a textured beige stone slab atop a marble countertop. The bottle features a black ribbed collar and a black rubber bulb, filled with clear amber-colored liquid through which a glass pipette is visible. To the left of the bottle, a delicate sprig of fresh eucalyptus with pale green rounded leaves rests gently on the stone. To the right, a crumpled piece of soft beige linen cloth adds casual texture. The background reveals a bright, airy bathroom interior with a large white-framed window on the left, casting soft, natural morning light from the side and creating gentle shadows across the stone surface. In the soft-focus background, a vanity area is visible with a white sink, brass faucet fixtures, and dark bottles resting on a shelf against a neutral-toned wall. The composition is balanced and eye-level, emphasizing clean lines, natural materials, and an organic aesthetic. The color palette consists of warm earth tones, soft greens, amber browns, and crisp whites. The overall mood is serene, minimalist, spa-like, and calm, with a focus on tactile surfaces and peaceful interior design.

code

message

Image description string. Depending on the selected model, it may contain either a natural-language description or a JSON-formatted prompt string.

description

data

The request body is malformed or missing required parameters

The API key is missing, invalid, or revoked

Account balance is insufficient or subscription has expired

Account does not have access to this endpoint

Idempotency-Key reused with a different request body.

Rate limited. Wait for the number of seconds in the `Retry-After` header before retrying.

An unexpected error occurred on the server

Describes what is in an image in text. It is the only image API that returns text instead of an image.

Describe Image

Input

Output

Related APIs