Version: 1.2.0

Alt-Text API Documentation

Version: 1.2.0

Single Image Alt-Text Generation API

/cl/alttext/api/v2/

Method: POST
Summary: Generate Alt-Text For Single Image
Description: Generate alternative text, descriptions, and metadata for a single image file.

Request Payload:

Type	Parameter	Description	Data Type	Is Optional
Form Data	file	Image file to generate alt text for	File (.png, .jpeg, .jpg, .bmp, .gif)	No
Form Data	selected_model	AI model selection (gpt-4o, gpt-4o-mini, gemini-1.5-flash)	string	No
Form Data	alt_text_length	Desired length of generated alt text (125-500)	integer	Yes
Form Data	alt_prompt	Custom prompt to guide generation	string	Yes
Form Data	generate_description	Enable detailed description generation	boolean	Yes
Form Data	generate_ocr	Enable text extraction from image	boolean	Yes
Form Data	context	Additional context for generation	string	Yes
Form Data	regenerate	Force new generation instead of using cache	boolean	Yes

Sample Code:

import requests

# Input Parameters
api_url = "https://api-genai-dev.learningmate.co/cl/alttext/api/v2/"
image_file_path = "image_file_path"
token = "your_token_here"
selected_model = "gpt-4o"  # Options: "gpt-4o", "gpt-4o-mini", "gemini-1.5-flash"
alt_prompt = ""
alt_text_length = 125
generate_description = False
generate_ocr = False
context = ""
regenerate = False

# Headers
headers = {
    "Authorization": f"Bearer {token}",
    "accept": "application/json"
}

# Prepare the form data
form_data = {
    "selected_model": selected_model,
    "alt_prompt": alt_prompt,
    "alt_text_length": alt_text_length,
    "generate_description": str(generate_description).lower(),
    "generate_ocr": str(generate_ocr).lower(),
    "context": context,
    "regenerate": str(regenerate).lower(),
}

try:
    # Open the image file and prepare the request
    with open(image_file_path, "rb") as image_file:
        files = {
            "file": (image_file_path, image_file, "multipart/form-data")
        }

        # Make the POST request
        response = requests.post(api_url, headers=headers, data=form_data, files=files)

    # Check the response
    if response.status_code == 200:
        print("Request successful!")
        print(response.json())
    else:
        print(f"Request failed with status code {response.status_code}: {response.text}")

except Exception as e:
    print(f"An error occurred: {e}")

Example Response:

{
  "status_code": 200,
  "message": "Success: Image info generated successfully.",
  "file_name": "image_name.extension",
  "alt_text": "An alt text for the image.",
  "classification": [
    "Example classification"
  ],
  "keywords": [
    "Keyword 1 ",
    "Keyword 2"
  ],
  "description": "An example detailed description of the image.",
  "ocr_text": "OCR text extracted from the image."
}

Responses:

Status Code	Description	Content-Type
200	Successful Response - Image info generated successfully	application/json
400	Bad Request - Bad Request : Could not process the request due to invalid input, network error or system error. Please try again later or contact support if the issue persists.	application/json
401	Unauthorized - Invalid or missing authentication token	application/json
415	Unauthorized - Error: Invalid file format. Please provide a valid image file format (JPEG, JPG, PNG, BMP, GIF).	application/json
422	Unprocessable Entity - Content policy violation: Request contains prohibited content. Please try some other content	application/json
500	Internal Server Error - Request failed: An unexpected error occurred. Please try again later or contact support if the issue persists.	application/json

Bulk Alt-Text Generation API

/cl/alttext/api/v3/

Method: POST
Summary: Generate Alt-Text For Multiple Images
Description: Generate alternative text and metadata for multiple images using a ZIP file containing images and configuration.

Request Payload:

Type	Parameter	Description	Data Type	Is Optional
Form Data	file	ZIP file containing images and JSON configuration	File (.zip)	No
Query Parameter	user_email	Email address for receiving results	string	Yes
Query Parameter	callback_url	URL for receiving completion notification	string	Yes

Sample Code:

import requests

api_url = "https://api-genai-dev.learningmate.co/cl/alttext/api/v3/"
zip_file_path = "path/to/your/images.zip"
token = "your_access_token"
user_email = "user@example.com"
callback_url = "https://your-callback-url.com/callback"

headers = {
    "Authorization": f"Bearer {token}",
    "accept": "application/json"
}

params = {
    "user_email": user_email,
    "callback_url": callback_url
}


try:
    with open(zip_file_path, "rb") as zip_file:
        files = {
            "file": (zip_file_path, zip_file, "application/x-zip-compressed")
        }
        response = requests.post(api_url, headers=headers, params=params, files=files)

    if response.status_code == 200 or response.status_code == 202:
        print("Request successful!")
        print(response.json())
    else:
        print(f"Request failed with status code {response.status_code}: {response.text}")

except Exception as e:
    print(f"An error occurred: {e}")

Example Response:

{
    "job_id": "12345",
    "s3_url": "S3 url for uploaded input zip file",
    "status": "Queued",
    "message": "Job is queued for processing. Please check the job status with the status api using job_id"
}

Responses:

Status Code	Description	Content-Type
200	Successful Response - Job submitted successfully	application/json
400	Bad Request - Unsupported file type. Only .zip files are supported	application/json
401	Unauthorized - Invalid or missing authentication token	application/json
415	Unsupported Media Type - Unsupported Media Type: Only .zip files are supported	application/json
422	Validation Error - No Json File in the ZIP	application/json
422	Validation Error - No image Files in the ZIP	application/json
422	Validation Error - Too many image Files in the ZIP	application/json
422	Validation Error - Too many Json Files in the ZIP	application/json
500	Internal Server Error - Unexpected server error	application/json

Status Check API

/cl/alttext/api/v3/status/{job_id}

Method: GET
Summary: Check Status of Bulk Alt-Text Generation Job
Description: Retrieve the current status and results of a bulk processing job.

Request Payload:

Type	Parameter	Description	Data Type	Is Optional
Path Parameter	job_id	Unique identifier for the bulk processing job	string	No

Sample Code:

import requests

job_id = "12345"
api_url = f"https://api-genai-dev.learningmate.co/cl/alttext/api/v3/status/{job_id}"
token = "your_access_token"

headers = {
    "Authorization": f"Bearer {token}",
    "accept": "application/json"
}

try:
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        print("Job status retrieved successfully!")
        print(response.json())
    elif response.status_code == 404:
        print(f"Job not found: {response.json().get('detail', 'No additional details')}")
    else:
        print(f"Request failed with status code {response.status_code}: {response.text}")

except Exception as e:
    print(f"An error occurred: {e}")

Example Response:

{
  "job_id": "3c22c4a3-bcfa-4dad-a55c-8e144fcd582e",
  "status": "Completed",
  "file_name": "zip_filename.zip",
  "s3_url": "S3 link for input file ",
  "created_at": "2025-01-03T07:44:30.616000",
  "updated_at": "2025-01-03T07:44:36.088000",
  "result": {
    "status_code": 200,
    "message": "Success: Image information for zip file generated successfully.",
    "total_images": 2,
    "success_count": 1,
    "failure_count": 1,
    "cdn_url": "S3 link for output file ",
    "images": [
      {
        "status": "success",
        "message": "Successfully generated image info",
        "name": "imagename.extension",
        "file_ref": "Images/image_2.extension",
        "alt_text": "An Amazon receipt showing details of a purchase including the seller's information, buyer's address, invoice date, payment method, and itemized list of purchased products with prices.",
        "classification": "Image Classification",
        "keywords": ["keyword 1, keyword 2, keyword 3, ... "],
        "long_alt_text": ""
      },
      {
        "status": "failure",
        "message": "Failed to generate image info",
        "name": "image_name",
        "file_ref": "Images/image_name",
        "alt_text": "",
        "classification": "",
        "keywords": []
      }
    ]
  }
}

Responses:

Status Code	Description	Content-Type
200	Successful Response - Status retrieved successfully	application/json
400	Bad Request - Invalid job ID format	application/json
401	Unauthorized - Invalid or missing authentication token	application/json
404	Job not found - Job with job_id 12345 not found.	application/json
422	Validation Error - Invalid job_id format. Please provide a valid job_id.	application/json
500	Internal Server Error - An error occurred while fetching the job status: [error details].	application/json

Alt-Text API Documentation

Single Image Alt-Text Generation API​

/cl/alttext/api/v2/​

Request Payload:​

Sample Code:​

Example Response:​

Bulk Alt-Text Generation API​

/cl/alttext/api/v3/​

Request Payload:​

Sample Code:​

Example Response:​

Status Check API​

/cl/alttext/api/v3/status/{job_id}​

Request Payload:​

Sample Code:​

Example Response:​

Single Image Alt-Text Generation API

/cl/alttext/api/v2/

Request Payload:

Sample Code:

Example Response:

Bulk Alt-Text Generation API

/cl/alttext/api/v3/

Request Payload:

Sample Code:

Example Response:

Status Check API

/cl/alttext/api/v3/status/{job_id}

Request Payload:

Sample Code:

Example Response: