Oatda vision analysis

OATDA Vision Analysis

Analyze images using vision-capable AI models through OATDA's unified API.

API Key Resolution

All commands need the OATDA API key. Resolve it inline for each exec call:

export OATDA_API_KEY="${OATDA_API_KEY:-$(cat ~/.oatda/credentials.json 2>/dev/null | jq -r '.profiles[.defaultProfile].apiKey' 2>/dev/null)}"

If the key is empty or null, tell the user to get one at https://oatda.com and configure it.

Security: Never print the full API key. Only verify existence or show first 8 chars.

Model Mapping

User says	Provider	Model
gpt-4o (default)	openai	gpt-4o
gpt-4o-mini	openai	gpt-4o-mini
gpt-5	openai	gpt-5
claude, sonnet	anthropic	claude-sonnet-4-5-20250929
opus	anthropic	claude-opus-4-5-20251101
gemini	google	gemini-3-pro-preview
gemini-2.5	google	gemini-2.5-pro
glm-v	zai	glm-4.6v

Default: openai / gpt-4o if no model specified.

⚠️ Models update frequently. Run oatda-list-models with type=vision for the latest vision models.

⚠️ Models update frequently. If a model ID fails, query oatda-list-models with ?type=chat for the latest vision-capable models.

Image URL Validation

• Accept: https:// URLs or data:image/ base64 data URIs
• Reject: http:// URLs, local file paths, internal IPs (localhost, 127.0.0.1, 169.254.x.x)
• If user provides a local file, suggest converting to base64 first

API Call

CRITICAL: The canonical endpoint is /api/v1/llm (NOT /api/v1/llm/generate-image — that's for image generation). The body uses a contents array, NOT a simple prompt string. The legacy /api/v1/llm/image alias is deprecated but accepts the same body for backward compatibility.

export OATDA_API_KEY="${OATDA_API_KEY:-$(cat ~/.oatda/credentials.json 2>/dev/null | jq -r '.profiles[.defaultProfile].apiKey' 2>/dev/null)}" && \
curl -s -X POST "https://oatda.com/api/v1/llm" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OATDA_API_KEY" \
  -d '{
    "provider": "<PROVIDER>",
    "model": "<MODEL>",
    "contents": [
      {"type": "text", "text": "<ANALYSIS_PROMPT>"},
      {"type": "image", "image": {"url": "<IMAGE_URL>", "detail": "auto"}}
    ]
  }'

Optional Parameters (add to body)

• temperature: 0-2, default 0.7
• maxTokens: Max response tokens

Image Detail Levels

• "auto" — Let the model decide (default)
• "low" — Faster, cheaper, less detail
• "high" — More detail, higher cost (recommended for OCR)

Response Format

{
  "success": true,
  "provider": "openai",
  "model": "gpt-4o",
  "response": "The image shows a sunset over...",
  "usage": {
    "promptTokens": 800,
    "completionTokens": 200,
    "totalTokens": 1000
  },
  "costs": {
    "inputCost": 0.004,
    "outputCost": 0.006,
    "totalCost": 0.01,
    "currency": "USD"
  }
}

Present the response field to the user. Optionally mention token usage and cost.

Error Handling

HTTP Status	Meaning	Action
401	Invalid API key	Tell user to check their key
400	Bad request	Check image URL is valid HTTPS, model supports vision
429	Rate limited	Wait 5 seconds and retry once

Example

User: "Describe this image: https://example.com/photo.jpg"

export OATDA_API_KEY="${OATDA_API_KEY:-$(cat ~/.oatda/credentials.json 2>/dev/null | jq -r '.profiles[.defaultProfile].apiKey' 2>/dev/null)}" && \
curl -s -X POST "https://oatda.com/api/v1/llm" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OATDA_API_KEY" \
  -d '{
    "provider": "openai",
    "model": "gpt-4o",
    "contents": [
      {"type": "text", "text": "Describe this image in detail"},
      {"type": "image", "image": {"url": "https://example.com/photo.jpg", "detail": "auto"}}
    ]
  }'

Notes

• Canonical endpoint is /api/v1/llm — NOT /api/v1/llm/generate-image (that's for generation). Legacy /api/v1/llm/image alias is deprecated but accepts the same body.
• Body uses contents array format, NOT a simple prompt string
• Only HTTPS image URLs accepted — no HTTP, no local paths
• Image tokens are included in prompt token count and affect cost
• For OCR tasks, use "detail": "high"
• Use oatda-generate-image for creating images
• Use oatda-list-models for available vision models