EthoswarmVitra_Image_Suite
Vitra.ai (translate.photo) image translation integration. Translates the text inside PNG/JPG images into other languages and returns a cloud URL to the translated image. Async pipeline: submit -> poll -> retrieve. Dual-header authentication (Bearer token + API key) is provider-managed by the Animoca Minds dashboard — the Mind does not read, store, or inject credentials. HTTPS cloud URLs only (max 10MB per file); language identifiers (e.g. 'spanish'), not ISO codes (e.g. 'es').
Submit an image for text translation via POST /v1/image-translator/direct-translate. The runtime fetches source_url, enforces the 10MB limit, then posts multipart/form-data with fields: file (binary), sourceLanguage (language identifier or 'auto'), targetLanguage (language identifier). Async — returns {jobId, translationVersionId} immediately; you MUST call Vitra_GetTranslationStatus to retrieve the translatedImageUrl. NEVER pass ISO codes ('es', 'fr', 'hi') — pass the identifier the API returned in the 'value' field of Vitra_ListLanguages (typically a language name like 'spanish', 'french', 'hindi'). Auto-detect aliases ('auto-detect', 'Auto Detect', 'autodetect', 'detect') are normalized to the literal 'auto' before send. This endpoint IS called with X-Client-Source: agent — errors return as HTTP 200 with {success:false, originalStatus, code, message}: unsupported language, file too large, insufficient credits, auth rejected (originalStatus 401/403), invalid URL. Hard reject inputs whose scheme is not https or that exceed 10MB.
Poll the async translation result via GET /v1/image-translator/{jobId}/translations/{translationVersionId}. Returns {status, translatedImageUrl}. Status values include 'pending', 'translating', 'completed' (also 'complete', 'done', 'success', 'succeeded', 'finished'), and failure states ('failed', 'error', 'errored', 'cancelled', 'canceled'). translatedImageUrl is the final cloud URL the Mind returns to the Steward — only present when status is in the completed family. Recommended polling cadence: every 5 seconds within a 300-second total budget. NEVER expose jobId or translationVersionId to the Steward as a result — they are intermediate identifiers. On non-completed terminal status (failure family), surface the actual payload code+message rather than guessing. This endpoint IS called with X-Client-Source: agent — auth errors surface as HTTP 200 with {success:false, originalStatus: 401|403}. Other errors: standard 4xx/5xx with payload.
List languages supported by the vitra.ai image translator via GET /v1/language/list. Returns an array of language objects. The canonical identifier field is 'value' (response normalization also accepts 'code', 'key', 'language', 'id' as fallbacks) — whatever string sits in that field is the EXACT identifier the submit endpoint accepts (e.g. 'spanish', 'french', 'hindi'). The 'name' field carries the human-readable label. Use this BEFORE submitting whenever you are unsure of the exact target/source language identifier, or when the Steward gives an ISO code ('es', 'fr') that needs to be mapped. Response is cacheable for ~1 hour. NOTE: this endpoint is called WITHOUT the X-Client-Source: agent header — errors arrive as standard non-2xx HTTP (401/403/4xx with payload), NOT as 200+success:false. Errors: 401/403 auth rejected; other 4xx/5xx return the API payload verbatim.