Send the URL of a public image and get back SEO metadata for it: title, alt text, caption, long description and, optionally, an SEO-friendly file name. The API works on any website or platform, not only WordPress.<\/p>\n\n\n\n
The API is asynchronous and has two calls:<\/p>\n\n\n\n
Base URL: https:\/\/capi-gpt.shortpixel.com. All requests and responses are JSON (Content-Type: application\/json).<\/p>\n\n\n\n
The image must be reachable over the public internet, because our servers download it. Supported formats: JPG\/JPEG\/JPE, PNG, GIF, WebP, AVIF. Image URLs can be up to 1000 characters long.<\/p>\n\n\n\n
Use your ShortPixel API key in the Authorization header. The key comes from your ShortPixel account, and your account plan must include the AI (Image SEO) feature.<\/p>\n\n\n\n
Authorization: ApiKey YOUR_API_KEY<\/code><\/pre>\n\n\n\nA call made with an API key returns a session token (JWT) that is valid for 1 hour. You get it in two places: the X-New-JWT response header, and the jwt field of the JSON body (next to user_id). For the next hour you can send that token instead of the key:<\/p>\n\n\n\n
Authorization: Bearer YOUR_JWT<\/code><\/pre>\n\n\n\nThere is no automatic fallback once the token expires: the call returns HTTP 401, and you have to authenticate again with ApiKey. Integrations that only make a few calls can simply send ApiKey every time.<\/p>\n\n\n\n
One key per site (recommended).<\/strong> Create an alias API key in your ShortPixel account and set its allowed domains. Requests for images on any other domain are then rejected with The domain <domain> is not allowed for this API key. Every image domain you send is also linked to your ShortPixel account. On free accounts, a domain that is already used by other free accounts is rejected.<\/p>\n\n\n\nKeep the key on your server. Never embed it in browser or mobile app code.<\/p>\n\n\n\n
Submit an image: POST \/add-url.php<\/strong><\/h1>\n\n\n\nSend the image URL plus one object for each field you want generated. Only the fields you request are generated. Each object takes a maximum length (chars) and optional instructions (context).<\/p>\n\n\n\nField<\/strong><\/th>Type<\/strong><\/th>Required<\/strong><\/th>Notes<\/strong><\/th><\/tr><\/thead>url<\/td> string<\/td> yes<\/td> Public image URL, up to 1000 characters<\/td><\/tr> version<\/td> string<\/td> recommended<\/td> Send “v_2”. Quota is then checked up front, and the call is rejected right away when you are over quota<\/td><\/tr> languages<\/td> string<\/td> no<\/td> Output language: ISO 639-1 code (en, de), optionally with a country (pt-BR). Default en<\/td><\/tr> context<\/td> string<\/td> no<\/td> General description of the image or page, up to 500 characters<\/td><\/tr> title<\/td> object<\/td> no<\/td> Generates title. chars max 100, default 20<\/td><\/tr> alt<\/td> object<\/td> no<\/td> Generates alt. chars max 200, default 72<\/td><\/tr> caption<\/td> object<\/td> no<\/td> Generates caption. chars max 250, default 128<\/td><\/tr> image_description<\/td> object<\/td> no<\/td> Generates image_description. chars max 500, default 300<\/td><\/tr> file<\/td> object<\/td> no<\/td> Generates generated_file_name, a lowercase slug without extension. chars 1\u2013100, default 48. Also takes existing_filename and prefer_keep_filename_if_relevant (see below)<\/td><\/tr> use_parent_post_title + parent_post_title<\/td> bool + string<\/td> no<\/td> Title of the page that shows the image, used as context. Up to 500 characters<\/td><\/tr> use_parent_post_category + parent_post_category_list<\/td> bool + string[]<\/td> no<\/td> Categories or tags of that page, used as context. Up to 50 items<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\nEach context is capped at 500 characters. chars values above the maximum are reduced to the maximum.<\/p>\n\n\n\n
All fields with their default values.<\/strong> Leave out any object you don’t need; only url is required.<\/p>\n\n\n\n{\n\n \"url\": \"https:\/\/example.com\/wp-content\/uploads\/2025\/dog.jpg\",\n\n \"languages\": \"en\",\n\n \"context\": \"optional global context\",\n\n \"version\": \"v_2\",\n\n \"file\": {\n\n \"chars\": 48,\n\n \"context\": \"filename with SEO keywords\",\n\n \"prefer_keep_filename_if_relevant\": true,\n\n \"existing_filename\": \"my-dog-in-garden\"\n\n },\n\n \"title\": {\n\n \"chars\": 20,\n\n \"context\": \"...\"\n\n },\n\n \"alt\": {\n\n \"chars\": 72,\n\n \"context\": \"...\"\n\n },\n\n \"caption\": {\n\n \"chars\": 128,\n\n \"context\": \"...\"\n\n },\n\n \"image_description\": {\n\n \"chars\": 300,\n\n \"context\": \"...\"\n\n },\n\n \"use_parent_post_title\": true,\n\n \"parent_post_title\": \"Dogs in the garden\",\n\n \"use_parent_post_category\": true,\n\n \"parent_post_category_list\": [\"Photography\", \"Dogs\"]\n\n}<\/code><\/pre>\n\n\n\nFile name.<\/strong> Pass the current name without its extension in file.existing_filename. When prefer_keep_filename_if_relevant is true, generated_file_name is returned only if the current name is not good for SEO. When the key is missing from the result, keep your current file name.<\/p>\n\n\n\nExample request<\/strong><\/p>\n\n\n\n{\n\n \"url\": \"https:\/\/example.com\/images\/IMG_2041.jpg\",\n\n \"version\": \"v_2\",\n\n \"languages\": \"en\",\n\n \"context\": \"Product photo for an online garden furniture store\",\n\n \"title\": { \"chars\": 60 },\n\n \"alt\": { \"chars\": 120, \"context\": \"describe for accessibility and search\" },\n\n \"caption\": { \"chars\": 150 },\n\n \"image_description\": { \"chars\": 300 },\n\n \"file\": { \"existing_filename\": \"IMG_2041\", \"prefer_keep_filename_if_relevant\": true, \"chars\": 60 },\n\n \"use_parent_post_title\": true,\n\n \"parent_post_title\": \"Teak garden bench, 3 seats\",\n\n \"use_parent_post_category\": true,\n\n \"parent_post_category_list\": [\"Garden furniture\", \"Benches\"]\n\n}<\/code><\/pre>\n\n\n\nThe job was queued if the response contains an id:<\/p>\n\n\n\n
{ \"id\": 3786, \"status\": 0 }<\/code><\/pre>\n\n\n\nOtherwise the response holds error and no job was created (see Errors). The response may also include warning when your account is over its fair-usage threshold. The job is still accepted, but it is processed with a delay of 20\u201360 seconds.<\/p>\n\n\n\n
Get the result: POST \/get-url.php<\/strong><\/h1>\n\n\n\nPoll with the job id until status is 2, -1 or -2. All three are final. Start about 5 seconds after submitting, then wait a little longer before each new check. You can only read your own jobs. Any other id returns HTTP 404.<\/p>\n\n\n\n
{ \"id\": 3786 }<\/code><\/pre>\n\n\n\nstatus<\/strong><\/th>Meaning<\/strong><\/th>What to do<\/strong><\/th><\/tr><\/thead>0<\/td> Queued<\/td> Poll again later<\/td><\/tr> 1<\/td> Processing<\/td> Poll again later<\/td><\/tr> 2<\/td> Finished: the generated fields are in the response<\/td> Save them<\/td><\/tr> -1<\/td> Failed: the reason is in error (download failed, timeout, quota, …)<\/td> Fix the cause and submit again<\/td><\/tr> -2<\/td> Image host temporarily blocked (see Errors)<\/td> Stop polling. Submit again in about an hour<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\nA rejected add-url creates no job. A job that was accepted always ends as 2, -1 or -2.<\/p>\n\n\n\n
A finished response contains only the fields you requested:<\/p>\n\n\n\n
{\n\n \"id\": 3786,\n\n \"status\": 2,\n\n \"title\": \"Teak Garden Bench with Three Seats\",\n\n \"alt\": \"Three-seat teak wooden bench on a green lawn\",\n\n \"caption\": \"Our teak bench, built to last outdoors in any season.\",\n\n \"image_description\": \"A natural teak garden bench with slatted seat and backrest ...\",\n\n \"generated_file_name\": \"teak-garden-bench-three-seats\"\n\n}<\/code><\/pre>\n\n\n\nResults can be read again as often as you need, for 7 days. After 7 days finished and failed jobs are deleted, so store the fields on your side.<\/p>\n\n\n\n
Errors and limits<\/strong><\/h1>\n\n\n\nAlways check the response body for an error key. Business rejections come back as HTTP 200 with {“error”: “…”} and no id. Only malformed requests, authentication and unknown jobs use other HTTP codes.<\/p>\n\n\n\nHTTP<\/strong><\/th>Example<\/strong> error<\/strong><\/th>Cause<\/strong><\/th><\/tr><\/thead>400<\/td> Invalid or missing ‘url’. \/ Missing or invalid ‘id’.<\/td> Missing or malformed field, or the body is not valid JSON<\/td><\/tr> 401<\/td> Unauthorized<\/td> Missing or wrong API key, or expired JWT<\/td><\/tr> 404<\/td> Not found \/ Job not found.<\/td> Unknown job, or the job belongs to another account<\/td><\/tr> 200<\/td> Too many jobs in queue. Please wait for some to complete.<\/td> You already have 100 jobs waiting<\/td><\/tr> 200<\/td> AI Image SEO quota reached (N images). Upgrade to the Unlimited AI plan.<\/td> Plan quota used up (checked up front only with “version”: “v_2”)<\/td><\/tr> 200<\/td> The domain <domain> is not allowed for this API key.<\/td> The image domain is not in the key’s allow list<\/td><\/tr> 200<\/td> This image host is temporarily blocked …<\/td> Over 90% of recent jobs for that host failed<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\nQueue limit.<\/strong> Each account can have up to 100 jobs waiting. Submit in batches and poll; send more as jobs finish.<\/p>\n\n\n\nHost block.<\/strong> When at least 90% of the jobs for one image host fail within an hour (minimum 3 jobs), that host is blocked for 1 hour. This usually happens when a site blocks our downloader, for example with a firewall, hotlink protection or a login wall. Jobs already queued for that host switch to status -2.<\/p>\n\n\n\nQuota.<\/strong> Every processed image counts toward the AI Image SEO quota of your plan. Unlimited plans have a fair-usage threshold. Above it, jobs are still processed, but with a delay of 20\u201360 seconds, and add-url returns a warning.<\/p>\n\n\n\nCode examples<\/strong><\/h1>\n\n\n\ncurl<\/strong><\/p>\n\n\n\ncurl -s -X POST https:\/\/capi-gpt.shortpixel.com\/add-url.php \\\n\n -H \"Authorization: ApiKey $SHORTPIXEL_API_KEY\" \\\n\n -H \"Content-Type: application\/json\" \\\n\n -d '{\"url\":\"https:\/\/example.com\/images\/bench.jpg\",\"version\":\"v_2\",\"languages\":\"en\",\"alt\":{\"chars\":120},\"title\":{\"chars\":60}}'\n\ncurl -s -X POST https:\/\/capi-gpt.shortpixel.com\/get-url.php \\\n\n -H \"Authorization: ApiKey $SHORTPIXEL_API_KEY\" \\\n\n -H \"Content-Type: application\/json\" \\\n\n -d '{\"id\":3786}'<\/code><\/pre>\n\n\n\nPHP<\/strong><\/p>\n\n\n\n<?php\n\nconst BASE = 'https:\/\/capi-gpt.shortpixel.com';\n\nfunction capi(string $path, array $body): array {\n\n $ch = curl_init(BASE . $path);\n\n curl_setopt_array($ch, [\n\n CURLOPT_POST => true,\n\n CURLOPT_RETURNTRANSFER => true,\n\n CURLOPT_HTTPHEADER => [\n\n 'Authorization: ApiKey ' . getenv('SHORTPIXEL_API_KEY'),\n\n 'Content-Type: application\/json',\n\n ],\n\n CURLOPT_POSTFIELDS => json_encode($body),\n\n ]);\n\n $res = json_decode(curl_exec($ch), true) ?? [];\n\n curl_close($ch);\n\n if (isset($res['error'])) {\n\n throw new RuntimeException($res['error']);\n\n }\n\n return $res;\n\n}\n\n$job = capi('\/add-url.php', [\n\n 'url' => 'https:\/\/example.com\/images\/bench.jpg',\n\n 'version' => 'v_2',\n\n 'languages' => 'en',\n\n 'title' => ['chars' => 60],\n\n 'alt' => ['chars' => 120],\n\n]);\n\n$delay = 5;\n\ndo {\n\n sleep($delay);\n\n $delay = min($delay * 2, 60);\n\n $res = capi('\/get-url.php', ['id' => $job['id']]);\n\n} while (in_array($res['status'], [0, 1], true));\n\necho $res['alt'], PHP_EOL;<\/code><\/pre>\n\n\n\nJavaScript (Node 18+)<\/strong><\/p>\n\n\n\nconst BASE = 'https:\/\/capi-gpt.shortpixel.com';\n\nasync function capi(path, body) {\n\n const r = await fetch(BASE + path, {\n\n method: 'POST',\n\n headers: {\n\n Authorization: `ApiKey ${process.env.SHORTPIXEL_API_KEY}`,\n\n 'Content-Type': 'application\/json',\n\n },\n\n body: JSON.stringify(body),\n\n });\n\n const data = await r.json();\n\n if (data.error) throw new Error(data.error);\n\n return data;\n\n}\n\nconst job = await capi('\/add-url.php', {\n\n url: 'https:\/\/example.com\/images\/bench.jpg',\n\n version: 'v_2',\n\n languages: 'en',\n\n title: { chars: 60 },\n\n alt: { chars: 120 },\n\n});\n\nlet res, delay = 5000;\n\ndo {\n\n await new Promise((ok) => setTimeout(ok, delay));\n\n delay = Math.min(delay * 2, 60000);\n\n res = await capi('\/get-url.php', { id: job.id });\n\n} while (res.status === 0 || res.status === 1);\n\nconsole.log(res.title, res.alt);<\/code><\/pre>\n\n\n\nPython<\/strong><\/p>\n\n\n\nimport os, time, requests\n\nBASE = \"https:\/\/capi-gpt.shortpixel.com\"\n\nHEADERS = {\"Authorization\": f\"ApiKey {os.environ['SHORTPIXEL_API_KEY']}\"}\n\ndef capi(path, body):\n\n data = requests.post(BASE + path, json=body, headers=HEADERS, timeout=30).json()\n\n if \"error\" in data:\n\n raise RuntimeError(data[\"error\"])\n\n return data\n\njob = capi(\"\/add-url.php\", {\n\n \"url\": \"https:\/\/example.com\/images\/bench.jpg\",\n\n \"version\": \"v_2\",\n\n \"languages\": \"en\",\n\n \"title\": {\"chars\": 60},\n\n \"alt\": {\"chars\": 120},\n\n})\n\ndelay = 5\n\nwhile True:\n\n time.sleep(delay)\n\n delay = min(delay * 2, 60)\n\n res = capi(\"\/get-url.php\", {\"id\": job[\"id\"]})\n\n if res[\"status\"] not in (0, 1):\n\n break\n\nprint(res[\"title\"], res[\"alt\"])<\/code><\/pre>\n\n\n\nIn these examples, a failed job (-1) or a blocked host (-2) raises an error, because the response includes error.<\/p>\n","protected":false},"excerpt":{"rendered":"
Send the URL of a public image and get back SEO metadata for it: title, alt text, caption, long description and, optionally, an SEO-friendly file name. The API works on any website or platform, not only WordPress. The API is asynchronous and has two calls: Base URL: https:\/\/capi-gpt.shortpixel.com. All requests and responses are JSON (Content-Type: […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","template":"","meta":{"footnotes":""},"doc_category":[37,61,59],"glossaries":[],"doc_tag":[],"class_list":["post-2996","docs","type-docs","status-publish","hentry","doc_category-shortpixel-image-optimizer","doc_category-tools-developer-api","doc_category-wordpress-plugins"],"blocksy_meta":[],"year_month":"2026-10","word_count":2031,"total_views":"6","reactions":{"happy":"0","normal":"0","sad":"0"},"author_info":{"name":"admin","author_nicename":"admin_mdli53m5","author_url":"https:\/\/kb.shortpixel.com\/author\/admin_mdli53m5\/"},"doc_category_info":[{"term_name":"ShortPixel Image Optimizer","term_url":"https:\/\/kb.shortpixel.com\/knowledge-base\/category\/shortpixel-image-optimizer\/"},{"term_name":"Tools & Developer API","term_url":"https:\/\/kb.shortpixel.com\/knowledge-base\/category\/tools-developer-api\/"},{"term_name":"WordPress Plugins","term_url":"https:\/\/kb.shortpixel.com\/knowledge-base\/category\/wordpress-plugins\/"}],"doc_tag_info":[],"knowledge_base_info":[],"knowledge_base_slug":[],"_links":{"self":[{"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/docs\/2996","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/types\/docs"}],"author":[{"embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/comments?post=2996"}],"version-history":[{"count":3,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/docs\/2996\/revisions"}],"predecessor-version":[{"id":2999,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/docs\/2996\/revisions\/2999"}],"wp:attachment":[{"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/media?parent=2996"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/doc_category?post=2996"},{"taxonomy":"glossaries","embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/glossaries?post=2996"},{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/kb.shortpixel.com\/wp-json\/wp\/v2\/doc_tag?post=2996"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}