04 - API Endpoints Documentation¶

Complete documentation for all API endpoints with examples, request/response formats, and usage scenarios.

📋 Overview¶

The API provides 12 main endpoints organized into these categories:

Text Processing: Summarization and marketing copy generation
Media Generation: Text-to-speech and video creation
YouTube Integration: Authentication and video uploads
Utilities: URL shortening and health checks

🌐 Base URL and Documentation¶

Base URL: http://localhost:8000
Interactive Docs: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

📊 Endpoint Summary Table¶

Endpoint	Method	Purpose	Authentication
`/health`	GET	Health check	None
`/summarize`	POST	Text summarization	API Key
`/bullet-summarize`	POST	Bullet point summary	API Key
`/product-marketing`	POST	Product marketing copy	API Key
`/product`	POST	Simple product summary	API Key
`/batch-products`	POST	Batch product processing	API Key
`/batch`	POST	Batch with TTS/video	API Key
`/generate-video`	POST	Video generation	API Key
`/youtube-auth-url`	GET	YouTube auth URL	None
`/youtube-auth`	POST	Complete YouTube auth	None
`/upload-youtube`	POST	Upload to YouTube	YouTube Auth
`/shortlink`	POST	URL shortening	None

🏥 Health Check Endpoint¶

`GET /health`¶

Check API health and service status.

Request¶

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

Response¶

{
  "status": "healthy",
  "version": "2.0.0",
  "services": {
    "text_summarizer": "active",
    "tts_service": "active",
    "video_service": "active",
    "youtube_service": "configured",
    "shortlink_service": "active"
  }
}

📝 Text Processing Endpoints¶

`POST /summarize`¶

Generate a concise summary of provided text.

Request Body¶

{
  "text": "string (required, min 10 chars)",
  "max_length": "integer (optional, default: 100, max: 500)",
  "min_length": "integer (optional, default: 20, max: max_length)",
  "temperature": "float (optional, default: 0.7, range: 0.1-1.0)"
}

Example Request¶

curl -X POST "http://localhost:8000/summarize" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Artificial intelligence (AI) is intelligence demonstrated by machines, in contrast to the natural intelligence displayed by humans and animals. Leading AI textbooks define the field as the study of intelligent agents: any device that perceives its environment and takes actions that maximize its chance of successfully achieving its goals.",
    "max_length": 50,
    "temperature": 0.8
  }'

Response¶

{
  "summary": "AI is machine intelligence that perceives environments and takes goal-oriented actions."
}

`POST /bullet-summarize`¶

Generate a bullet point summary.

Request Body¶

{
  "text": "string (required, min 10 chars)",
  "num_points": "integer (optional, default: 5, max: 10)",
  "max_length": "integer (optional, default: 200, max: 1000)"
}

Example Request¶

curl -X POST "http://localhost:8000/bullet-summarize" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The iPhone 15 Pro features a titanium design, A17 Pro chip, improved camera system with 5x telephoto zoom, and USB-C connectivity. It comes in four colors and offers up to 1TB storage.",
    "num_points": 3,
    "max_length": 150
  }'

Response¶

{
  "summary": "• Titanium design with A17 Pro chip for enhanced performance\n• Advanced camera system featuring 5x telephoto zoom capabilities\n• USB-C connectivity with up to 1TB storage options in four colors"
}

`POST /product-marketing`¶

Generate marketing copy for a product.

Request Body¶

{
  "product_data": {
    "title": "string (required)",
    "price": "string (optional)",
    "description": "string (optional)",
    "features": "array (optional)"
  },
  "tone": "string (optional, default: 'enthusiastic')",
  "max_length": "integer (optional, default: 150, max: 500)"
}

Example Request¶

curl -X POST "http://localhost:8000/product-marketing" \
  -H "Content-Type: application/json" \
  -d '{
    "product_data": {
      "title": "Wireless Bluetooth Headphones",
      "price": "$79.99",
      "description": "High-quality wireless headphones with noise cancellation"
    },
    "tone": "professional",
    "max_length": 100
  }'

Response¶

{
  "summary": "Experience premium audio with these professional wireless Bluetooth headphones featuring advanced noise cancellation technology, delivering exceptional sound quality for just $79.99."
}

`POST /product`¶

Simple product marketing copy generation.

Request Body¶

{
  "title": "string (required)",
  "price": "string (optional)",
  "link": "string (optional)",
  "rank": "integer (optional)"
}

Example Request¶

curl -X POST "http://localhost:8000/product" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sundays Are for the Birds Sweatshirt",
    "price": "$28.97",
    "link": "https://www.amazon.com/dp/B0DS6MC1J2"
  }'

Response¶

{
  "summary": "Get cozy with this fun 'Sundays Are for the Birds' sweatshirt! Perfect for game day or casual weekends, this comfortable pullover is a great gift for sports fans at just $28.97."
}

🎬 Media Generation Endpoints¶

`POST /batch-products`¶

Process multiple products with marketing copy generation.

Request Body¶

{
  "products": [
    {
      "title": "string (required)",
      "price": "string (optional)",
      "link": "string (optional)",
      "rank": "integer (optional)"
    }
  ],
  "tone": "string (optional, default: 'enthusiastic')",
  "max_length": "integer (optional, default: 150, max: 500)"
}

Example Request¶

curl -X POST "http://localhost:8000/batch-products" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "title": "Wireless Mouse",
        "price": "$19.99",
        "rank": 1
      },
      {
        "title": "USB Keyboard",
        "price": "$34.99",
        "rank": 2
      }
    ],
    "tone": "enthusiastic",
    "max_length": 100
  }'

Response¶

[
  {
    "title": "Wireless Mouse",
    "price": "$19.99",
    "rank": 1,
    "summary": "Discover the freedom of wireless computing with this precision mouse! Smooth tracking and ergonomic design make it perfect for work or gaming at an amazing $19.99!",
    "audio_url": "https://storage.googleapis.com/merchant-ary/Wireless_Mouse.mp3",
    "video_url": null
  },
  {
    "title": "USB Keyboard",
    "price": "$34.99",
    "rank": 2,
    "summary": "Type with confidence using this reliable USB keyboard! Featuring responsive keys and durable construction, it's the perfect addition to your setup for just $34.99!",
    "audio_url": "https://storage.googleapis.com/merchant-ary/USB_Keyboard.mp3",
    "video_url": null
  }
]

`POST /batch`¶

Complete batch processing with TTS and video generation.

Request Body¶

{
  "products": [
    {
      "title": "string (required)",
      "price": "string (optional)",
      "link": "string (optional)"
    }
  ]
}

Example Request¶

curl -X POST "http://localhost:8000/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "title": "Smart Watch Fitness Tracker",
        "price": "$89.99"
      }
    ]
  }'

`POST /generate-video`¶

Generate videos from product data using existing audio and image files.

Request Body¶

{
  "title": "string (required, min 1 char)",
  "price": "string (optional)",
  "summary": "string (optional)",
  "link": "string (optional)",
  "rank": "integer (optional, >= 1)",
  "video_format": "string (optional, 'regular' or 'shorts', default: 'regular')",
  "upload_to_youtube": "boolean (optional, default: false)",
  "youtube_public": "boolean (optional, default: false)",
  "bucket_name": "string (optional, default: 'merchant-ary')",
  "expiration": "integer (optional, 60-604800 seconds, default: 3600)"
}

Example Request¶

curl -X POST "http://localhost:8000/generate-video" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Wireless Bluetooth Headphones",
    "price": "$79.99",
    "video_format": "shorts",
    "upload_to_youtube": true,
    "youtube_public": false
  }'

Response¶

{
  "success": true,
  "message": "Video generated successfully",
  "video_path": "https://storage.googleapis.com/merchant-ary/Wireless_Bluetooth_Headphones.mp4",
  "local_video_path": "videos_output/Wireless_Bluetooth_Headphones.mp4",
  "expires_at": "2025-09-07T10:30:00Z",
  "title": "Wireless Bluetooth Headphones",
  "safe_title": "Wireless_Bluetooth_Headphones",
  "audio_found": true,
  "image_found": true,
  "audio_path": "audio/Wireless_Bluetooth_Headphones.mp3",
  "image_path": "images/Wireless_Bluetooth_Headphones.jpg",
  "product_data": {
    "title": "Wireless Bluetooth Headphones",
    "price": "$79.99"
  },
  "youtube_video_id": "dQw4w9WgXcQ",
  "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "youtube_error": null
}

📺 YouTube Integration Endpoints¶

`GET /youtube-auth-url`¶

Get YouTube OAuth2 authorization URL for first-time setup.

Request¶

curl -X GET "http://localhost:8000/youtube-auth-url"

Response¶

{
  "auth_url": "https://accounts.google.com/o/oauth2/auth?response_type=code&client_id=...",
  "instructions": "Visit this URL, authorize the application, and copy the 'code' parameter from the callback URL to complete setup."
}

`POST /youtube-auth`¶

Complete YouTube OAuth2 authorization with callback code.

Request Body¶

{
  "authorization_code": "string (required)"
}

Example Request¶

curl -X POST "http://localhost:8000/youtube-auth" \
  -H "Content-Type: application/json" \
  -d '{
    "authorization_code": "4/0AX4XfWh_example_code_here"
  }'

Response¶

{
  "success": true,
  "message": "YouTube authorization completed successfully. You can now upload videos.",
  "error": null
}

`POST /upload-youtube`¶

Upload a video to YouTube with product metadata.

Request Body¶

{
  "video_path": "string (required)",
  "product_data": {
    "title": "string (required)",
    "price": "string (optional)",
    "link": "string (optional)",
    "summary": "string (optional)"
  },
  "youtube_public": "boolean (optional, default: false)"
}

Example Request¶

curl -X POST "http://localhost:8000/upload-youtube" \
  -H "Content-Type: application/json" \
  -d '{
    "video_path": "videos_output/product_video.mp4",
    "product_data": {
      "title": "Amazing Product Review",
      "price": "$49.99",
      "summary": "This is an amazing product that everyone should have!"
    },
    "youtube_public": true
  }'

Response¶

{
  "success": true,
  "error": null,
  "video_id": "dQw4w9WgXcQ",
  "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "title": "Amazing Product Review - $49.99",
  "privacy_status": "public"
}

🔗 Utility Endpoints¶

`POST /shortlink`¶

Create shortened URLs using external service.

Request Body¶

{
  "url": "string (required, valid URL)"
}

Example Request¶

curl -X POST "http://localhost:8000/shortlink" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.amazon.com/dp/B0014C0LSY?tag=AGSM1323"
  }'

Response¶

{
  "success": true,
  "original_url": "https://www.amazon.com/dp/B0014C0LSY?tag=AGSM1323",
  "shortened_url": "https://ulvis.net/A1B2C3",
  "error": null
}

🔄 Workflow Examples¶

Complete Product Processing Workflow¶

1. Generate Marketing Copy¶

curl -X POST "http://localhost:8000/product" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Smart Fitness Watch",
    "price": "$199.99"
  }'

2. Generate Video (requires audio/image files)¶

curl -X POST "http://localhost:8000/generate-video" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Smart Fitness Watch",
    "price": "$199.99",
    "video_format": "shorts",
    "upload_to_youtube": true
  }'

3. Shorten Product URL¶

curl -X POST "http://localhost:8000/shortlink" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.amazon.com/dp/B123456789"
  }'

Batch Processing Workflow¶

curl -X POST "http://localhost:8000/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "title": "Product 1",
        "price": "$29.99"
      },
      {
        "title": "Product 2",
        "price": "$39.99"
      }
    ]
  }'

🚨 Error Handling¶

Common Error Responses¶

400 Bad Request¶

{
  "detail": "Request validation error",
  "errors": [
    {
      "loc": ["body", "text"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

422 Validation Error¶

{
  "detail": "Request validation error",
  "errors": [
    {
      "loc": ["body", "max_length"],
      "msg": "ensure this value is less than or equal to 500",
      "type": "value_error.number.not_le"
    }
  ]
}

500 Internal Server Error¶

{
  "detail": "Summarization error: API key not configured"
}

Error Status Codes¶

Code	Description	Common Causes
400	Bad Request	Invalid JSON, malformed data
422	Validation Error	Missing required fields, invalid values
500	Internal Server Error	API key issues, service unavailable

📊 Rate Limits and Constraints¶

Request Limits¶

Batch endpoints: Maximum 10 products per request
Text length: Maximum 10,000 characters for summarization
Video uploads: Maximum 2GB file size
Batch cooldown: 1 hour between large batch requests

File Requirements¶

Audio files: MP3 format, stored in audio/ directory
Image files: JPG/PNG format, stored in images/ directory
Video output: MP4 format, saved to videos_output/ directory

🎯 Next Steps¶

For troubleshooting and advanced usage: - 05-troubleshooting.md - Common issues and solutions - 06-architecture.md - Technical architecture details

📝 Testing Tips¶

Use curl for quick testing:¶

# Test health
curl http://localhost:8000/health

# Test with verbose output
curl -v -X POST "http://localhost:8000/summarize" \
  -H "Content-Type: application/json" \
  -d '{"text": "test"}'

# Save response to file
curl -X POST "http://localhost:8000/summarize" \
  -H "Content-Type: application/json" \
  -d '{"text": "test"}' \
  -o response.json

Use the interactive docs:¶

Visit http://localhost:8000/docs for a user-friendly interface to test all endpoints with automatic validation and examples.

04 - API Endpoints Documentation¶

📋 Overview¶

🌐 Base URL and Documentation¶

📊 Endpoint Summary Table¶

🏥 Health Check Endpoint¶

GET /health¶

Request¶

Response¶

📝 Text Processing Endpoints¶

POST /summarize¶

Request Body¶

Example Request¶

Response¶

POST /bullet-summarize¶

Request Body¶

Example Request¶

Response¶

POST /product-marketing¶

Request Body¶

Example Request¶

Response¶

POST /product¶

Request Body¶

Example Request¶

Response¶

🎬 Media Generation Endpoints¶

POST /batch-products¶

Request Body¶

Example Request¶

Response¶

POST /batch¶

Request Body¶

Example Request¶

POST /generate-video¶

Request Body¶

Example Request¶

Response¶

📺 YouTube Integration Endpoints¶

GET /youtube-auth-url¶

Request¶

Response¶

POST /youtube-auth¶

Request Body¶

Example Request¶

Response¶

POST /upload-youtube¶

Request Body¶

Example Request¶

Response¶

🔗 Utility Endpoints¶

POST /shortlink¶

Request Body¶

Example Request¶

Response¶

🔄 Workflow Examples¶

Complete Product Processing Workflow¶

1. Generate Marketing Copy¶

2. Generate Video (requires audio/image files)¶

3. Shorten Product URL¶

Batch Processing Workflow¶

🚨 Error Handling¶

Common Error Responses¶

400 Bad Request¶

422 Validation Error¶

500 Internal Server Error¶

Error Status Codes¶

📊 Rate Limits and Constraints¶

Request Limits¶

File Requirements¶

🎯 Next Steps¶

📝 Testing Tips¶

Use curl for quick testing:¶

Use the interactive docs:¶

`GET /health`¶

`POST /summarize`¶

`POST /bullet-summarize`¶

`POST /product-marketing`¶

`POST /product`¶

`POST /batch-products`¶

`POST /batch`¶

`POST /generate-video`¶

`GET /youtube-auth-url`¶

`POST /youtube-auth`¶

`POST /upload-youtube`¶

`POST /shortlink`¶