AI Stock Keywords LogoLightroom Plug-in
Sign In

API Docs

POST https://www.aistockkeywords.com/api/public/v1/generate-metadata

Generates AI-powered metadata for an uploaded image file or a remotely hosted image referenced by URL.

Request
  • Method: POST
  • Content-Type: multipart/form-data (required)
  • Authorization: Bearer YOUR_API_KEY (required). Generate an API key on the account page.
  • Form Fields / Multipart Parts:
    • file (File, optional*): The image file to process. Maximum file size: 4.5 MB (uploaded).
    • fileUrl (string, optional*): HTTP/HTTPS URL to an image. Remote fetch limit: 10 MB. Must point to an image/* resource.
    *Exactly one of file or fileUrl is required. If both are supplied the uploaded file takes precedence.
  • Query Parameters:
    • contextAndInstructions (string, optional): Additional context or instructions for metadata generation.
    • numberOfKeywords (number, optional): Number of keywords to generate (default: 49).
    • shortTitle (boolean, optional): Whether to generate a short title.
    • englishLettersOnly (boolean, optional): Restrict keywords to English letters only.
    • oneWordKeywordsOnly (boolean, optional): Restrict keywords to single words only.
    • keywordsPhrasesPreferred (boolean, optional): Prefer keyword phrases over single words.
  • Legacy compatibility: apiKey remains accepted as a query parameter only when the Authorization header is absent. New integrations should use the Authorization header.
Response
  • Success (200): Returns generated metadata plus advisory image-review risks. Each risk has a stable category and concise visual evidence; an empty array means no clear signal was found. Risks are not legal advice or a submission decision.
  • Error (400): Missing or invalid credentials, file input, context length, or boolean parameters.
  • Error (401): Invalid API key.
  • Error (403): Insufficient balance.
  • Error (413): File too large (exceeds 4.5 MB limit).
  • Error (500): Internal server error.
Example Request (File Upload)
POST https://www.aistockkeywords.com/api/public/v1/generate-metadata?numberOfKeywords=6&shortTitle=true
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_KEY

file: [your image file]
Example Request (Remote URL)
POST https://www.aistockkeywords.com/api/public/v1/generate-metadata
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_KEY

fileUrl: https://example.com/path/to/image.jpg
Example Response
{
  "title": "Sunset over the mountains",
  "description": "A beautiful sunset casting warm colors over a mountain landscape.",
  "keywords": [
    "sunset",
    "mountains",
    "landscape",
    "nature",
    "sky",
    "scenery"
  ],
  "risks": [
    {
      "category": "visible_text",
      "evidence": "Readable trail sign near the foreground"
    }
  ]
}