Ztrace
ZTRACE

SDKs & Libraries

Ztrace Documentation

Official SDKs for popular programming languages. All SDKs provide full type support, automatic retries, and convenient helper methods.

Installation

Node.js / TypeScript

Bash
npm install @ztrace/sdk

Python

Bash
pip install ztrace

Node.js SDK

node-example.ts
TypeScript
1<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>import</span></span> { <span class="text-yellow-300">Ztrace</span> } <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>from</span></span> <span class="text-emerald-<span class="text-orange-400">400</span>">'@ztrace/sdk'</span>;
2 
3// Initialize the client with your API key
4<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> client = <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>new</span> <span class="text-blue-400"><span class="text-yellow-300">Ztrace</span></span>({
5  apiKey: process.<span class="text-cyan-300">env</span>.<span class="text-cyan-300">ZTRACE_API_KEY</span>,
6  region: <span class="text-emerald-<span class="text-orange-400">400</span>">'us-east-<span class="text-orange-400">1</span>'</span>,
7  timeout: <span class="text-orange-400">30000</span>,
8  retries: <span class="text-orange-400">3</span>
9});
10 
11// Analyze an image and get location data
12<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> result = <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>await</span></span> client.<span class="text-blue-400">analyze</span>({
13  image: <span class="text-emerald-<span class="text-orange-400">400</span>">'./path/to/image.<span class="text-cyan-300">jpg</span>'</span>,
14  options: {
15    confidence_threshold: <span class="text-orange-400">0.<span class="text-cyan-300">85</span></span>,
16    include_metadata: <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>true</span>,
17    include_features: <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>true</span>,
18    include_landmarks: <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>true</span>
19  }
20});
21 
22console.<span class="text-blue-400">log</span>(<span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">Location</span>:'</span>, result.<span class="text-cyan-300">location</span>);
23// Output: { lat: 35.6762, lng: 139.6503, confidence: 0.947 }
24 
25console.<span class="text-blue-400">log</span>(<span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">Place</span>:'</span>, result.<span class="text-cyan-300">place_name</span>);
26// Output: "Shibuya Crossing, Tokyo, Japan"

Python SDK

python-example.py
Python
1# Ztrace Python SDK - Complete Example
2<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>from</span></span> ztrace <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>import</span></span> <span class="text-yellow-300">ZtraceClient</span>, <span class="text-yellow-300">AnalysisOptions</span>, <span class="text-yellow-300">BatchConfig</span>
3<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>from</span></span> ztrace.<span class="text-cyan-300">models</span> <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>import</span></span> <span class="text-yellow-300">Location</span>, <span class="text-yellow-300">AnalysisResult</span>
4<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>import</span></span> asyncio
5 
6# Initialize client with configuration
7client = <span class="text-blue-400"><span class="text-yellow-300">ZtraceClient</span></span>(
8    api_key=<span class="text-emerald-<span class="text-orange-400">400</span>">"your-api-key"</span>,
9    region=<span class="text-emerald-<span class="text-orange-400">400</span>">"us-east-<span class="text-orange-400">1</span>"</span>,
10    timeout=<span class="text-orange-400">30</span>,
11    max_retries=<span class="text-orange-400">3</span>
12)
13 
14# Single image analysis
15<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>async</span></span> <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>def</span> <span class="text-blue-400">analyze_single_image</span>():
16    result: <span class="text-yellow-300">AnalysisResult</span> = <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>await</span></span> client.<span class="text-blue-400">analyze</span>(
17        image_path=<span class="text-emerald-<span class="text-orange-400">400</span>">"./image.<span class="text-cyan-300">jpg</span>"</span>,
18        options=<span class="text-blue-400"><span class="text-yellow-300">AnalysisOptions</span></span>(
19            confidence_threshold=<span class="text-orange-400">0.<span class="text-cyan-300">85</span></span>,
20            include_features=<span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class="text-yellow-300">True</span></span>,
21            include_landmarks=<span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class="text-yellow-300">True</span></span>,
22            include_weather=<span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class="text-yellow-300">True</span></span>
23        )
24    )
25    
26    <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>print</span>(f<span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Location</span>: {result.<span class="text-cyan-300">location</span>.<span class="text-cyan-300">lat</span>}, {result.<span class="text-cyan-300">location</span>.<span class="text-cyan-300">lng</span>}"</span>)
27    <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>print</span>(f<span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Place</span>: {result.<span class="text-cyan-300">place_name</span>}"</span>)
28    <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>print</span>(f<span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Confidence</span>: {result.<span class="text-cyan-300">confidence</span>:.<span class="text-orange-400">1</span>%}"</span>)
29    <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>print</span>(f<span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Country</span>: {result.<span class="text-cyan-300">country</span>}"</span>)
30    <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>print</span>(f<span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Features</span>: {', '.<span class="text-blue-400">join</span>(result.<span class="text-cyan-300">features</span>)}"</span>)
31    
32    <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>if</span></span> result.<span class="text-cyan-300">landmarks</span>:
33        <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>for</span></span> landmark <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>in</span></span> result.<span class="text-cyan-300">landmarks</span>:
34            <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>print</span>(f<span class="text-emerald-<span class="text-orange-400">400</span>">"  - {landmark.<span class="text-cyan-300">name</span>} ({landmark.<span class="text-cyan-300">distance_m</span>}m away)"</span>)
35    
36    <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>return</span></span> result
37 
38# Batch processing with async
39<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>async</span></span> <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>def</span> <span class="text-blue-400">batch_analyze</span>():
40    images = [
41        <span class="text-emerald-<span class="text-orange-400">400</span>">"./images/img1.<span class="text-cyan-300">jpg</span>"</span>,
42        <span class="text-emerald-<span class="text-orange-400">400</span>">"./images/img2.<span class="text-cyan-300">jpg</span>"</span>,
43        <span class="text-emerald-<span class="text-orange-400">400</span>">"https://example.<span class="text-cyan-300">com</span>/img3.<span class="text-cyan-300">jpg</span>"</span>
44    ]
45    
46    config = <span class="text-blue-400"><span class="text-yellow-300">BatchConfig</span></span>(
47        parallel=<span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class="text-yellow-300">True</span></span>,
48        max_concurrency=<span class="text-orange-400">5</span>,
49        on_progress=<span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>lambda</span> p: <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>print</span>(f<span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Progress</span>: {p.<span class="text-cyan-300">completed</span>}/{p.<span class="text-cyan-300">total</span>}"</span>)
50    )
51    
52    results = <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>await</span></span> client.<span class="text-blue-400">batch_analyze</span>(images, config=config)
53    
54    <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>for</span></span> result <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>in</span></span> results:
55        <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>if</span></span> result.<span class="text-cyan-300">success</span>:
56            <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>print</span>(f<span class="text-emerald-<span class="text-orange-400">400</span>">"{result.<span class="text-cyan-300">image_id</span>}: {result.<span class="text-cyan-300">location</span>}"</span>)
57        <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>else</span></span>:
58            <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>print</span>(f<span class="text-emerald-<span class="text-orange-400">400</span>">"{result.<span class="text-cyan-300">image_id</span>}: <span class="text-yellow-300">Failed</span> - {result.<span class="text-cyan-300">error</span>}"</span>)
59    
60    <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>return</span></span> results
61 
62# Feature extraction only
63<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>async</span></span> <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>def</span> <span class="text-blue-400">extract_features</span>():
64    features = <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>await</span></span> client.<span class="text-blue-400">extract_features</span>(
65        image_path=<span class="text-emerald-<span class="text-orange-400">400</span>">"./image.<span class="text-cyan-300">jpg</span>"</span>,
66        feature_types=[<span class="text-emerald-<span class="text-orange-400">400</span>">"landmarks"</span>, <span class="text-emerald-<span class="text-orange-400">400</span>">"text"</span>, <span class="text-emerald-<span class="text-orange-400">400</span>">"objects"</span>, <span class="text-emerald-<span class="text-orange-400">400</span>">"climate"</span>]
67    )
68    
69    <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>print</span>(<span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Detected</span> <span class="text-yellow-300">Features</span>:"</span>)
70    <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>for</span></span> feature <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>in</span></span> features.<span class="text-cyan-300">items</span>:
71        <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>print</span>(f<span class="text-emerald-<span class="text-orange-400">400</span>">"  {feature.<span <span class="</span>text-purple-<span class="text-orange-400">400</span> font-medium<span class="text-emerald-<span class="text-orange-400">400</span>">">class</span>="</span>text-purple-<span class="text-orange-400">400</span> font-medium<span class="text-emerald-<span class="text-orange-400">400</span>">">type</span>}: {feature.<span class="text-cyan-300">value</span>} (conf: {feature.<span class="text-cyan-300">confidence</span>:.<span class="text-cyan-300">2f</span>})"</span>)
72 
73# Run examples
74<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>if</span></span> __name__ == <span class="text-emerald-<span class="text-orange-400">400</span>">"__main__"</span>:
75    asyncio.<span class="text-blue-400">run</span>(<span class="text-blue-400">analyze_single_image</span>())

cURL Examples

curl-examples.sh
Bash
1# Ztrace API - cURL Examples
2 
3# 1. Analyze image from URL
4curl -<span class="text-yellow-300">X</span> <span class="text-yellow-300">POST</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"https://api.<span class="text-cyan-300">ztrace</span>.<span class="text-cyan-300">ai</span>/v2/analyze"</span> \
5  -<span class="text-yellow-300">H</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Authorization</span>: <span class="text-yellow-300">Bearer</span> $ZTRACE_API_KEY"</span> \
6  -<span class="text-yellow-300">H</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Content</span>-<span class="text-yellow-300">Type</span>: application/json"</span> \
7  -d '{
8    <span class="text-emerald-<span class="text-orange-400">400</span>">"image_url"</span>: <span class="text-emerald-<span class="text-orange-400">400</span>">"https://example.<span class="text-cyan-300">com</span>/image.<span class="text-cyan-300">jpg</span>"</span>,
9    <span class="text-emerald-<span class="text-orange-400">400</span>">"options"</span>: {
10      <span class="text-emerald-<span class="text-orange-400">400</span>">"model"</span>: <span class="text-emerald-<span class="text-orange-400">400</span>">"geo-v3"</span>,
11      <span class="text-emerald-<span class="text-orange-400">400</span>">"confidence_threshold"</span>: <span class="text-orange-400">0.<span class="text-cyan-300">85</span></span>,
12      <span class="text-emerald-<span class="text-orange-400">400</span>">"include_features"</span>: <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>true</span>,
13      <span class="text-emerald-<span class="text-orange-400">400</span>">"include_landmarks"</span>: <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>true</span>
14    }
15  }'
16 
17# Response:
18# {
19#   "id": "analysis_abc123",
20#   "status": "completed",
21#   "location": {
22#     "lat": 35.6762,
23#     "lng": 139.6503,
24#     "accuracy_m": 150,
25#     "confidence": 0.947
26#   },
27#   "place_name": "Shibuya Crossing, Tokyo, Japan",
28#   "country": "JP",
29#   "country_name": "Japan",
30#   "features": ["urban", "crosswalk", "japanese_signage", "crowd"],
31#   "landmarks": [
32#     {"name": "Shibuya 109", "distance_m": 85},
33#     {"name": "Hachiko Statue", "distance_m": 120}
34#   ],
35#   "processing_time_ms": 1243
36# }
37 
38# 2. Analyze with file upload
39curl -<span class="text-yellow-300">X</span> <span class="text-yellow-300">POST</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"https://api.<span class="text-cyan-300">ztrace</span>.<span class="text-cyan-300">ai</span>/v2/analyze"</span> \
40  -<span class="text-yellow-300">H</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Authorization</span>: <span class="text-yellow-300">Bearer</span> $ZTRACE_API_KEY"</span> \
41  -<span class="text-yellow-300">F</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"image=@./photo.<span class="text-cyan-300">jpg</span>"</span> \
42  -<span class="text-yellow-300">F</span> <span class="text-emerald-<span class="text-orange-400">400</span>">'options={"confidence_threshold": <span class="text-orange-400">0.<span class="text-cyan-300">8</span></span>}'</span>
43 
44# 3. Create batch job
45curl -<span class="text-yellow-300">X</span> <span class="text-yellow-300">POST</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"https://api.<span class="text-cyan-300">ztrace</span>.<span class="text-cyan-300">ai</span>/v2/batch"</span> \
46  -<span class="text-yellow-300">H</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Authorization</span>: <span class="text-yellow-300">Bearer</span> $ZTRACE_API_KEY"</span> \
47  -<span class="text-yellow-300">H</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Content</span>-<span class="text-yellow-300">Type</span>: application/json"</span> \
48  -d '{
49    <span class="text-emerald-<span class="text-orange-400">400</span>">"images"</span>: [
50      {<span class="text-emerald-<span class="text-orange-400">400</span>">"id"</span>: <span class="text-emerald-<span class="text-orange-400">400</span>">"img1"</span>, <span class="text-emerald-<span class="text-orange-400">400</span>">"url"</span>: <span class="text-emerald-<span class="text-orange-400">400</span>">"https://example.<span class="text-cyan-300">com</span>/<span class="text-orange-400">1.</span>jpg"</span>},
51      {<span class="text-emerald-<span class="text-orange-400">400</span>">"id"</span>: <span class="text-emerald-<span class="text-orange-400">400</span>">"img2"</span>, <span class="text-emerald-<span class="text-orange-400">400</span>">"url"</span>: <span class="text-emerald-<span class="text-orange-400">400</span>">"https://example.<span class="text-cyan-300">com</span>/<span class="text-orange-400">2.</span>jpg"</span>}
52    ],
53    <span class="text-emerald-<span class="text-orange-400">400</span>">"options"</span>: {
54      <span class="text-emerald-<span class="text-orange-400">400</span>">"priority"</span>: <span class="text-emerald-<span class="text-orange-400">400</span>">"high"</span>,
55      <span class="text-emerald-<span class="text-orange-400">400</span>">"webhook_url"</span>: <span class="text-emerald-<span class="text-orange-400">400</span>">"https://your-app.<span class="text-cyan-300">com</span>/webhook"</span>
56    }
57  }'
58 
59# 4. Get batch status
60curl -<span class="text-yellow-300">X</span> <span class="text-yellow-300">GET</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"https://api.<span class="text-cyan-300">ztrace</span>.<span class="text-cyan-300">ai</span>/v2/batch/batch_xyz789"</span> \
61  -<span class="text-yellow-300">H</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Authorization</span>: <span class="text-yellow-300">Bearer</span> $ZTRACE_API_KEY"</span>
62 
63# 5. List API keys
64curl -<span class="text-yellow-300">X</span> <span class="text-yellow-300">GET</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"https://api.<span class="text-cyan-300">ztrace</span>.<span class="text-cyan-300">ai</span>/v2/api-keys"</span> \
65  -<span class="text-yellow-300">H</span> <span class="text-emerald-<span class="text-orange-400">400</span>">"<span class="text-yellow-300">Authorization</span>: <span class="text-yellow-300">Bearer</span> $ZTRACE_API_KEY"</span>

Batch Processing

batch-processing.ts
TypeScript
1// Batch processing with progress tracking
2<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>import</span></span> { <span class="text-yellow-300">Ztrace</span>, <span class="text-yellow-300">BatchJob</span> } <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>from</span></span> <span class="text-emerald-<span class="text-orange-400">400</span>">'@ztrace/sdk'</span>;
3 
4<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> client = <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>new</span> <span class="text-blue-400"><span class="text-yellow-300">Ztrace</span></span>({ apiKey: process.<span class="text-cyan-300">env</span>.<span class="text-cyan-300">ZTRACE_API_KEY</span> });
5 
6// Define images to process
7<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> images = [
8  { id: <span class="text-emerald-<span class="text-orange-400">400</span>">'img-<span class="text-orange-400">001</span>'</span>, path: <span class="text-emerald-<span class="text-orange-400">400</span>">'./images/location1.<span class="text-cyan-300">jpg</span>'</span> },
9  { id: <span class="text-emerald-<span class="text-orange-400">400</span>">'img-<span class="text-orange-400">002</span>'</span>, path: <span class="text-emerald-<span class="text-orange-400">400</span>">'./images/location2.<span class="text-cyan-300">jpg</span>'</span> },
10  { id: <span class="text-emerald-<span class="text-orange-400">400</span>">'img-<span class="text-orange-400">003</span>'</span>, url: <span class="text-emerald-<span class="text-orange-400">400</span>">'https://example.<span class="text-cyan-300">com</span>/image3.<span class="text-cyan-300">jpg</span>'</span> },
11  { id: <span class="text-emerald-<span class="text-orange-400">400</span>">'img-<span class="text-orange-400">004</span>'</span>, buffer: imageBuffer },
12];
13 
14// Create batch job with configuration
15<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> batchJob = <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>await</span></span> client.<span class="text-cyan-300">batch</span>.<span class="text-blue-400">create</span>({
16  images,
17  options: {
18    model: <span class="text-emerald-<span class="text-orange-400">400</span>">'geo-v3-turbo'</span>,
19    confidence_threshold: <span class="text-orange-400">0.<span class="text-cyan-300">75</span></span>,
20    parallel: <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>true</span>,
21    maxConcurrency: <span class="text-orange-400">10</span>,
22    priority: <span class="text-emerald-<span class="text-orange-400">400</span>">'high'</span>,
23    webhook_url: <span class="text-emerald-<span class="text-orange-400">400</span>">'https://your-app.<span class="text-cyan-300">com</span>/webhooks/batch'</span>
24  }
25});
26 
27console.<span class="text-blue-400">log</span>(<span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">Batch</span> <span class="text-yellow-300">ID</span>:'</span>, batchJob.<span class="text-cyan-300">id</span>);
28console.<span class="text-blue-400">log</span>(<span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">Total</span> <span class="text-yellow-300">Images</span>:'</span>, batchJob.<span class="text-cyan-300">total_count</span>);
29 
30// Option 1: Poll for results
31<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> results = <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>await</span></span> client.<span class="text-cyan-300">batch</span>.<span class="text-blue-400">wait</span>(batchJob.<span class="text-cyan-300">id</span>, {
32  pollInterval: <span class="text-orange-400">2000</span>,
33  timeout: <span class="text-orange-400">300000</span>,
34  onProgress: (progress) => {
35    console.<span class="text-blue-400">log</span>(<span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-emerald-<span class="text-orange-400">400</span>"</span>>`<span class="text-yellow-300">Progress</span>: ${progress.<span class="text-cyan-300">completed</span>}/${progress.<span class="text-cyan-300">total</span>}`</span>);
36  }
37});
38 
39// Option 2: Stream results as they complete
40<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>for</span></span> <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>await</span></span> (<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> result <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>of</span> client.<span class="text-cyan-300">batch</span>.<span class="text-blue-400">stream</span>(batchJob.<span class="text-cyan-300">id</span>)) {
41  console.<span class="text-blue-400">log</span>(<span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-emerald-<span class="text-orange-400">400</span>"</span>>`<span class="text-yellow-300">Completed</span>: ${result.<span class="text-cyan-300">image_id</span>}`</span>);
42  console.<span class="text-blue-400">log</span>(<span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-emerald-<span class="text-orange-400">400</span>"</span>>`<span class="text-yellow-300">Location</span>: ${result.<span class="text-cyan-300">location</span>.<span class="text-cyan-300">lat</span>}, ${result.<span class="text-cyan-300">location</span>.<span class="text-cyan-300">lng</span>}`</span>);
43  console.<span class="text-blue-400">log</span>(<span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-emerald-<span class="text-orange-400">400</span>"</span>>`<span class="text-yellow-300">Confidence</span>: ${(result.<span class="text-cyan-300">confidence</span> * <span class="text-orange-400">100</span>).<span class="text-blue-400">toFixed</span>(<span class="text-orange-400">1</span>)}%`</span>);
44  
45  // Save to database
46  <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>await</span></span> db.<span class="text-cyan-300">results</span>.<span class="text-blue-400">insert</span>({
47    imageId: result.<span class="text-cyan-300">image_id</span>,
48    location: result.<span class="text-cyan-300">location</span>,
49    features: result.<span class="text-cyan-300">features</span>,
50    processedAt: <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>new</span> <span class="text-blue-400"><span class="text-yellow-300">Date</span></span>()
51  });
52}
53 
54// Get batch summary
55<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> summary = <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>await</span></span> client.<span class="text-cyan-300">batch</span>.<span class="text-blue-400">getSummary</span>(batchJob.<span class="text-cyan-300">id</span>);
56console.<span class="text-blue-400">log</span>(<span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">Success</span> <span class="text-yellow-300">Rate</span>:'</span>, <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-emerald-<span class="text-orange-400">400</span>"</span>>`${summary.<span class="text-cyan-300">success_rate</span>}%`</span>);
57console.<span class="text-blue-400">log</span>(<span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">Average</span> <span class="text-yellow-300">Confidence</span>:'</span>, summary.<span class="text-cyan-300">avg_confidence</span>);
58console.<span class="text-blue-400">log</span>(<span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">Processing</span> <span class="text-yellow-300">Time</span>:'</span>, <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-emerald-<span class="text-orange-400">400</span>"</span>>`${summary.<span class="text-cyan-300">total_time_ms</span>}ms`</span>);

Last updated December 2025

Was this helpful?