CartVisualCreate account

Should I use Claid’s upload endpoint when my product image is still local or private?

Use Claid’s upload route when your workflow has the source image bytes on a computer or server and does not want to provide an image URL. Put those bytes in the `file` multipart part and the edit instructions in the JSON `data` part. Treat delivery and catalog retention as separate decisions: a returned result, including a temporary URL or storage identifier, still needs your review and asset-record workflow before publication.

Published · By CartVisual editorial team

Choose the transport boundary

Make this decision before writing the edit payload. If the source is available to your workstation or server but is not being exposed as a retrievable image URL, use the upload route. If an authorized workflow already has a suitable image URL, compare that route separately; this guide addresses Claid’s direct-upload contract, not every rule for URL-based editing.

This choice controls how Claid receives the input. It does not select the output format, approve the image, or decide where your commerce team stores the result. Keep those as downstream states in the job record.

  • Record the source revision and filename before submission.
  • Send image bytes in file; do not put a filesystem path in the edit JSON.
  • Choose the route from access and transport constraints, not from the filename extension alone.

Build one request with two contracts

Claid’s documented upload request is multipart form data with a file part and a JSON part. The JSON uses the regular editing structure for processing and output instructions, but omits the input image URL because the image arrives in the file part. The API request also carries bearer authentication.

The useful configuration contrast is simple: file answers “which bytes should be processed?” while data answers “how should Claid process and store them?” Keep the two records separate in logs so a malformed edit contract is not confused with a wrong source revision.

  • Part file: source image bytes and a filename.
  • Part data: JSON containing the applicable operations and output instructions.
  • Header: bearer API key; keep the credential in the server-side workflow.
  • Record the request status and response body before selecting a recovery action.

Propagate the result through your own states

Model the workflow as four states: submitted, returned, retained, and approved. A successful API response can move a job from submitted to returned. It does not by itself prove that your internal asset store contains the approved file or that the product listing is ready.

Inspect the returned output metadata against the destination requirement, then move the asset to retained only after your workflow has copied or otherwise recorded it according to policy. Move it to approved only after product-image review. This state separation prevents a delivery field from being mistaken for a durable catalog record.

  • Returned: capture the response’s actual output metadata and delivery field.
  • Retained: associate the accepted result with your internal asset ID and source revision.
  • Approved: complete the product-image review before attaching it to a listing.
  • If the request fails, preserve the status and body; diagnose the transport, contract, authorization, or account condition from the actual response.

Worked example: private bottle source

Hypothetical seller scenario. bottle-front-v4.jpg is on a private production server, and the seller wants a 1,000-pixel-wide edit without exposing a source URL. The seller chooses upload, then maps each request element to the intended state transition. The request is not executed, and no response is claimed.

Workflow questionHypothetical recordNext action
How does Claid receive the source?Private server; source bytes availableSend bytes as file
What should Claid do?Resize width to 1,000; keep background unchangedPut the edit instructions in JSON data
What came back?Actual output metadata and delivery fieldInspect format and dimensions; move to returned
Can the listing use it?Internal durable-asset record is absentRetain and review before approval or publication

Source and evidence scope

Prepared by the CartVisual editorial team with AI assistance. Competitor behavior is documented rather than independently executed for this guide.

Claid: Upload API Reference

Official source snapshot checked .

The supplied official Claid Upload API Reference documents direct multipart image upload, the file and data parts, authentication headers, the upload endpoint, response structure, and output metadata. It does not establish all rules for Claid’s regular URL-based request, downstream catalog storage, or publication approval. No Claid request was executed.

Related decisions

Browse ecommerce creative workflows