Add the picture inline, in the text flow.
dotnet add package RecursiveAI.OneDocument.DocumentsRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using RecursiveAI.OneDocument.Documents; using var doc = Document.Create(); var png = File.ReadAllBytes("swatches.png"); doc.Body.AddPicture(png, widthPoints: 72, altText: "Blue and yellow swatches"); doc.SaveAs("swatches.docx"); Console.WriteLine("Wrote swatches.docx");
Unzip the example, then dotnet run.
This writes swatches.docx with the picture in its own paragraph. Use swatches.png from the download (24 × 12 pixels, blue on the left and yellow on the right), or replace its path with the path to any PNG or JPEG.
Wrote swatches.docxThe full program
The program puts the same picture after “Palette:” in the same paragraph. It opens the saved DOCX as a zip to read back the embedded file, alt text, and displayed size.
using System.IO.Compression; using System.Xml.Linq; using RecursiveAI.OneDocument.Documents; const string output = "swatches.docx"; using (var doc = Document.Create()) { var paragraph = doc.Paragraphs.Single(); paragraph.AddRun("Palette: "); paragraph.AddPicture(File.ReadAllBytes("swatches.png"), widthPoints: 72, altText: "Blue and yellow swatches"); doc.SaveAs(output); } using var package = ZipFile.OpenRead(output); var image = package.Entries.Single(e => e.FullName.StartsWith("word/media/")); using var main = package.GetEntry("word/document.xml")!.Open(); var xml = XDocument.Load(main); XNamespace wp = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"; var inline = xml.Descendants(wp + "inline").Single(); var size = inline.Element(wp + "extent")!; Console.WriteLine($"Wrote {output}"); Console.WriteLine($"Embedded PNG: {image.Length} bytes"); Console.WriteLine($"Alt text: {(string?)inline.Element(wp + "docPr")?.Attribute("descr")}"); Console.WriteLine($"Inline size: {(long)size.Attribute("cx")! / 12700} × {(long)size.Attribute("cy")! / 12700} pt");
dotnet run prints:
Wrote swatches.docx Embedded PNG: 85 bytes Alt text: Blue and yellow swatches Inline size: 72 × 36 pt
AddPicture accepts PNG, JPEG, GIF, or BMP bytes. It throws ArgumentException when it can’t recognize a supported picture header or when the supplied size isn’t positive and finite.
Variations
Append a picture to an existing DOCX
Use the swatches.docx made by the full program as the input. This adds another copy of the PNG at the end and saves a separate document. Setting just the height keeps the picture’s proportions.
using RecursiveAI.OneDocument.Documents; using var doc = Document.Open("swatches.docx"); var png = File.ReadAllBytes("swatches.png"); doc.Body.AddPicture(png, heightPoints: 24, altText: "Blue and yellow swatches"); doc.SaveAs("with-picture.docx"); Console.WriteLine("Wrote with-picture.docx");
Wrote with-picture.docxRelated recipes
The short answer
Read the picture bytes, call AddPicture, and save the document as DOCX. Call it on the body to add a picture in its own paragraph at the end, or on a paragraph to append the picture after that paragraph’s existing content. In OneDocument 1.0.0, AddPicture cannot insert a floating picture or wrap text around it; see Floating objects and text wrap for how OneDocument renders pictures that are already anchored in a document.
How do I insert a PNG image into Word?
Pass the bytes you read from the PNG directly to AddPicture. OneDocument checks the image header, not its filename extension. The authoring API writes the image bytes into a media part of the DOCX and inserts a reference to it in the paragraph. The document therefore doesn’t need the original PNG file beside it when you open it. AddPicture doesn’t decode the pixels, so an accepted header doesn’t guarantee the full image is intact.
When editing an existing Word document, open it with Document.Open rather than Document.Create. Call AddPicture on the paragraph where you want the image to appear after the text. Call it on the body instead if you want the picture at the end, like the variation above. Save to a different filename if you want to keep the original document unchanged.
How do I resize a picture in Word without stretching it?
Supply either widthPoints or heightPoints, not both. OneDocument computes the other side from the image’s pixel dimensions. A point is 1/72 inch, so widthPoints: 72 displays the sample image at one inch wide and half an inch high. The file keeps the original pixels; the size you specify is for the layout. Supplying both dimensions sets both sides independently. If you supply neither, OneDocument uses the pixel dimensions at 96 dpi and scales the picture down to fit a maximum width of six inches.
How do I add alt text to an image in Word?
Pass altText to AddPicture when you insert the image. Describe what a reader needs from it rather than repeating the filename. For the sample, “Blue and yellow swatches” conveys the content without seeing the pixels. In the saved DOCX, the description is stored on the inline picture’s drawing properties (wp:docPr, descr), separate from any visible text in the paragraph.