Curl Examples for Image Transcription API

This document provides curl examples for using the image transcription functionality via the REST API.

Prerequisites

Start the API server:
```
python api_server.py
# or
python run_api.py
```
The server will run on http://localhost:8000 by default.

Ensure API keys are configured in your .env file:

OPENAI_API_KEY=your_openai_key_here
GOOGLE_API_KEY=your_google_key_here

Have image URLs ready for testing

API Endpoints

1. Image URL Transcription Endpoint (Primary)

Endpoint: POST /transcribe-image-url

Description: Provide an image URL and get structured JSON with title, description, and extracted text.

2. Image File Upload Endpoint (Alternative)

Endpoint: POST /transcribe-image

Description: Upload an image file and get structured JSON with title, description, and extracted text.

Curl Examples

Basic Image URL Transcription

curl -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}'

With Custom Filename

curl -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/image", "filename": "my-photo.jpg"}'

Save Response to File

curl -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/document.png"}' \
  -o image_result.json

Pretty Print JSON Response

curl -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/screenshot.jpg"}' | jq '.'

Silent Mode (No Progress)

curl -s -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/image.png"}'

With Custom Headers

curl -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0" \
  -H "Accept: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}'

Real-World Image URLs

# Stock photo
curl -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://picsum.photos/800/600"}'

# GitHub raw image
curl -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://raw.githubusercontent.com/user/repo/main/image.jpg"}'

# Direct image URL
curl -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://i.imgur.com/example.png"}'

Alternative: File Upload (if needed)

# Upload local file instead of URL
curl -X POST "http://localhost:8000/transcribe-image" \
  -F "file=@local-photo.jpg"

Expected Response Format

Successful Response

{
  "file_id": "uuid-string",
  "file_info": {
    "name": "photo.jpg",
    "extension": ".jpg",
    "size_mb": 2.5,
    "mime_type": "image/jpeg"
  },
  "success": true,
  "error": null,
  "title": "Modern Office Meeting Room",
  "description": "A contemporary meeting room with a large wooden conference table surrounded by black office chairs. The room features floor-to-ceiling windows with natural light, white walls, and a large flat-screen display mounted on the wall.",
  "extracted_text": "QUARTERLY REVIEW\nQ3 2024 Results\nMeeting at 2:00 PM",
  "processor_used": "OpenAI Vision",
  "processing_time": 3.24,
  "timestamp": "2024-01-15T10:30:45.123456"
}

Error Response

{
  "file_id": "uuid-string",
  "file_info": {
    "name": "document.pdf",
    "extension": ".pdf",
    "size_mb": 1.2,
    "mime_type": "application/pdf"
  },
  "success": false,
  "error": "Unsupported image format: .pdf. Supported: .bmp, .gif, .jpg, .jpeg, .png, .tif, .tiff, .webp",
  "title": null,
  "description": null,
  "extracted_text": null,
  "processor_used": null,
  "processing_time": 0.1,
  "timestamp": "2024-01-15T10:30:45.123456"
}

Advanced Examples

Extract Specific Fields with jq

# Get only the title
curl -s -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}' | jq -r '.title'

# Get title and description
curl -s -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}' | jq '{title: .title, description: .description}'

# Get extracted text only
curl -s -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/document.jpg"}' | jq -r '.extracted_text'

# Check if processing was successful
curl -s -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}' | jq '.success'

Error Handling in Scripts

#!/bin/bash

response=$(curl -s -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d "{\"url\": \"$1\"}")

success=$(echo "$response" | jq -r '.success')

if [ "$success" = "true" ]; then
    echo "Success! Title: $(echo "$response" | jq -r '.title')"
    echo "Description: $(echo "$response" | jq -r '.description')"
else
    echo "Error: $(echo "$response" | jq -r '.error')"
fi

Batch Processing Script for URLs

#!/bin/bash

# Process multiple image URLs from a file
while IFS= read -r url; do
    if [ ! -z "$url" ]; then
        echo "Processing: $url"
        filename=$(basename "$url" | cut -d'?' -f1)
        curl -s -X POST "http://localhost:8000/transcribe-image-url" \
          -H "Content-Type: application/json" \
          -d "{\"url\": \"$url\"}" \
          -o "${filename%.*}_result.json"
        echo "Saved result to: ${filename%.*}_result.json"
    fi
done < image_urls.txt

Check Processing Time

curl -s -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/large_image.jpg"}' | jq '.processing_time'

Testing Other API Endpoints

Health Check

curl -X GET "http://localhost:8000/health"

General File Upload (includes images)

curl -X POST "http://localhost:8000/extract" \
  -F "file=@photo.jpg"

Image URL Processing (Primary Method)

curl -X POST "http://localhost:8000/transcribe-image-url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/photo.jpg"}'

API Documentation

# View interactive API docs
open http://localhost:8000/docs

# View ReDoc documentation
open http://localhost:8000/redoc

Common Issues and Solutions

1. File Not Found Error

# Error
curl: (26) Failed to open/read local data from file/application

# Solution: Check file path
ls -la photo.jpg
curl -X POST "http://localhost:8000/transcribe-image" \
  -F "file=@./path/to/photo.jpg"

2. Unsupported File Format

# Error response:
{
  "success": false,
  "error": "Unsupported image format: .pdf"
}

# Solution: Use supported formats
curl -X POST "http://localhost:8000/transcribe-image" \
  -F "file=@converted_image.jpg"

3. API Server Not Running

# Error
curl: (7) Failed to connect to localhost port 8000

# Solution: Start the server
python api_server.py

4. Large File Upload

# For large files, increase timeout
curl --max-time 300 -X POST "http://localhost:8000/transcribe-image" \
  -F "file=@large_image.jpg"

5. API Key Issues

# Error response:
{
  "detail": "Image processor not available. Please check API key configuration."
}

# Solution: Check .env file has valid API keys
cat .env | grep -E "(OPENAI_API_KEY|GOOGLE_API_KEY)"

Performance Tips

Use appropriate image sizes: Smaller images process faster
Choose the right format: JPEG and PNG typically work best
Monitor processing time: Use jq to extract .processing_time
Batch processing: Process multiple images sequentially to avoid rate limits

Security Considerations

Use HTTPS in production: Replace http://localhost:8000 with https://your-domain.com
API Authentication: Consider adding authentication headers if implemented
File size limits: The API has built-in file size restrictions
Rate limiting: Be mindful of API rate limits for the underlying services

Environment-Specific Examples

Development

curl -X POST "http://localhost:8000/transcribe-image" \
  -F "file=@test_image.jpg"

Production

curl -X POST "https://your-api-domain.com/transcribe-image" \
  -H "Authorization: Bearer your-token" \
  -F "file=@image.jpg"

Docker

# If running in Docker
curl -X POST "http://localhost:8000/transcribe-image" \
  -F "file=@image.jpg"

Integration Examples

Python

import requests

# Using image URL (primary method)
data = {"url": "https://example.com/photo.jpg"}
response = requests.post('http://localhost:8000/transcribe-image-url', json=data)
result = response.json()
print(f"Title: {result['title']}")

# Alternative: Upload local file
# with open('photo.jpg', 'rb') as f:
#     files = {'file': f}
#     response = requests.post('http://localhost:8000/transcribe-image', files=files)
#     result = response.json()
#     print(f"Title: {result['title']}")

JavaScript/Node.js

// Using image URL (primary method)
const data = { url: "https://example.com/photo.jpg" };

fetch('http://localhost:8000/transcribe-image-url', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log('Title:', data.title));

// Alternative: Upload local file
// const FormData = require('form-data');
// const fs = require('fs');
//
// const form = new FormData();
// form.append('file', fs.createReadStream('photo.jpg'));
//
// fetch('http://localhost:8000/transcribe-image', {
//     method: 'POST',
//     body: form
// })
// .then(response => response.json())
// .then(data => console.log('Title:', data.title));

PHP

// Using image URL (primary method)
$data = json_encode(array('url' => 'https://example.com/photo.jpg'));

$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => 'http://localhost:8000/transcribe-image-url',
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $data,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'Content-Length: ' . strlen($data)
    ),
));

$response = curl_exec($curl);
$result = json_decode($response, true);
echo "Title: " . $result['title'];

// Alternative: Upload local file
// $curl = curl_init();
// curl_setopt_array($curl, array(
//     CURLOPT_URL => 'http://localhost:8000/transcribe-image',
//     CURLOPT_POST => true,
//     CURLOPT_POSTFIELDS => array('file' => new CURLFile('photo.jpg')),
//     CURLOPT_RETURNTRANSFER => true,
// ));
//
// $response = curl_exec($curl);
// $result = json_decode($response, true);
// echo "Title: " . $result['title'];

Translation API Examples

Single Text Translation

Basic Translation (using Gemini by default)

curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, how are you?",
    "source_language": "en",
    "target_language": "es"
  }'

Auto-Detect Source Language

curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Bonjour, comment allez-vous?",
    "source_language": "auto-detect",
    "target_language": "en"
  }'

Using Different Auto-Detect Keywords

# Using "auto"
curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hola, ¿cómo estás?",
    "source_language": "auto",
    "target_language": "en"
  }'

# Using "detect"
curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Guten Tag, wie geht es Ihnen?",
    "source_language": "detect",
    "target_language": "en"
  }'

Force OpenAI API Usage

curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello world",
    "source_language": "en",
    "target_language": "fr",
    "use_openai": true
  }'

Long Text Translation

curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is a longer text that demonstrates the translation capabilities of the API. It can handle multiple sentences and preserve the meaning and context across the translation.",
    "source_language": "auto-detect",
    "target_language": "es"
  }'

Batch Text Translation

Basic Batch Translation with Auto-Detect

curl -X POST "http://localhost:8000/translate-batch" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": [
      "Hello world",
      "How are you?",
      "Thank you very much"
    ],
    "source_language": "auto-detect",
    "target_language": "es"
  }'

Mixed Language Batch (Auto-Detect)

curl -X POST "http://localhost:8000/translate-batch" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": [
      "Hello world",
      "Bonjour le monde",
      "Hola mundo",
      "Hallo Welt"
    ],
    "source_language": "auto",
    "target_language": "en"
  }'

Batch Translation with Specific Source Language

curl -X POST "http://localhost:8000/translate-batch" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": [
      "Buenos días",
      "Buenas tardes",
      "Buenas noches"
    ],
    "source_language": "es",
    "target_language": "en"
  }'

Language Detection

Detect Language of Text

curl -X POST "http://localhost:8000/detect-language" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Je suis très heureux de vous rencontrer"
  }'

Language Detection with OpenAI

curl -X POST "http://localhost:8000/detect-language" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Ich freue mich sehr, Sie kennenzulernen",
    "use_openai": true
  }'

Get Supported Languages

curl -X GET "http://localhost:8000/supported-languages" \
  -H "Accept: application/json"

Translation Examples by Language Pair

English to Spanish

curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The weather is beautiful today",
    "source_language": "en",
    "target_language": "es"
  }'

Auto-Detect to French

curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "私は日本人です",
    "source_language": "auto-detect",
    "target_language": "fr"
  }'

German to English

curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Wie spät ist es?",
    "source_language": "de",
    "target_language": "en"
  }'

Error Handling Examples

Invalid Language Code

curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello",
    "source_language": "invalid",
    "target_language": "es"
  }'

Empty Text

curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "",
    "source_language": "en",
    "target_language": "es"
  }'

FilesExpand file tree

CURL_EXAMPLES.md

Latest commit

History