Images List
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
{
"detail": "Method \"GET\" not allowed.",
"errors": [
{
"code": "UNKNOWN",
"message": "Method \"GET\" not allowed.",
"path": null,
"field": null
}
]
}