Media tagging

Analyze a publicly reachable image with a vision model and return a structured set of tags. The model fetches the URL directly; the image is never stored.

POST /api/v1/companion/media-tag

• Auth: Bearer key with the chat:companion scope.

Request body

Field	Type	Required	Notes
image_url	string	✓	A public https URL, 1–2000 chars. Private or internal addresses are rejected.
model	string	-	Override the vision model (1–200 chars).
debug	boolean	-	Default false. Returns { model, system_prompt, raw_output, timings_ms } alongside the tags.

Example

curl -X POST https://api.phantomrouter.ai/api/v1/companion/media-tag \
  -H "Authorization: Bearer $PHANTOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image_url": "https://example.com/photo.jpg" }'

Response

{
  "result": {
    "title": "Woman smiling on a beach at sunset",
    "clothing": "summer dress",
    "nudity_level": "fully_clothed",
    "focus": "full_body",
    "setting": "outdoors",
    "mood": "playful",
    "time_of_day": "day",
    "additional_details": "golden-hour lighting, ocean in the background"
  }
}

result fields

Field	Type	Values
title	string	A short caption.
clothing	string	Free-text description of attire.
nudity_level	enum	fully_clothed · lingerie · topless · bottomless · fully_nude
focus	enum	cleavage · breasts · ass · intimate_area · covered_with_hands · full_body · other
setting	enum	bedroom · bathroom · living_room · kitchen · outdoors · other
mood	enum	innocent · playful · horny · dominant · submissive · romantic · confident · shy · other
time_of_day	enum	day · night
additional_details	string	Any other notable details.

The vision model actually used (which may differ from a requested model on fallback) is reported as debug.model, returned only when you set debug: true.

Errors

Status	Code	When
400	INVALID_REQUEST	Body failed validation, or the URL is non-https / not publicly reachable.
402	PAYMENT_REQUIRED	Insufficient credit balance.
403	FORBIDDEN	Key lacks chat:companion.
503	SERVICE_UNAVAILABLE	The vision model failed or returned an unparseable result. Retry with backoff.