Capture photos and images

Capture photos and images with the OneNote API

Learn how to include images in captured OneNote notebook pages with the Microsoft OneNote API.

Last modified: January 22, 2016

Applies to: OneNote service

In this article
Capture photos and images in an Android app
Capture photos and images in an iOS app
Capture photos and images in a Windows Phone app
Capture photos and images in a Windows Store app
Capture photos and images using REST

Note Note

See this content on our new documentation site for consumer and enterprise OneNote APIs.

Many apps that capture information to OneNote will include images of some form. The OneNote API enables your app to create pages that include logos, images, and even photos from a device camera.

The API provides several ways to capture images on to the user's OneNote pages:

  1. By URL Reference. The HTML <img src="http://..."> tag inserts an image that's available on the Internet. You'll usually use this technique when you're capturing a normal web page. There are code samples showing this method in the Create structure using HTML with the OneNote API topic.

  2. Including image data in the POST. Using <img src="name:MultiPartBlockName" ...>, include the binary image data inside the multi-part request, in a part having the name from the img tag. The code samples in this topic use this method.

  3. Making an image/web page snapshot. Using <img data-render-src="..."> renders an image that the API inserts into the page. For more information and code samples, see Capture web page snapshots with the OneNote API.

Image types supported by the API include TIFF, PNG, GIF, JPEG, and BMP. If you need to capture an image file format that's not one of those common image file formats, and don't want to convert it, consider uploading it as a binary file, using the information and code examples at Capture embedded files with the OneNote API.

Note Note

Detecting the image type. The OneNote API automatically detects the original input image type, and returns it as the data-fullres-src-type in the output HTML. The API also returns the image type of the optimized image in data-src-type.

The <img> tag can optionally include height and width attributes.

When you include the image data in the POST, as shown in the code samples contained here, you don't need to use Base64 or otherwise encode the data. Just use the binary data.

Remember the following limits when using images in a OneNote API capture:

  • Maximum number of images is 30. If you add more images in the POST, they'll be ignored. The same limit applies to regular <img src="..."> tags. If you need to capture a web page with lots of images, consider using the page snapshot features described in Capture web page snapshots with the OneNote API.

  • 25 MB size limit for each image, including the multi-part header lines.

  • Total POST size limit is ~70 MB, including image and other data. The actual limit is impacted by downstream encoding, so there's not really a fixed byte-count limit. Captures with data more than that limit may make your app and captures unreliable, so be careful.

  • Images captured cannot be links. That is, the <img> tag is not supported inside an <a href…> tag in your HTML.

Important note Important

Before POST requests like the ones shown here can succeed, you need to Get a client ID for use with the OneNote API (or package ID for a Windows Store application), and your app has to Authenticate the user for the OneNote API. If you don't supply a valid OAuth token with your request, it will fail.

Tip Tip

These code samples should not be considered production-ready code. Things like detailed user-input validation have been left out to make it easier to understand the code flow. Carefully review your code for potential code-quality and security issues before you publish your app.

The following code builds a multi-part request that contains a "Presentation" part with HTML, and a second part with binary image data. In this example, a logo image is compiled into the app, but the technique is the same for other images, such as from the device's camera.

In this code, the binary image data is passed to this member as the imageBinaryAsString parameter. The createPageWithImage function is adapted from the SendPageCreateAsyncTask class in the Android sample on Github. For more information, see Get the OneNote API sample applications.

public ApiResponse createPageWithImage(String imageBinaryAsString) 
{
  try {
    this.connectForMultipart(PAGES_ENDPOINT);
    String date = getDate();
    String imagePartName = "image1";
    String onml = "<html>" +
      "<head>" +
      "<title>A page with an image on it (Android Sample)</title>" +
      "<meta name=\"created\" content=\"" + date + "\" />" +
      "</head>" +
      "<body>" +
      "<h1>This is a page with an image on it</h1>" +
      "<img src=\"name:" + imagePartName + "\" width=\"426\" height=\"68\" />" +
      "</body>" +
      "</html>";
    this.addFormPart("Presentation", "application/xhtml+xml", onml);
    this.addFormPart(imagePartName, "image/jpeg", imageBinaryAsString);
    this.finishMultipart();
    ApiResponse response = this.getResponse();
      return response;
  } catch (Exception ex) {
    String test = ex.getMessage();
  }
  return null;
}

The following code builds a multi-part request that contains a "Presentation" part with HTML, and a second part with binary image data. In this example, a logo image is compiled into the app, but the technique is the same for other images, such as from the device's camera.

This code is adapted from the ONSCPSCreateExamples class in the iOS code sample on GitHub. For more information, see Get the OneNote API sample applications.


- (void)createPageWithImage {
    NSString *date = [ONSCPSCreateExamples getDate];
    UIImage *logo = [UIImage imageNamed:@"Logo"];
    NSString *simpleHtml = [NSString stringWithFormat:
        @"<html>"
        "<head>"
        "<title>A simple page with an image from iOS</title>"
        "<meta name=\"created\" content=\"%@\" />"
        "</head>"
        "<body>"
        "<h1>This is a page with an image on it</h1>"
        "<img src=\"name:image1\" width=\"%.0f\" height=\"%.0f\" />"
        "</body>"
        "</html>", date, [logo size].width, [logo size].height];
    NSData *presentation = [simpleHtml dataUsingEncoding:NSUTF8StringEncoding];
    NSData *image1 = UIImageJPEGRepresentation(logo, 1.0);
    
    NSMutableURLRequest *request = [[AFHTTPRequestSerializer serializer] 
      multipartFormRequestWithMethod:@"POST" URLString:PagesEndPoint parameters:nil 
      constructingBodyWithBlock: ^(id <AFMultipartFormData>formData) {
        [formData
          appendPartWithHeaders:@{
            @"Content-Disposition" : @"form-data; name=\"Presentation\"",
            @"Content-Type" : @"text/html"}
          body:presentation];
        [formData
          appendPartWithHeaders:@{
            @"Content-Disposition" : @"form-data; name=\"image1\"",
            @"Content-Type" : @"image/jpeg"}
           body:image1];
    }];
    if (liveClient.session)
    {
        [request setValue:[@"Bearer " 
          stringByAppendingString:liveClient.session.accessToken] 
          forHTTPHeaderField:@"Authorization"];
    }
    currentConnection = [[NSURLConnection alloc] 
      initWithRequest:request delegate:self startImmediately:YES];
}

The following code builds a multi-part request that contains a "Presentation" part with HTML, and a second part with binary image data. In this example, a logo image is compiled into the app, but the technique is the same for other images, such as from the device's camera.

This code is adapted from the Windows Phone code sample on GitHub. For more information, see Get the OneNote API sample applications.

        
private async void btn_CreateWithImage_Click(object sender, RoutedEventArgs e)
{
  StartRequest();
  var client = new HttpClient();

  // Note: API only supports JSON return type.
  client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));
  // This allows you to see what happens when an unauthenticated call is made.
  if (m_AccessToken != null)
    {
      client.DefaultRequestHeaders.Authorization = 
        new AuthenticationHeaderValue("Bearer", m_AccessToken);
    }

  const string imagePartName = "image1";
  string date = GetDate();
  string simpleHtml = "<html>" +
    "<head>" +
    "<title>A page with an image on it (WinPhone8 Sample)</title>" +
    "<meta name=\"created\" content=\"" + date + "\" />" +
    "</head>" +
    "<body>" +
    "<h1>This is a page with an image on it</h1>" +
    "<img src=\"name:" + imagePartName + 
    "\" alt=\"A beautiful logo\" width=\"426\" height=\"68\" />" +
    "</body>" +
    "</html>";

  // Create the image part - be sure it is disposed after we've sent 
  // the message in order to close the stream.
    HttpRequestMessage createMessage = null;
    HttpResponseMessage response = null;
    Stream imageStream = await GetImageStream("assets\\Logo.jpg");
    using (var imageContent = new StreamContent(imageStream))
      {
        imageContent.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
        createMessage = new HttpRequestMessage(HttpMethod.Post, PAGESENDPOINT)
      {
    Content = new MultipartFormDataContent
      {
        { 
          new StringContent(simpleHtml, System.Text.Encoding.UTF8, 
            "text/html"), "Presentation"},
            {imageContent, imagePartName}
        }
      };
    // Must send the request within the using block, or the 
    // image stream will have been disposed.
    response = await client.SendAsync(createMessage);
  }
  await EndRequest(response);
}

The following code builds a multi-part request that contains a "Presentation" part with HTML, and a second part with binary image data. In this example, a logo image is compiled into the app, but the technique is the same for other images, such as from the device's camera.

This code is adapted from the Windows Store code sample on GitHub. For more information, see Get the OneNote API sample applications.


async public Task<StandardResponse> CreatePageWithImage(bool debug)
{
  var client = new HttpClient();
  // Note: API only supports JSON return type.
  client.DefaultRequestHeaders.Accept.Add( 
    new MediaTypeWithQualityHeaderValue("application/json"));
  // This allows you to see what happens when an unauthenticated call is made.
  if (this.IsAuthenticated)
  {
    client.DefaultRequestHeaders.Authorization = 
      new AuthenticationHeaderValue("Bearer", 
      this._authClient.Session.AccessToken);
  }
  const string imagePartName = "image1";
  string date = GetDate();
  string simpleHtml = "<html>" +
    "<head>" +
    "<title>A simple page created with an image on it</title>" +
    "<meta name=\"created\" content=\"" + date + "\" />" +
    "</head>" +
    "<body>" +
    "<h1>This is a page with an image on it</h1>" +
    "<img src=\"name:" + imagePartName + 
    "\" alt=\"A beautiful logo\" width=\"426\" height=\"68\" />" +
    "</body>" +
    "</html>";
  // Create the image part - be sure it is disposed after 
  // we've sent the message in order to close the stream.
  HttpRequestMessage createMessage = null;
  HttpResponseMessage response = null;
  using (var imageContent = new StreamContent( 
    await GetImageStream("assets\\Logo.jpg")))
    {
      imageContent.Headers.ContentType = 
        new MediaTypeHeaderValue("image/jpeg");
      createMessage = new HttpRequestMessage(HttpMethod.Post, PagesEndPoint)
        {
          Content = new MultipartFormDataContent
            {
              { 
                new StringContent(simpleHtml, 
                System.Text.Encoding.UTF8, "text/html"), "Presentation"
              },
              {imageContent, imagePartName}
            }
        };
      // Must send the request within the using block, or the 
      // image stream will have been disposed.
      response = await client.SendAsync(createMessage);
    }
  return await TranslateResponse(response);
}

If your app is running in a mobile device, scanner or camera, and you want to capture images in OneNote, you will want to upload the image data directly to the API from the device. You do this by embedding the image data in parts of your multi-part requests.

In the HTML of your request's "Presentation" block, include an img tag. In the img tag's src attribute, use the special syntax "name:RequestBlockPartId", where RequestBlockPartId is an alphanumeric identifier of a block in your request. This next example shows how to do that, using the string as the identifier.


Content-Type:multipart/form-data; boundary=MyAppPartBoundary
Authorization:bearer tokenString

--MyAppPartBoundary
Content-Disposition:form-data; name="Presentation"
Content-type:text/html

<!DOCTYPE html>
<html>
  <head>
    <title>A simple page with an embedded image</title>
  </head>
  <body>
    <p>This is a very simple Presentation block.</p>
    <p>This next image specifies the image data in this POST request.</p>
    <img src="name:MyAppPictureId" alt="a cool image" width="500"/>
  </body>
</html>

--MyAppPartBoundary
Content-Disposition:form-data; name="MyAppPictureId"
Content-type:image/jpeg

... image binary data ...

--MyAppPartBoundary--


If you need to embed multiple images this way, each image Id has to be unique within the POST request.

The image data is binary data; don't use Base64 or otherwise encode it.

Show:
© 2016 Microsoft