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 applicableoperationsandoutputinstructions. - 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 question | Hypothetical record | Next action |
|---|---|---|
| How does Claid receive the source? | Private server; source bytes available | Send bytes as file |
| What should Claid do? | Resize width to 1,000; keep background unchanged | Put the edit instructions in JSON data |
| What came back? | Actual output metadata and delivery field | Inspect format and dimensions; move to returned |
| Can the listing use it? | Internal durable-asset record is absent | Retain 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.
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.