{"uid":"cap_fWujE1CDyY9Sz0pqQxggt","slug":"agents-vimmerse-net-vimmerse-elements-multi-reference-image-9f63c989","name":"Vimmerse Elements – Multi-Reference Image Generation & Editing","description":"Generates or edits an image using a **main** image plus **reference** images (characters, objects, environments).\n\nPass all images as **`image_urls`**: the first URL is the main image; the rest are references. Limits depend on `option` (see field description in the schema).\n\n### Example\n\n```python\nimport requests\n\nurl = \"https://api.vimmerse.net/v2/image/elements\"\nheaders = {\n    \"X-Api-Key\": \"YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\",\n}\npayload = {\n    \"image_urls\": [\n        \"https://media.vimmerse.net/example/main.png\",\n        \"https://media.vimmerse.net/example/ref_character.png\",\n    ],\n    \"prompt\": \"Place the character naturally in the scene, photorealistic\",\n    \"option\": \"AutoI\",\n    \"aspect_ratio\": \"16:9\",\n    \"quantity\": 1,\n    \"swap_faces\": False,\n}\n\nresponse = requests.post(url, headers=headers, json=payload, timeout=300)\nresponse.raise_for_status()\nprint(response.json()[\"results\"])\n```","url":"https://agents.vimmerse.net/v2/image/elements?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"ElementsRequest","required":["image_urls"],"properties":{"option":{"type":"string","title":"Option","default":"AutoI","description":"Available values: `AutoI`, `FluxPro`, `Seedream`, `NanoBananaPro`, `FluxKontextPro`, `NanoBanana`, and `GPTImage`."},"prompt":{"type":"string","title":"Prompt","default":"","examples":["Make image more realistic."]},"quantity":{"type":"integer","title":"Quantity","default":1,"maximum":4,"minimum":1,"description":"Number of images to generate."},"async_mode":{"type":"boolean","title":"Async Mode","default":false},"image_urls":{"type":"array","items":{"type":"string"},"title":"Element Image URLs","minItems":1,"description":"The first image is the main image and the rest are reference images. Max 4 URLs for `FluxKontextPro`, 6 for `Seedream`, 8 for `FluxPro`, and 10 for `GPTImage`, `NanoBanana`, and `NanoBananaPro`."},"swap_faces":{"type":"boolean","title":"Swap Faces","default":false,"description":"Swap the resulting faces with the original faces."},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook URL"},"aspect_ratio":{"type":"string","title":"Aspect Ratio","default":"16:9","pattern":"^(\\d+):(\\d+)$","examples":["21:9","16:9","4:3","3:2","1:1","2:3","3:4","9:16","9:21"]},"enhance_image":{"type":"boolean","title":"Enhance Image","default":false,"description":"Enhances the image by applying 1× super-resolution during post-processing."}},"description":"Request body for POST /v2/image/elements. Content-Type: application/json."},"responseSchema":{"type":"object","title":"Response Elements Api V2 Image Elements Post","additionalProperties":true},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"0.12","displayCostAsset":"USDC","priceDynamic":true,"priceHint":null,"priceStatus":"priced","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"dynamic","summary":"$0.12/call (dynamic — varies by input)","primary":{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_xT6XyDkyzneMuxzUq4cr_","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"unknown","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":"agents.vimmerse.net","brandSlug":"agents-vimmerse-net-x402","brandBaseUrl":"https://agents.vimmerse.net","brandDocsUrl":null,"whatItDoes":"Generates or edits an image by compositing a main image with one or more reference images (characters, objects, environments) using a text prompt.","exampleAgentPrompt":"Take my main scene image at https://media.vimmerse.net/example/main.png and place the character from https://media.vimmerse.net/example/ref_character.png naturally into it — photorealistic style, 16:9 aspect ratio, using the AutoI model, and give me 1 result.","exampleUseCases":[{"title":"Character placement in new scene","prompt":"I have a background scene image and a separate character reference image — can you composite the character naturally into that scene in photorealistic style, 16:9 ratio, using AutoI, and give me 2 results?"},{"title":"Product lifestyle photo creation","prompt":"Take my product photo and insert it into this lifestyle background image I have, using the FluxPro model, 4:3 aspect ratio, and generate 1 image that looks like a natural marketing shot."},{"title":"Face-preserving portrait edit","prompt":"Use this portrait as my main image and this reference character image to create a new composited portrait — enable face swapping so the final faces match the originals — in 1:1 square format using GPTImage, give me 1 result."}],"resultDescription":"A JSON object with a 'results' array containing URLs or base64 data for the generated composite images. The number of images matches the requested quantity (1–4). Optional async mode returns a job ID to poll instead.","failureModes":["Invalid or inaccessible image URLs return a 4xx error","Exceeding the model-specific URL limit (e.g. more than 4 URLs for FluxKontextPro) causes a validation error","Unsupported aspect ratio format returns a pattern mismatch error","API key missing or invalid returns 401 unauthorized","Timeout on very large or slow-to-process images (client should set a long timeout, e.g. 300s)","Invalid option value returns a validation error listing accepted values"],"whenToPreferThis":"Choose this endpoint when you need to combine a main scene or base image with one or more visual references (characters, objects, or environments) into a single output image. It is distinct from pure text-to-image generation because it anchors the output to real visual inputs. Prefer it over background replacement (which only swaps the background) when you need multi-reference compositing with full-scene control and prompt guidance.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-31T00:41:40.430Z","isFirstParty":false,"canonicalSlug":"agents-vimmerse-net-vimmerse-elements-multi-reference-image-9f63c989"}