ImgStory API Documentation

Welcome to the ImgStory API documentation. This API allows you to analyze media files (images and videos) and generate creative stories based on visual content using OpenAI's vision models.

Base URL

http://localhost:8000

For production environments, replace with your actual domain.

Authentication

Currently, the ImgStory API does not require authentication for local usage. If deploying to production, you may want to implement authentication using API keys or OAuth2 to secure your endpoints.

Rate Limits

This application relies on OpenAI's API which has its own rate limits. Please be mindful of the following:

• There may be limits on the number of requests you can make within a time period
• Token usage is tracked and displayed in the response
• Processing large video files may take more time than images

API Endpoints

{
  "english": "English language story generated from the media",
  "thai": "Thai language translation of the story",
  "token_usage": {
    "input_tokens": 123,
    "output_tokens": 456,
    "total_tokens": 579
  }
}

curl -X POST http://localhost:8000/analyze/ \
  -F "files=@/path/to/your/image.jpg" \
  -F "prompt=Generate a story about this image in the style of Anthony Bourdain"

const formData = new FormData();
formData.append('files', imageFile); // From file input
formData.append('prompt', 'Generate a story about this image in the style of Anthony Bourdain');

fetch('http://localhost:8000/analyze/', {
  method: 'POST',
  body: formData
})
.then(response => response.json())
.then(data => {
  console.log(data.english); // English story
  console.log(data.thai);    // Thai story
  console.log(data.token_usage); // Token usage statistics
})
.catch(error => console.error('Error:', error));

import requests

url = "http://localhost:8000/analyze/"
files = {'files': open('image.jpg', 'rb')}
data = {'prompt': 'Generate a story about this image in the style of Anthony Bourdain'}

response = requests.post(url, files=files, data=data)
result = response.json()

print(result['english'])
print(result['thai'])
print(result['token_usage'])

Error Handling

The API returns standard HTTP status codes to indicate the success or failure of a request. Error responses include a JSON object with details about what went wrong.

Error Response Format

{
  "detail": "Error message describing what went wrong"
}

Usage Examples

Analyzing a Single Image

This example demonstrates how to upload a single image and generate a story:

curl -X POST http://localhost:8000/analyze/ \
  -F "files=@/path/to/your/image.jpg"

Analyzing Multiple Images

You can upload multiple images in a single request:

curl -X POST http://localhost:8000/analyze/ \
  -F "files=@/path/to/image1.jpg" \
  -F "files=@/path/to/image2.jpg" \
  -F "files=@/path/to/image3.jpg"

Analyzing a Video

You can also upload a video file:

curl -X POST http://localhost:8000/analyze/ \
  -F "files=@/path/to/video.mp4"

Troubleshooting

If you encounter issues using the API, check the following:

• Ensure you're using supported file formats (JPG, PNG for images, MP4 for video)
• Check file size limits (10MB for images, 50MB for video)
• For server-side issues, check the application logs
• If you encounter rate limiting, wait and try again later

Common Issues