Jump to API response

The images endpoint turn a plot (which may be given in multiple forms) into an image of the desired format.


Reference



Authorization


You must be authenticated to use this endpoint. See authorization for details.


Request body fields


This is a list of all valid fields. See actions for details on specific requirements.

figure: A nested JSON object (or JSON string) describing a Ploty plot.

width: Override the width attribute in the given or saved plot object.

height: Override the height attribute in the given or saved plot object.

format [default='png']: The desired image format 'png', 'jpeg', 'svg', 'pdf', 'eps', or 'webp'

scale [default=1]: Both png and jpeg formats will be scaled beyond the specified width and height by this number.

encoded [default=false]: A boolean flag for base64 encoding of bytes


Actions


To generate an image, you must make a successful POST request to this endpoint. To do so, specify a plot as a JSON argument.


generate from json

This option always requires authorization.

The only required field is 'figure'.See request body fields for a full list of fields with definitions.

Note that the figure must include either data or layout fields where data is an array and layout is an object.

Examples:

// POST https://api.plotly.com/v2/images/ --> 400 Bad Request

// POST https://api.plotly.com/v2/images/ --> 400 Bad Request
{
    "figure": {"data": []}
}

// POST https://api.plotly.com/v2/images/ --> 200 OK
{
    "figure": {"data": [], "layout": {}}
}

// POST https://api.plotly.com/v2/images/ --> 200 OK
{
    "figure": "{\"data\": [], \"layout\": {}}"
}

// POST https://api.plotly.com/v2/images/ --> 200 OK
{
    "figure": {
        "data": [{"y": [10, 10, 2, 20]}],
        "layout": {"width": 700}
    },
    "width": 1000,
    "height": 500,
    "format": "png",
    "scale": 4,
    "encoded": true
}

// POST https://api.plotly.com/v2/images/ --> 200 OK
{
    "figure": {
        "data": [
            {
                "xsrc": "gridlover:10:a7f3k",
                "y": [10, 10, 2, 20]
            }
        ],
        "layout": {}
    }
}

Note, the 'width' given in the top-level JSON body will override the 'width' specified in the figure layout. This also works for the 'height' attribute.

Also note, while Plotly graph objects may exist with data references--strings referencing columns in Plotly grids--references sent via this endpoint will not be expanded, just ignored. In the example above, the request is OK, but '*src' keys will not affect the resulting image.


Responses


Successful requests (200 OK) will have the raw image in the body of the response with an appropriate content-type header. If 'encoded' is true, the image will be returned base64 encoded.

Unsuccessful requests (4xx or 5xx) will return a JSON response. Human-readable debug information will be given in a 'detail' field as discussed in the responses section of the root api page.

GET /v2/images?format=api
HTTP 405 Method Not Allowed
Allow: POST, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "detail": "Method \"GET\" not allowed.",
    "errors": [
        {
            "code": "UNKNOWN",
            "message": "Method \"GET\" not allowed.",
            "path": null,
            "field": null
        }
    ]
}