{"id":15032,"date":"2026-10-29T13:54:23","date_gmt":"2026-10-29T11:54:23","guid":{"rendered":"https:\/\/shortpixel.com/blog\/?p=15032"},"modified":"2026-10-29T13:57:12","modified_gmt":"2026-10-29T11:57:12","slug":"generate-ai-image-seo-metadata-shortpixel-api","status":"publish","type":"post","link":"https:\/\/shortpixel.com\/blog\/generate-ai-image-seo-metadata-shortpixel-api\/","title":{"rendered":"How to Generate AI Image SEO Metadata With the ShortPixel API (cURL, PHP, JavaScript & Python Examples)"},"content":{"rendered":"\n

Search engines can analyze what’s in an image, but descriptive alt text, captions and titles still give them, and your visitors, useful context. When those fields are empty, you’re leaving all the explaining to a machine.<\/p>\n\n\n\n

For a blog with 50 images, that’s an afternoon of work. For a store with 8,000 product photos, it’s a backlog that never gets cleared.<\/p>\n\n\n\n

That’s what the ShortPixel AI Image SEO API is for. You send the URL of an image, and you get back a title, alt text, a caption and a longer description. It can also suggest a better file name. And it isn’t tied to WordPress: any website or app that can make an HTTP request can use it.<\/p>\n\n\n\n

Here’s what we’ll cover: how the two API calls work, how to get better results by giving the AI some context, and how to call it from cURL, PHP, JavaScript and Python. Further down there’s a script that tags a small product catalog and saves everything to a CSV file.<\/p>\n\n\n\n

Using WordPress? You can generate AI image metadata<\/em> straight from the Media Library<\/em><\/a> with the ShortPixel Image Optimizer<\/a> or ShortPixel AI ALT Text Generator<\/a> plugin, so you don’t need to build an API integration. This article is for custom CMSs, e-commerce platforms, DAM systems and scripts.<\/em><\/p>\n\n\n\n

How the API works<\/strong><\/h2>\n\n\n\n

It’s asynchronous.<\/strong> Generating text from an image takes a few seconds, and keeping a connection open that long doesn’t scale when you have thousands of files. So the work is split into two calls:<\/p>\n\n\n\n

    \n
  1. POST \/add-url.php queues an image and returns a job id.<\/li>\n\n\n\n
  2. POST \/get-url.php takes that id and returns the job status. When the job is finished, the generated text is in the response.<\/li>\n<\/ol>\n\n\n\n

    The base URL is https:\/\/capi-gpt.shortpixel.com, and everything is JSON (Content-Type: application\/json).<\/p>\n\n\n\n

    The image has to be public.<\/strong> Our servers download it themselves. JPG, PNG, GIF, WebP and AVIF are supported.<\/p>\n\n\n\n

    The API doesn’t publish anything.<\/strong> It generates the metadata, and saving it in your CMS or database is up to you.<\/p>\n\n\n\n

    Authentication<\/strong><\/h2>\n\n\n\n

    Your ShortPixel API key goes in the Authorization header. Your plan must include the AI Image SEO feature.<\/p>\n\n\n\n

    Authorization: ApiKey YOUR_API_KEY<\/p>\n\n\n\n

    Calls made with the key also return a session token (JWT) that’s valid for one hour. You can send it instead of the key, as Authorization: Bearer YOUR_JWT. Once it expires, the API answers with HTTP 401 and you have to authenticate with the key again. If your integration makes only a few calls, sending the key every time is simpler.<\/p>\n\n\n\n

    One key per site.<\/strong> We recommend creating an alias API key for each site and setting its allowed domains. Requests for images on any other domain are then rejected.<\/p>\n\n\n\n

    Keep the key on your server.<\/strong> It should never appear in browser or mobile app code.<\/p>\n\n\n\n

    Submit an image<\/strong><\/h2>\n\n\n\n

    Only url is required. You get back just the fields you ask for.<\/p>\n\n\n\n

    Field<\/strong><\/td>What it does<\/strong><\/td><\/tr>
    url<\/td>Public image URL<\/td><\/tr>
    version<\/td>Recommended: send “v_2”. Your quota is then checked up front, so an over-quota request is rejected immediately<\/td><\/tr>
    languages<\/td>Output language as an ISO 639-1 code (en, de), optionally with a country (pt-BR). Default is en<\/td><\/tr>
    context<\/td>General description of the image or page, up to 500 characters<\/td><\/tr>
    title<\/td>Max 100 characters, default 20<\/td><\/tr>
    alt<\/td>Max 200 characters, default 72<\/td><\/tr>
    caption<\/td>Max 250 characters, default 128<\/td><\/tr>
    image_description<\/td>Max 500 characters, default 300<\/td><\/tr>
    file<\/td>SEO-friendly file name, 1 to 100 characters, default 48<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    title, alt, caption, image_description and file are objects. Each takes chars, the maximum length, and an optional context with instructions for that field only.<\/p>\n\n\n\n

    Here’s a request for a product photo:<\/p>\n\n\n\n

    {\n\n\u00a0\u00a0\"url\": \"https:\/\/example.com\/images\/IMG_2041.jpg\",\n\n\u00a0\u00a0\"version\": \"v_2\",\n\n\u00a0\u00a0\"languages\": \"en\",\n\n\u00a0\u00a0\"context\": \"Product photo for an online garden furniture store\",\n\n\u00a0\u00a0\"title\": { \"chars\": 60 },\n\n\u00a0\u00a0\"alt\": { \"chars\": 120, \"context\": \"describe for accessibility and search\" },\n\n\u00a0\u00a0\"caption\": { \"chars\": 150 },\n\n\u00a0\u00a0\"image_description\": { \"chars\": 300 },\n\n\u00a0\u00a0\"file\": {\n\n\u00a0\u00a0\u00a0\u00a0\"existing_filename\": \"IMG_2041\",\n\n\u00a0\u00a0\u00a0\u00a0\"prefer_keep_filename_if_relevant\": true,\n\n\u00a0\u00a0\u00a0\u00a0\"chars\": 60\n\n\u00a0\u00a0},\n\n\u00a0\u00a0\"use_parent_post_title\": true,\n\n\u00a0\u00a0\"parent_post_title\": \"Teak garden bench, 3 seats\",\n\n\u00a0\u00a0\"use_parent_post_category\": true,\n\n\u00a0\u00a0\"parent_post_category_list\": [\"Garden furniture\", \"Benches\"]\n\n}<\/code><\/pre>\n\n\n\n
    If the job was queued, the response contains an id:<\/p>\n\n\n\n
    { \"id\": 3786, \"status\": 0 }<\/code><\/pre>\n\n\n\n
    If it contains error instead, no job was created.<\/p>\n\n\n\n
    Give the AI some context<\/strong><\/h3>\n\n\n\n
    This is the part that makes the biggest difference. A model that only sees pixels will describe your bench as “a wooden bench on grass.” Accurate, but not very useful. Tell the API the page is about a three-seat teak bench from a garden furniture store, and you can get a much more relevant description. It’s still AI-generated text, so read it before it goes live, especially for products.<\/p>\n\n\n\n
    You can pass context in three places:<\/p>\n\n\n\n
      \n
    • Top level:<\/strong> context applies to the whole request, for example the kind of store you run.<\/li>\n\n\n\n
    • Per field:<\/strong> context inside a field applies to that field only, like “describe for accessibility and search” on alt.<\/li>\n\n\n\n
    • Page data:<\/strong> parent_post_title and parent_post_category_list send the title and categories of the page that shows the image. Turn them on with use_parent_post_title and use_parent_post_category.<\/li>\n<\/ul>\n\n\n\n
      File names<\/strong><\/h3>\n\n\n\n
      Add a file object and the result includes generated_file_name, a lowercase slug without extension, like teak-garden-bench-three-seats. Pass the current name, without extension, in existing_filename. With prefer_keep_filename_if_relevant set to true, you get a new name only if the current one isn’t good for SEO. If generated_file_name is missing from the result, keep the name you have.<\/p>\n\n\n\n
      Get the result<\/strong><\/h2>\n\n\n\n
      Poll \/get-url.php with the job id until the status is 2, -1 or -2. All three are final.<\/p>\n\n\n\n
      { \"id\": 3786 }<\/code><\/pre>\n\n\n\n
      Status<\/strong><\/td>Meaning<\/strong><\/td>What to do<\/strong><\/td><\/tr>
      0<\/td>Queued<\/td>Poll again later<\/td><\/tr>
      1<\/td>Processing<\/td>Poll again later<\/td><\/tr>
      2<\/td>Finished<\/td>Save the generated fields<\/td><\/tr>
      -1<\/td>Failed (download error, timeout, quota\u2026)<\/td>Read error, fix the cause, submit again<\/td><\/tr>
      -2<\/td>Image host temporarily blocked<\/td>Stop polling, submit again in about an hour<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
      Wait about 5 seconds after submitting, then a little longer before each new check. A finished job looks like this:<\/p>\n\n\n\n
      {\n\n\u00a0\u00a0\"id\": 3786,\n\n\u00a0\u00a0\"status\": 2,\n\n\u00a0\u00a0\"title\": \"Teak Garden Bench with Three Seats\",\n\n\u00a0\u00a0\"alt\": \"Three-seat teak wooden bench on a green lawn\",\n\n\u00a0\u00a0\"caption\": \"Our teak bench, built to last outdoors in any season.\",\n\n\u00a0\u00a0\"image_description\": \"A natural teak garden bench with slatted seat and backrest ...\",\n\n\u00a0\u00a0\"generated_file_name\": \"teak-garden-bench-three-seats\"\n\n}<\/code><\/pre>\n\n\n\n
      Store the text right away.<\/strong> Results can be read for 7 days. After that, finished and failed jobs are deleted.<\/p>\n\n\n\n
      Code examples<\/strong><\/h2>\n\n\n\n
      The PHP, JavaScript and Python examples do the same thing: they submit one image, poll with a growing delay and print the result. They stop with an error if the response contains error or the HTTP request fails.<\/p>\n\n\n\n
      cURL can’t wait and poll on its own, so here you run the two calls by hand.<\/p>\n\n\n\n
      cURL<\/strong><\/h3>\n\n\n\n
      curl -s -X POST https:\/\/capi-gpt.shortpixel.com\/add-url.php \\\n\n\u00a0\u00a0-H \"Authorization: ApiKey $SHORTPIXEL_API_KEY\" \\\n\n\u00a0\u00a0-H \"Content-Type: application\/json\" \\\n\n\u00a0\u00a0-d '{\"url\":\"https:\/\/example.com\/images\/bench.jpg\",\"version\":\"v_2\",\"languages\":\"en\",\"alt\":{\"chars\":120},\"title\":{\"chars\":60}}'<\/code><\/pre>\n\n\n\n
      The response contains a job id. Put it in the second call (replace 3786) and repeat it until the status is 2, -1 or -2:<\/p>\n\n\n\n
      curl -s -X POST https:\/\/capi-gpt.shortpixel.com\/get-url.php \\\n  -H \"Authorization: ApiKey $SHORTPIXEL_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\"id\":3786}'<\/code><\/pre>\n\n\n\n
      PHP<\/strong><\/h3>\n\n\n\n
      <?php\n\nconst BASE = 'https:\/\/capi-gpt.shortpixel.com';\n\nfunction capi(string $path, array $body): array {\n\n\u00a0\u00a0\u00a0\u00a0$ch = curl_init(BASE . path);curlsetoptarray(ch, [\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0CURLOPT_POST => true,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0CURLOPT_RETURNTRANSFER => true,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0CURLOPT_TIMEOUT => 30,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0CURLOPT_HTTPHEADER => [\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0'Authorization: ApiKey ' . getenv('SHORTPIXEL_API_KEY'),\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0'Content-Type: application\/json',\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0],\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0CURLOPT_POSTFIELDS => json_encode($body),\n\n\u00a0\u00a0\u00a0\u00a0]);\n\n\u00a0\u00a0\u00a0\u00a0raw=curlexec(ch);\n\n\u00a0\u00a0\u00a0\u00a0if ($raw === false) {\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0err=curlerror(ch);\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0curl_close($ch);\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0throw new RuntimeException('Network error: ' . $err);\n\n\u00a0\u00a0\u00a0\u00a0}\n\n\u00a0\u00a0\u00a0\u00a0code=curlgetinfo(ch, CURLINFO_HTTP_CODE);\n\n\u00a0\u00a0\u00a0\u00a0curl_close($ch);\n\n\u00a0\u00a0\u00a0\u00a0res=jsondecode(raw, true) ?? [];\n\n\u00a0\u00a0\u00a0\u00a0if (isset($res['error'])) {\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0throw new RuntimeException($res['error']);\n\n\u00a0\u00a0\u00a0\u00a0}\n\n\u00a0\u00a0\u00a0\u00a0if ($code >= 400) {\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0throw new RuntimeException(\"HTTP $code\");\n\n\u00a0\u00a0\u00a0\u00a0}\n\n\u00a0\u00a0\u00a0\u00a0return $res;\n\n}\n\n$job = capi('\/add-url.php', [\n\n\u00a0\u00a0\u00a0\u00a0'url' => 'https:\/\/example.com\/images\/bench.jpg',\n\n\u00a0\u00a0\u00a0\u00a0'version' => 'v_2',\n\n\u00a0\u00a0\u00a0\u00a0'languages' => 'en',\n\n\u00a0\u00a0\u00a0\u00a0'title' => ['chars' => 60],\n\n\u00a0\u00a0\u00a0\u00a0'alt' => ['chars' => 120],\n\n]);\n\n$delay = 5;\n\ndo {\n\n\u00a0\u00a0\u00a0\u00a0sleep($delay);\n\n\u00a0\u00a0\u00a0\u00a0delay=min(delay * 2, 60);\n\n\u00a0\u00a0\u00a0\u00a0$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\n
      JavaScript (Node 18+)<\/strong><\/h3>\n\n\n\n
      const BASE = 'https:\/\/capi-gpt.shortpixel.com';\n\nasync function capi(path, body) {\n\n\u00a0\u00a0const r = await fetch(BASE + path, {\n\n\u00a0\u00a0\u00a0\u00a0method: 'POST',\n\n\u00a0\u00a0\u00a0\u00a0headers: {\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0Authorization: `ApiKey ${process.env.SHORTPIXEL_API_KEY}`,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0'Content-Type': 'application\/json',\n\n\u00a0\u00a0\u00a0\u00a0},\n\n\u00a0\u00a0\u00a0\u00a0body: JSON.stringify(body),\n\n\u00a0\u00a0\u00a0\u00a0signal: AbortSignal.timeout(30000),\n\n\u00a0\u00a0});\n\n\u00a0\u00a0const data = await r.json().catch(() => ({}));\n\n\u00a0\u00a0if (data.error) throw new Error(data.error);\n\n\u00a0\u00a0if (!r.ok) throw new Error(`HTTP ${r.status}`);\n\n\u00a0\u00a0return data;\n\n}\n\nconst job = await capi('\/add-url.php', {\n\n\u00a0\u00a0url: 'https:\/\/example.com\/images\/bench.jpg',\n\n\u00a0\u00a0version: 'v_2',\n\n\u00a0\u00a0languages: 'en',\n\n\u00a0\u00a0title: { chars: 60 },\n\n\u00a0\u00a0alt: { chars: 120 },\n\n});\n\nlet res, delay = 5000;\n\ndo {\n\n\u00a0\u00a0await new Promise((ok) => setTimeout(ok, delay));\n\n\u00a0\u00a0delay = Math.min(delay * 2, 60000);\n\n\u00a0\u00a0res = 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\n
      Python<\/strong><\/h3>\n\n\n\n
      import 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\u00a0\u00a0\u00a0\u00a0r = requests.post(BASE + path, json=body, headers=HEADERS, timeout=30)\n\n\u00a0\u00a0\u00a0\u00a0try:\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0data = r.json()\n\n\u00a0\u00a0\u00a0\u00a0except ValueError:\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0data = {}\n\n\u00a0\u00a0\u00a0\u00a0if \"error\" in data:\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0raise RuntimeError(data[\"error\"])\n\n\u00a0\u00a0\u00a0\u00a0r.raise_for_status()\n\n\u00a0\u00a0\u00a0\u00a0return data\n\njob = capi(\"\/add-url.php\", {\n\n\u00a0\u00a0\u00a0\u00a0\"url\": \"https:\/\/example.com\/images\/bench.jpg\",\n\n\u00a0\u00a0\u00a0\u00a0\"version\": \"v_2\",\n\n\u00a0\u00a0\u00a0\u00a0\"languages\": \"en\",\n\n\u00a0\u00a0\u00a0\u00a0\"title\": {\"chars\": 60},\n\n\u00a0\u00a0\u00a0\u00a0\"alt\": {\"chars\": 120},\n\n})\n\ndelay = 5\n\nwhile True:\n\n\u00a0\u00a0\u00a0\u00a0time.sleep(delay)\n\n\u00a0\u00a0\u00a0\u00a0delay = min(delay * 2, 60)\n\n\u00a0\u00a0\u00a0\u00a0res = capi(\"\/get-url.php\", {\"id\": job[\"id\"]})\n\n\u00a0\u00a0\u00a0\u00a0if res[\"status\"] not in (0, 1):\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0break\n\nprint(res[\"title\"], res[\"alt\"])<\/code><\/pre>\n\n\n\n
      A failed job (-1) and a blocked host (-2) both come back with an error key, so these helpers raise an exception for either. In production, you’ll also want retries for temporary network errors.<\/p>\n\n\n\n
      Example: tagging a product catalog<\/strong><\/h2>\n\n\n\n
      Say you run a store with a few thousand products and no alt text at all. You probably already have what the API needs: an image URL, a product title and a category for each item.<\/p>\n\n\n\n
      The script below sends images in chunks of 50, which keeps you under the limit of 100 waiting jobs per account. Results go into a CSV file you can read before importing anything. Anything that fails goes into a second file, with the reason.<\/p>\n\n\n\n
      import csv, os, time, requests\n\nBASE = \"https:\/\/capi-gpt.shortpixel.com\"\n\nHEADERS = {\"Authorization\": f\"ApiKey {os.environ['SHORTPIXEL_API_KEY']}\"}\n\nCHUNK = 50\u00a0 # stay under the 100 waiting jobs limit\n\nclass ApiError(Exception):\n\n\u00a0\u00a0\u00a0\u00a0\"\"\"The API answered, but rejected the request. Retrying won't help.\"\"\"\n\ndef post(path, body):\n\n\u00a0\u00a0\u00a0\u00a0r = requests.post(BASE + path, json=body, headers=HEADERS, timeout=30)\n\n\u00a0\u00a0\u00a0\u00a0r.raise_for_status()\n\n\u00a0\u00a0\u00a0\u00a0data = r.json()\n\n\u00a0\u00a0\u00a0\u00a0# Failed jobs (-1, -2) also carry \"error\", but together with \"status\"\n\n\u00a0\u00a0\u00a0\u00a0if \"error\" in data and \"status\" not in data:\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0raise ApiError(data[\"error\"])\n\n\u00a0\u00a0\u00a0\u00a0return data\n\ndef is_temporary(exc):\n\n\u00a0\u00a0\u00a0\u00a0\"\"\"Timeouts, connection errors, 429 and 5xx are worth another try.\"\"\"\n\n\u00a0\u00a0\u00a0\u00a0if isinstance(exc, requests.HTTPError):\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0code = exc.response.status_code\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0return code == 429 or code >= 500\n\n\u00a0\u00a0\u00a0\u00a0return True\n\n# (image URL, product page title, categories)\n\nproducts = [\n\n\u00a0\u00a0\u00a0\u00a0(\"https:\/\/example.com\/img\/bench.jpg\", \"Teak garden bench, 3 seats\", [\"Garden furniture\", \"Benches\"]),\n\n\u00a0\u00a0\u00a0\u00a0(\"https:\/\/example.com\/img\/parasol.jpg\", \"Cantilever parasol 3 m\", [\"Garden furniture\", \"Parasols\"]),\n\n\u00a0\u00a0\u00a0\u00a0# ...\n\n]\n\nwith open(\"seo_results.csv\", \"w\", newline=\"\", encoding=\"utf-8\") as ok_file, \\\n\n\u00a0\u00a0\u00a0\u00a0\u00a0open(\"seo_failed.csv\", \"w\", newline=\"\", encoding=\"utf-8\") as fail_file:\n\n\u00a0\u00a0\u00a0\u00a0ok, failed = csv.writer(ok_file), csv.writer(fail_file)\n\n\u00a0\u00a0\u00a0\u00a0ok.writerow([\"image_url\", \"title\", \"alt\", \"caption\"])\n\n\u00a0\u00a0\u00a0\u00a0failed.writerow([\"image_url\", \"job_id\", \"reason\"])\n\n\u00a0\u00a0\u00a0\u00a0for i in range(0, len(products), CHUNK):\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0pending = {}\u00a0 # job id -> image url\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0# 1. Submit the chunk\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0for url, page_title, cats in products[i:i + CHUNK]:\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0try:\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0job = post(\"\/add-url.php\", {\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"url\": url,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"version\": \"v_2\",\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"languages\": \"en\",\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"context\": \"Product photo for an online garden furniture store\",\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"title\": {\"chars\": 60},\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"alt\": {\"chars\": 120},\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"caption\": {\"chars\": 150},\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"use_parent_post_title\": True,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"parent_post_title\": page_title,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"use_parent_post_category\": True,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"parent_post_category_list\": cats,\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0})\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0pending[job[\"id\"]] = url\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0except (ApiError, requests.RequestException, KeyError) as e:\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0failed.writerow([url, \"\", f\"Not submitted: {e}\"])\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0# 2. Poll until every job in the chunk is final\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0errors = {job_id: 0 for job_id in pending}\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0delay = 5\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0while pending:\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0time.sleep(delay)\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0delay = min(delay * 2, 60)\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0for job_id in list(pending):\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0try:\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0res = post(\"\/get-url.php\", {\"id\": job_id})\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0except ApiError as e:\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 # definitive\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0failed.writerow([pending.pop(job_id), job_id, str(e)])\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0continue\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0except requests.RequestException as e:\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0if is_temporary(e) and errors[job_id] < 4:\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0errors[job_id] += 1\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 # keep the job, retry next round\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0continue\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0# The job may still finish: results stay readable for 7 days\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0failed.writerow([pending.pop(job_id), job_id, f\"Polling failed: {e}\"])\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0continue\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0errors[job_id] = 0\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0status = res.get(\"status\")\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0if status in (0, 1):\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0continue\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0url = pending.pop(job_id)\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0if status == 2:\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0ok.writerow([url, res.get(\"title\"), res.get(\"alt\"), res.get(\"caption\")])\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0else:\u00a0 # -1 failed, -2 host blocked\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0failed.writerow([url, job_id, res.get(\"error\", f\"Status {status}\")])\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0ok_file.flush()\n\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0fail_file.flush()<\/code><\/pre>\n\n\n\n
      When the run ends, seo_results.csv holds the text to review and import, and seo_failed.csv lists the images that need another look, with the job id and the reason. A blocked host (status -2) means you should wait about an hour and submit those images again.<\/p>\n\n\n\n
      The product’s page title and categories go into every request, which helps the AI write “Teak garden bench” instead of “wooden seat.” And the results go to a CSV first, not straight into your database, so you can read a sample before anything goes live.<\/p>\n\n\n\n
      Errors and limits<\/strong><\/h2>\n\n\n\n
      Always check for an<\/strong> error<\/strong> key.<\/strong> Rejections like an exceeded quota come back as HTTP 200 with {“error”: “…”} and no job id, so looking only at the status code isn’t enough. Other HTTP codes are used for malformed requests (400), authentication problems (401) and unknown jobs (404).<\/p>\n\n\n\n
      Then there are the limits:<\/p>\n\n\n\n