API Reference
Complete reference for all Oceanir REST API endpoints. All endpoints require authentication via API key.
Base URL
https://oceanir.ai/api/v1Authentication
Include your API key in the x-api-key header:
x-api-key: orca_live_...Pricing and usage
API access is free and does not require a subscription. Sign in to create one key and receive 3 trial credits. Self-serve keys allow up to 10 requests per minute and 100 requests per hour.
Successful calls consume credits at the depth cost below. The standard rate is $0.80 per credit, with pack discounts down to $0.60 per credit. Failed analyses are not charged. When the balance is too low, the API returns HTTP 402. Metered overage is available only by written agreement.
Oceanir Pro includes 25 additional API-only credits each month. Active Pro members can also buy up to two 25-credit API boosters for $10 each per calendar month.
Credit top-ups
Credit costs
API calls use dedicated Pro API credits first, then the shared credit balance. The request defaults to D1 when depth is omitted.
Example: 100 credits cover 10 D3 analyses, 50 D2 analyses, or 100 D1 analyses. Mix and match as needed.
Volume examples
These examples use the fewest 100-credit top-up packs needed. There is no monthly API subscription.
| Requests / month | Depth | Credits required | 100-credit top-ups | Estimated monthly total |
|---|---|---|---|---|
| 200 | D1 | 200 | 2 | $119.98 |
| 300 | D1 | 300 | 3 | $179.97 |
| 200 | D2 | 400 | 4 | $239.96 |
| 300 | D2 | 600 | 6 | $359.94 |
Running 200–300 D3 forensic calls requires 2,000–3,000 credits. For sustained D3 or mixed production workloads, contact [email protected] for a volume agreement instead of stacking self-serve packs. See current plan details on the pricing page.
Endpoints
/api/v1/geolocate/api/v1/geolocate/{id}/api/v1/credits/api/v1/mesh/cameras/api/v1/mesh/cameras/{id}POST /api/v1/geolocate
Submit one image, get ranked coordinates with confidence and visual reasoning. Authenticate with your key in Authorization: Bearer <key> or x-api-key: <key> — both work. For retry-safe billing, reuse the same Idempotency-Key for every retry of one analysis.
Request body (JSON)
image_b64stringone ofBase64-encoded JPEG/PNG. Max 20MB.image_urlstringone ofPublic URL to fetch the image from instead.depthintegeroptional1 = Surface (region, 1 credit), 2 = Standard (block, 2), 3 = Forensic (street, 10). Default 1.Example request
curl -X POST https://oceanir.ai/api/v1/geolocate \
-H "Authorization: Bearer orca_live_YOUR_KEY" \
-H "Idempotency-Key: your-unique-request-id" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://example.com/street.jpg",
"depth": 2
}'200 response
{
"success": true,
"analysis_id": "an_8X2k...",
"location": {
"latitude": 45.7700,
"longitude": 4.8459,
"country": "France",
"city": "Lyon",
"neighborhood": "6th arrondissement",
"address": "Rue de Créqui, 69006 Lyon"
},
"confidence": 0.88,
"reasoning": "French street signage, Haussmann facades, plane trees...",
"thinking": "<step-by-step cues — depth >= 2 only>",
"visual_clues": [
{ "label": "Street sign", "detail": "Rue de Créqui", "x": 0.41, "y": 0.32 }
],
"model": "orca-2.1",
"depth": 2,
"timing_ms": 9120
}confidence is 0–1. thinking and visual_clues are returned only at depth ≥ 2.
Errors
401Missing or invalid API key.402Insufficient credits for the requested depth.422No image_b64 or image_url provided.429Rate limit exceeded — retry after retry_after seconds.502Analysis failed upstream. Retry, or lower the depth.