Name: Lucataco Captions – AI Image Descriptions | $0.02/call | API.market
Brand: magicapi
SKU: api-magicapi-ai-image-caption-generator
Availability: InStock
Rating: 5.00 (1 reviews)
Author: API Market

Shashank Agarwal

# 📝 Instant Image Caption Generator API (lucataco/image-caption)

## Overview
The Instant Image Caption Generator API provides a fast and easy way to generate concise, descriptive captions for any image. Powered by GPT-5-mini, this API offers quick, high-quality captions that can be easily integrated into your apps or workflows. From social media posting to automated content pipelines, this API instantly analyzes your images and returns relevant textual descriptions.

## Features
- Automatically analyzes and captions images in seconds  
- Flexible prompts to customize the style or detail of the caption  
- High accuracy for diverse industries and image types  
- Seamless JSON responses for quick integration into existing systems  

## Use Cases
Below are several practical use cases optimized for different industries and scenarios:

1. Social Media Automation  
   • Automatically generate entertaining or informative captions for user-submitted images on a social platform.  
   • Save time and reduce manual caption writing by leveraging AI-driven descriptions.

2. E-commerce Product Listings  
   • Quickly create engaging product descriptions for new product images.  
   • Ensure consistent, high-quality product captions to improve searchability and SEO ranking.

3. Digital Asset Management  
   • Automatically tag and label thousands of images with relevant descriptions for better organization and retrieval.  
   • Use the AI-generated captions as metadata to enhance search functionality.

4. Content Creation for Blogs and News  
   • Speed up editorial processes by having the AI model generate quick captions or lead-in text for article images.  
   • Maintain a coherent writing style by providing custom prompts that match your publication’s voice.

5. Accessibility Enhancements  
   • Provide textual descriptions for visuals to comply with accessibility standards.  
   • Automatically create alt-text that is user-friendly and consistent.

## Visual Examples

### Example Input Image
Below is an example of an input image URL provided in the schema:

![Street taco with grilled meat, pineapple, cilantro, etc.](https://replicate.delivery/pbxt/NUpLg5V4oPfWI5Px6KduMqz8E7DK0AGxaGn0wMz4XYf4aOJ3/replicate-prediction-h1jdds1cbhrma0crg12s1cnm00.jpg)

Example input JSON:
```json
{
  "image": "https://replicate.delivery/pbxt/NUpLg5V4oPfWI5Px6KduMqz8E7DK0AGxaGn0wMz4XYf4aOJ3/replicate-prediction-h1jdds1cbhrma0crg12s1cnm00.jpg",
  "prompt": "Write a caption for this image"
}
```

### Example Output Caption
The API might return a concise and descriptive caption such as:
```
"Juicy grilled pork, sweet pineapple, red onion and fresh cilantro tucked into a charred tortilla — a perfect street-taco moment."
```

## Pricing
• Pay As You Go (PAYG) model – you only pay for the actual number of images processed  
• 1 API unit = 1 image processed  
• GET requests to check prediction status (GET /api/v1/magicapi/ai-image-caption-generator/predictions/{id}) are free and do not count toward usage  
• No monthly subscription fees or usage caps – simple per-call pricing  

## API Documentation

### Base URL
All requests should be directed to:
```
https://prod.api.market/api/v1/magicapi/ai-image-caption-generator
```

### Authentication
Use your API key to authenticate requests. Include the key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API uses asynchronous processing to generate image captions. The flow is:
1. POST a new prediction request  
2. Receive a unique prediction ID in the response  
3. Poll the GET endpoint (with the prediction ID) to check the status  
4. When status is "succeeded," you can retrieve the final caption in the response  

Processing time varies by image size, prompt complexity, etc. Use these best practices:
- Poll once per second (1s interval)  
- Maximum timeout of 600 seconds (10 minutes)  
- If status is "failed," handle the error gracefully  

### Endpoints

#### Create a prediction
POST /api/v1/magicapi/ai-image-caption-generator/predictions

• Creates a new prediction job for caption generation.  
• Make sure to include the correct model version and the required input properties.

Request Body (JSON):
```json
{
  "version": "d5ebb91a76fe0cf3daef9d4e84ab68d8cef113e334866bfd14022a62bbe60da2",
  "input": {
    "image": "https://example.com/image.jpg",
    "prompt": "Write a caption for this image"
  }
}
```

Example cURL:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-image-caption-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "d5ebb91a76fe0cf3daef9d4e84ab68d8cef113e334866bfd14022a62bbe60da2",
    "input": {
      "image": "https://example.com/image.jpg",
      "prompt": "Write a caption for this image"
    }
  }'
```

Response (201 Created) example:
```json
{
  "id": "abcd1234",
  "version": "d5ebb91a76fe0cf3daef9d4e84ab68d8cef113e334866bfd14022a62bbe60da2",
  "status": "starting",
  "created_at": "2025-08-17T17:19:38.437Z"
}
```

#### Get prediction status and results
GET /api/v1/magicapi/ai-image-caption-generator/predictions/{id}

• Retrieves the status and, if completed, the generated caption for a prediction.  
• Use this endpoint to poll until the status is "succeeded" or "failed."

Example cURL:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-image-caption-generator/predictions/abcd1234" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response (200 OK) example when succeeded:
```json
{
  "id": "abcd1234",
  "status": "succeeded",
  "output": "Juicy grilled pork, sweet pineapple, red onion and fresh cilantro tucked into a charred tortilla — a perfect street-taco moment.",
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

### Status Codes
• 200 OK – The request completed successfully  
• 201 Created – A new prediction was successfully created  
• 400 Bad Request – Invalid input or malformed request  
• 401 Unauthorized – Missing or invalid API key  
• 403 Forbidden – Valid API key but insufficient permissions  
• 404 Not Found – Resource not found (e.g., invalid prediction ID)  
• 429 Too Many Requests – Rate limit exceeded, retry after some delay  
• 500 Internal Server Error – Server-side issue  
• 503 Service Unavailable – Service is temporarily unavailable  

### Rate Limits
If you exceed usage thresholds, you may receive 429 Too Many Requests. When this happens, implement an exponential backoff or retry after a short delay. Keep your usage within your allocated limits to avoid disruptions.

### Error Handling
When an error occurs, the API returns a JSON response with an "error" field that contains a code, message, and status. For example:
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'image' parameter is required",
    "status": 400
  }
}
```
• Common errors include missing or invalid parameters.  
• Network or internal service errors may also occur (5xx range).  
• Always handle unexpected failures gracefully and implement retries where appropriate.

## Implementation Guide

### Example Code

Below are brief examples in JavaScript, Python, and cURL to demonstrate how to integrate with the asynchronous prediction process.

#### JavaScript (Node.js)

```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-image-caption-generator";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-market-key": apiKey
      },
      body: JSON.stringify({
        version: "d5ebb91a76fe0cf3daef9d4e84ab68d8cef113e334866bfd14022a62bbe60da2",
        input: inputData
      })
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second between checks

  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    // Check prediction status
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-api-market-key": apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();

    // Check status and return if completed
    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    // Handle failure
    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }

    // Wait before next poll
    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}
```

#### Python

```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ai-image-caption-generator"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }
    
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={
            "version": "d5ebb91a76fe0cf3daef9d4e84ab68d8cef113e334866bfd14022a62bbe60da2",
            "input": input_data
        }
    )
    
    if response.status_code not in [200, 201]:
        raise Exception(f"API error: {response.status_code} {response.text}")
    
    prediction = response.json()
    prediction_id = prediction["id"]
    
    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second between checks

    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        # Check prediction status
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)
        
        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        # Check status and return if completed
        if prediction["status"] == "succeeded":
            return prediction["output"]
        
        # Handle failure
        if prediction["status"] == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")

        time.sleep(POLL_INTERVAL)
    
    raise Exception("Prediction timed out after 10 minutes")
```

#### cURL

```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-image-caption-generator/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "d5ebb91a76fe0cf3daef9d4e84ab68d8cef113e334866bfd14022a62bbe60da2",
    "input": {
      "image": "https://example.com/image.jpg",
      "prompt": "Write a caption for this image"
    }
  }'

# Response (Example):
# {
#   "id": "abcd1234",
#   "status": "starting"
# }

# Step 2: Poll the status endpoint until status is "succeeded"
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-image-caption-generator/predictions/abcd1234" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
1. Cache or reuse prediction results where possible to avoid repeated calls for the same image.  
2. Poll responsibly (1 second intervals) to reduce unnecessary API calls.  
3. Use minimal prompts for speed—overly large or complex prompts can increase processing time.

## FAQ
1. Can I request multiple captions for the same image?  
   Yes. Simply call the POST endpoint again with the same image and a new prompt if desired.  

2. How quickly can I expect results?  
   Most images will complete within a few seconds, but it may vary based on server load and image complexity.  

3. Is there a limit to image size?  
   Very large images can increase processing times. If experiencing slow results, consider resizing images before sending.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello[at]api.market.

Automatically generate accurate, concise captions for any image. Powered by GPT-5-mini. From $0.02/call. Try it free on API.market.

Lucataco Captions – AI Image Descriptions | $0.02/call | API.market

📝 Instant Image Caption Generator API (lucataco/image-caption)

PAYG

MagicAPI

quick and simple—turns any image into clear captions in seconds. perfect for social posts, product listings, or making content more accessible.


Automatically generate accurate, concise captions for any image in seconds with the lucataco GPT-5-mini-powered API—perfect for social apps and automation.