Clear patterns.
Thoughtful photo features.
Reference workflows for importing, transforming, and delivering photos. Use these patterns to plan your application and map the details to your platform or API provider.
Start with one complete journey.
Choose a concrete task: import a profile picture, prepare a catalog photo, or back up selected originals. Write the acceptance criteria before choosing endpoints. Include how the person sees progress, how a failure is explained, and how an unwanted result is removed.
The examples here illustrate application-owned data and browser markup. They are not a universal SDK contract. Authentication, upload destinations, accepted formats, quotas, and job status responses depend on the provider and platform you implement.
Begin with the Photos API lifecycle guide. For mobile selections, also read the iOS access guide or Android import guide.
Separate an asset from its URLs.
Keep a stable application identifier for each photo. A public delivery URL, an expiring upload URL, and a temporary local reference have different lifetimes. Do not make any one of them the permanent definition of the asset.
| Record | Purpose |
|---|---|
| Asset | Ownership, stable identity, original metadata, and lifecycle state. |
| Original | A recoverable source, stored under an explicit access policy. |
| Recipe | The edit instructions and their version. |
| Derivative | A specific output produced from an original and a recipe. |
| Job | Processing progress, attempts, failure context, and completion. |
Make transformations explicit.
Prefer a small, versioned vocabulary over loosely ordered operations. Document the units, ranges, and order. Decide whether a size is a hard crop, a maximum boundary, or a request to enlarge. Keep the original available so an accepted recipe can be revised without editing an already compressed derivative.
{
"assetId": "photo_01",
"source": "original",
"operations": [
{ "type": "resize", "width": 1600, "fit": "inside" }
],
"output": { "format": "webp" },
"recipeVersion": 1,
"preserveOriginal": true
}Illustrative application recipe. Adapt the fields to your chosen provider.
Use conventional editing patterns for precisely specified transformations. Use AI editing workflows when the requested change needs generative interpretation, with a separate review decision.
Give incomplete work an honest state.
An upload can finish while a derivative is still processing. A device selection can exist while the desired representation remains unavailable. Separate those events in the data model and in the interface, so the application can resume from the right point.
{
"assetId": "photo_01",
"state": "processing",
"originalStored": true,
"derivativeReady": false,
"recipeVersion": 1,
"attempt": 1
}Illustrative application recipe. Adapt the fields to your chosen provider.
Set an attempt budget and make the handling of repeated work explicit. Use your provider’s documented retry behavior; a timeout is not proof that the original operation failed. Save enough state to reconcile a completed result that arrives after the client has moved on.
When work fails, offer the relevant next action: retry a transfer, select the image again, choose a supported format, or revise an edit. Do not turn every failure into a generic “try later” message.
Match the output to the layout.
Define a small set of output sizes based on your actual display slots. A thumbnail grid and a full-width editorial image need different budgets. Keep format, dimensions, and crop purpose explicit instead of serving the largest original everywhere.
<picture>
<source
type="image/webp"
srcset="/assets/images/photo-workflow-hero-photosapi-480.webp 480w,
/assets/images/photo-workflow-hero-photosapi-800.webp 800w,
/assets/images/photo-workflow-hero-photosapi-1200.webp 1200w"
sizes="(max-width: 600px) 92vw, 560px">
<img src="/assets/images/photo-workflow-hero-photosapi.png"
alt="Iridescent glass ribbon beside a lime sphere"
width="1200" height="1200" loading="lazy">
</picture>Illustrative application recipe. Adapt the fields to your chosen provider.
This markup uses the sample image included on this site. The image has an explicit aspect ratio, several width candidates, and a PNG fallback. For your product, make the sizes value describe the image’s real layout and test the browser’s chosen source at representative viewport widths.
Read the responsive image formats guide for the reasoning behind source selection and fallbacks. The HTML image standard defines the markup behavior.
Review the boundaries before launch.
Input & access
Confirm who can upload and read each image. Validate file characteristics, decoded dimensions, and resource limits. Exercise denied permissions and revoked access.
Quality & recovery
Inspect real output images. Confirm derivative identity, retained originals, and restore behavior. A green request status should correspond to a usable result.
Progress & retries
Interrupt transfers and processing. Check whether repeated work duplicates an asset, repeats a charge, or leaves the interface in an incorrect state.
Costs & retention
Model stored bytes, delivered bytes, transformations, and attempts separately. Decide which versions you retain and how deletion changes the workload.
Continue with secure uploads, AI evaluation, and the photo API cost guide.
Good documentation makes the next decision easier.
Explore complete articles with practical examples and linked primary sources.