Shopify fileCreate: 250 files per batch, 512-character alt text

Shopify's fileCreate mutation accepts at most 250 files in one call, and each file's alt text can be at most 512 characters. If you generate a catalog's worth of product images with Sume, split the list into chunks of 250, trim alt text to 512 characters before sending, and read userErrors on every response.

Everything about Shopify below comes from the fileCreate reference, read 2026-10-02. The Sume side comes from the Image docs and Jobs and results. Sume's docs do not describe a Shopify connector, so the Shopify call is yours to make.

What does fileCreate accept?

The mutation takes a files array of FileCreateInput. Per Shopify's page, originalSource (an external URL or a staged upload URL) and contentType are required; alt and filename are optional, and Shopify generates a filename when you omit one. Content types listed are IMAGE, VIDEO, EXTERNAL_VIDEO, FILE and MODEL. Created files land on the Files page of the Shopify admin.

Files process asynchronously. The fileStatus field reports progress and READY means processing finished, so a successful response does not mean the image is usable yet.

How do I get public image URLs out of Sume?

POST /v1/images blocks for up to 30 seconds and returns data[].url values on media.sume.com. When a generation runs past that budget, or you send mode: "async", you get a 202 job envelope instead and read the images from GET /v1/jobs/{id}/result. Check the status code, not the body shape.

One call can request several images with n, but the per-model ceiling is lower than the general maximum of 10, so read the catalog's n range before you size a batch. Store the Sume URL, not a provider URL: Sume mirrors outputs to its own media host and the docs tell integrations to keep that one.

What does a 250-file chunk loop look like?

This sketch sends finished Sume image URLs to Shopify in chunks. It reads the store, token and API version from the environment so no version is assumed, and it prints userErrors per chunk.

import os, requests

SHOP, TOKEN = os.environ["SHOP"], os.environ["SHOPIFY_TOKEN"]
VERSION = os.environ["SHOPIFY_API_VERSION"]
Q = """mutation($files: [FileCreateInput!]!) {
  fileCreate(files: $files) {
    files { id fileStatus }
    userErrors { field message code }
  }
}"""

def create_images(items):  # items: [(sume_image_url, alt_text)]
    for i in range(0, len(items), 250):
        files = [
            {"originalSource": url, "contentType": "IMAGE", "alt": alt[:512]}
            for url, alt in items[i:i + 250]
        ]
        r = requests.post(
            f"https://{SHOP}/admin/api/{VERSION}/graphql.json",
            headers={"X-Shopify-Access-Token": TOKEN},
            json={"query": Q, "variables": {"files": files}},
            timeout=60,
        )
        r.raise_for_status()
        print(r.json()["data"]["fileCreate"]["userErrors"])

What should I check before sending alt text?

Write alt text from the product record, not from the image model's prompt. Shopify only checks length, so a 400-character prompt pasted as alt text passes the limit and still reads badly to a screen-reader user.

Truncating at 512 characters can cut a word in half; trim at the last space instead if the text is long.

• Chunk at 250 files, even when a store has only a few hundred products.
• Keep a map of Sume job id to Shopify file id so a retry does not create duplicates.
• Poll until fileStatus is READY before attaching the file to a product.
• Video: the page lists VIDEO as a content type but does not say whether an external URL is accepted for it, so test on a draft or use the staged upload route in our staged upload post.

How many Sume generations can I run at once?

Concurrency, not batch size, decides how fast a catalog finishes. Per Generation admission, a Pro workspace processes 4 generation jobs at a time with a default queue of 20, while Scale processes 20 with a queue of 100. The dashboard Concurrency tab is the source of truth, so read your effective limit instead of trusting the static table.

Valid jobs beyond the concurrency limit are accepted as queued, which is normal; only a full queue returns 429 queue_full, and an empty balance returns 402 insufficient_credits before any work starts. For a 600-image catalog that means feeding Sume in waves sized to your queue, collecting URLs as jobs finish, and calling fileCreate once you hold 250 of them. Send an Idempotency-Key on every submit so a retry after a timeout cannot create a second paid job.

Does Sume push these files to Shopify for me?

No. The Sume docs I read describe generation, polling and media-hosting endpoints and say nothing about Shopify, so the fileCreate call, the token and the retry logic stay in your code. The tidy part is that Sume results are plain HTTPS URLs, which is exactly the input originalSource wants. For a webhook-driven version of this flow, see Shopify product video AI API with products/create webhooks.