Product images for ads
Use actual screenshots, logos and product photos to ground creative generation in the customer's product.
Give the generator the real product
Upload one to three relevant images before generating an ad. For software, use a clear screenshot of the actual interface and an optional logo. Add a style reference only when its role is visual direction. The written brief still supplies product facts: a screenshot is not independent verification of performance, customer numbers, pricing or testimonials.
No advertiser setup is needed. A live campaigns:write key or the owner session can upload. A live campaigns:read key can list and read. Sandbox keys cannot access these private resources.
Upload an image
curl "$BASE_URL/api/v1/creative-references?kind=screenshot&label=Actual%20project%20dashboard" \
-H "Authorization: Bearer $MR_API_KEY" \
-H 'Idempotency-Key: product-dashboard-v1' \
-H 'Content-Type: image/png' \
--data-binary @dashboard.png
Send raw image bytes, not JSON or multipart. The kind and label query parameters are required. Use each once; no other parameters are accepted.
| kind | Intended use |
|---|---|
| screenshot | An actual product interface. Do not substitute a fictional mockup. |
| logo | The customer's actual brand mark. |
| product_photo | A photo of the actual product or packaging. |
| style_reference | Composition, palette and visual direction only; its brand and claims are not product facts. |
The label is a short description, 1–120 characters. Images must be PNG, JPEG or static WebP, no larger than 3 MiB, at least 16 pixels per side and at most 16 megapixels. The server decodes the full raster, strips metadata, fits it inside 2048 × 2048 without enlarging, and saves private PNG bytes. Very narrow images that become smaller than 16 pixels on one side are rejected. Animated or invalid images and mismatched Content-Type are rejected. Remove personal data, private customer records, secrets and material you cannot use in advertising before uploading.
Read data.id and status. A ready reference can be used immediately. The response also includes dimensions, normalized byte size and a signed preview valid for 900 seconds. Uploading creates no AI job and does not charge advertising credit. It does not make the image public.
Retry without duplicates
Keep the exact raw file, kind, label, Content-Type and Idempotency-Key. An identical replay returns the same reference. A changed upload with the same key returns idempotency_conflict. After a timeout or reference_upload_unconfirmed, repeat the original upload; a saved blob is verified before the same record becomes ready. Never overwrite an existing reference. Use a new key for an intentionally different source image.
GET /api/v1/creative-references returns up to 20 items in descending UUID order. Follow next_cursor as the cursor query parameter until null. GET /api/v1/creative-references/{id} reads one item and refreshes its preview. Both are workspace scoped, including incomplete uploads. The single-item endpoint accepts no query parameters. Reading an incomplete upload does not recover it: resend its original upload.
Private preview URLs are temporary bearer links. Do not put them in public documents, logs or ad copy. Refresh them with authenticated GET when expired. References are immutable; retained source files allow saved jobs to be revised consistently. Current capacity is 100 references per workspace; reuse existing IDs. reference_capacity requires capacity review rather than an upload retry loop.
Generate from saved references
Add reference_ids to your existing POST /api/v1/creatives brief:
{
"url": "https://example.com",
"name": "Field Notes",
"description": "A shared workspace for recording and organizing research notes.",
"audience": "Small research teams",
"benefits": ["Keep research notes in one place"],
"reference_ids": ["REPLACE_WITH_UPLOADED_REFERENCE_UUID"],
"art_direction": "Use the actual workspace screenshot as the main visual, with a clean typographic headline.",
"format": "square",
"variants": 2
}
Replace the placeholder with data.id from a successful upload. Supply one to three distinct ready references owned by this workspace. Invalid, foreign or incomplete references fail before a job is reserved. The worker checks saved content integrity before making a potentially billed model call. There is no remote-image fetch endpoint.
The supplied images go to OpenAI for both copy and visual generation. Images and their labels are untrusted source material, never executable instructions. Generation remains a separate explicitly requested operation with the existing allowance and no automatic paid retries. Read creative generation for job polling and publication.
Revisions inherit the original product references. For visual revisions the existing ad is the first image; the product references follow in their original order. Copy-only revisions preserve the original ad image. To use a different set of source references, create a new brief with new reference_ids. Existing creatives and published assets remain unchanged.
Review and publish
Image models can change fine details and text even when given a real screenshot or logo. Check readability, interface accuracy, brand details and all claims before selecting an ad. Reference images improve context; they do not prove product claims or guarantee pixel-exact reproduction or Meta approval.
The owner has the same upload, selection and reusable library under Product images in the Creative studio. Up to three selected images are included in the generated request. Only an explicit creative publish sends a finished ad image to the advertising platform; uploading a source reference does not.