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 | | claude, sonnet | anthropic | claude-3-5-sonnet | | gemini | google | gemini-2.0-flash | | gemini-1.5 | google | gemini-1.5-pro |

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

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

Image URL Validation

API Call

CRITICAL: The endpoint is /api/v1/llm/image (NOT /api/v1/llm/generate-image — that's for image generation). The body uses a contents array, NOT a simple prompt string.

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/image" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OATDA_API_KEY" \
  -d '{
    "provider": "",
    "model": "",
    "contents": [
      {"type": "text", "text": ""},
      {"type": "image", "image": {"url": "", "detail": "auto"}}
    ]
  }'

Optional Parameters (add to body)

Image Detail Levels

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/image" \
  -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

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/image" \
  -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"}}
    ]
  }'