1 | [![Build Status](https://travis-ci.org/cloudinary/cloudinary_npm.svg?branch=master)](https://travis-ci.org/cloudinary/cloudinary_npm)
|
2 |
|
3 | Cloudinary
|
4 | ==========
|
5 |
|
6 | Cloudinary is a cloud service that offers a solution to a web application's entire image management pipeline.
|
7 |
|
8 | Easily upload images to the cloud. Automatically perform smart image resizing, cropping and conversion without installing any complex software. Integrate Facebook or Twitter profile image extraction in a snap, in any dimension and style to match your website’s graphics requirements. Images are seamlessly delivered through a fast CDN, and much much more.
|
9 |
|
10 | Cloudinary offers comprehensive APIs and administration capabilities and is easy to integrate with any web application, existing or new.
|
11 |
|
12 | Cloudinary provides URL and HTTP based APIs that can be easily integrated with any Web development framework.
|
13 |
|
14 | For Node.js, Cloudinary provides an extension for simplifying the integration even further.
|
15 |
|
16 | ## Getting started guide
|
17 | ![](https://res.cloudinary.com/cloudinary/image/upload/see_more_bullet.png) **Take a look at our [Getting started guide for Node.js](https://cloudinary.com/documentation/node_integration#node_js_getting_started_guide)**.
|
18 |
|
19 |
|
20 | ## Setup ######################################################################
|
21 |
|
22 | ``` npm install cloudinary ```
|
23 |
|
24 | ## Try it right away
|
25 |
|
26 | Sign up for a [free account](https://cloudinary.com/users/register/free) so you can try out image transformations and seamless image delivery through CDN.
|
27 |
|
28 | *Note: Replace `demo` in all the following examples with your Cloudinary's `cloud name`.*
|
29 |
|
30 | Accessing an uploaded image with the `sample` public ID through a CDN:
|
31 |
|
32 | http://res.cloudinary.com/demo/image/upload/sample.jpg
|
33 |
|
34 | ![Sample](https://res.cloudinary.com/demo/image/upload/w_0.4/sample.jpg "Sample")
|
35 |
|
36 | Generating a 150x100 version of the `sample` image and downloading it through a CDN:
|
37 |
|
38 | http://res.cloudinary.com/demo/image/upload/w_150,h_100,c_fill/sample.jpg
|
39 |
|
40 | ![Sample 150x100](https://res.cloudinary.com/demo/image/upload/w_150,h_100,c_fill/sample.jpg "Sample 150x100")
|
41 |
|
42 | Converting to a 150x100 PNG with rounded corners of 20 pixels:
|
43 |
|
44 | http://res.cloudinary.com/demo/image/upload/w_150,h_100,c_fill,r_20/sample.png
|
45 |
|
46 | ![Sample 150x150 Rounded PNG](https://res.cloudinary.com/demo/image/upload/w_150,h_100,c_fill,r_20/sample.png "Sample 150x150 Rounded PNG")
|
47 |
|
48 | For plenty more transformation options, see our [image transformations documentation](http://cloudinary.com/documentation/image_transformations).
|
49 |
|
50 | Generating a 120x90 thumbnail based on automatic face detection of the Facebook profile picture of Bill Clinton:
|
51 |
|
52 | http://res.cloudinary.com/demo/image/facebook/c_thumb,g_face,h_90,w_120/billclinton.jpg
|
53 |
|
54 | ![Facebook 90x120](https://res.cloudinary.com/demo/image/facebook/c_thumb,g_face,h_90,w_120/billclinton.jpg "Facebook 90x200")
|
55 |
|
56 | For more details, see our documentation for embedding [Facebook](https://cloudinary.com/documentation/facebook_profile_pictures) and [Twitter](https://cloudinary.com/documentation/twitter_profile_pictures) profile pictures.
|
57 |
|
58 |
|
59 | ## Usage
|
60 |
|
61 | ### Configuration
|
62 |
|
63 | Each request for building a URL of a remote cloud resource must have the `cloud_name` parameter set.
|
64 | Each request to our secure APIs (e.g., image uploads, eager sprite generation) must have the `api_key` and `api_secret` parameters set. See [API, URLs and access identifiers](https://cloudinary.com/documentation/solution_overview#account_and_api_setup) for more details.
|
65 |
|
66 | Setting the `cloud_name`, `api_key` and `api_secret` parameters can be done either directly in each call to a Cloudinary method, by calling the cloudinary.config(), or by using the CLOUDINARY_URL environment variable.
|
67 |
|
68 | ### Require the Cloudinary library
|
69 |
|
70 | ```js
|
71 | var cloudinary = require('cloudinary').v2
|
72 | ```
|
73 |
|
74 | ### Overriding the request agent
|
75 | To override the request agent pass the agent into any method that makes a
|
76 | request and it will be used instead of the normal https agent. e.g
|
77 |
|
78 | ```js
|
79 | cloudinary.uploader.upload_stream(
|
80 | { agent: myAgent },
|
81 | function(error, result) { console.log(result); }
|
82 | );
|
83 |
|
84 | ```
|
85 |
|
86 | ### Embedding and transforming images
|
87 |
|
88 | Any image uploaded to Cloudinary can be transformed and embedded using powerful view helper methods:
|
89 |
|
90 | The following example generates the url for accessing an uploaded `sample` image while transforming it to fill a 100x150 rectangle:
|
91 |
|
92 | ```js
|
93 | cloudinary.url("sample.jpg", {width: 100, height: 150, crop: "fill"})
|
94 | ```
|
95 |
|
96 | Another example, emedding a smaller version of an uploaded image while generating a 90x90 face detection based thumbnail:
|
97 |
|
98 | ```js
|
99 | cloudinary.url("woman.jpg", {width: 90, height: 90, crop: "thumb", gravity: "face"});
|
100 | ```
|
101 |
|
102 | You can provide either a Facebook name or a numeric ID of a Facebook profile or a fan page.
|
103 |
|
104 | Embedding a Facebook profile to match your graphic design is very simple:
|
105 |
|
106 | ```js
|
107 | cloudinary.url("billclinton.jpg", {width: 90, height: 130, type: "facebook", crop: "fill", gravity: "north_west"});
|
108 | ```
|
109 |
|
110 | Same goes for Twitter:
|
111 |
|
112 | ```js
|
113 | cloudinary.url("billclinton.jpg", {type: "twitter_name"});
|
114 | ```
|
115 |
|
116 | ![](https://res.cloudinary.com/cloudinary/image/upload/see_more_bullet.png) **See [our documentation](https://cloudinary.com/documentation/node_image_manipulation) for more information about displaying and transforming images in Node.js**.
|
117 |
|
118 | ### Upload
|
119 |
|
120 | Assuming you have your Cloudinary configuration parameters defined (`cloud_name`, `api_key`, `api_secret`), uploading to Cloudinary is very simple.
|
121 |
|
122 | The following example uploads a local JPG to the cloud:
|
123 |
|
124 | ```js
|
125 | var cloudinary = require('cloudinary').v2;
|
126 | cloudinary.uploader.upload("my_picture.jpg", function(error, result) { console.log(result) });
|
127 | ```
|
128 |
|
129 | Below is an example of an upload's result:
|
130 |
|
131 | ```json
|
132 | {
|
133 | "public_id": "4srvcynxrf5j87niqcx6w",
|
134 | "version": 1340625837,
|
135 | "signature": "01234567890abcdef01234567890abcdef012345",
|
136 | "width": 200,
|
137 | "height": 200,
|
138 | "format": "jpg",
|
139 | "resource_type": "image",
|
140 | "url": "http://res.cloudinary.com/demo/image/upload/v1340625837/4srvcynxrf5j87niqcx6w.jpg",
|
141 | "secure_url": "https://res.cloudinary.com/demo/image/upload/v1340625837/4srvcynxrf5j87niqcx6w.jpg"
|
142 | }
|
143 | ```
|
144 |
|
145 | The uploaded image is assigned a randomly generated public ID. The image is immediately available for download through a CDN:
|
146 |
|
147 | ```js
|
148 | cloudinary.url("abcfrmo8zul1mafopawefg.jpg");
|
149 |
|
150 | // http://res.cloudinary.com/demo/image/upload/abcfrmo8zul1mafopawefg.jpg
|
151 | ```
|
152 | You can also specify your own public ID:
|
153 |
|
154 | ```js
|
155 | cloudinary.uploader.upload(
|
156 | "http://www.example.com/image.jpg",
|
157 | {public_id: 'sample_remote'},
|
158 | function(error, result) {
|
159 | console.log(result)
|
160 | }
|
161 | );
|
162 |
|
163 | cloudinary.url("sample_remote.jpg")
|
164 |
|
165 | // http://res.cloudinary.com/demo/image/upload/sample_remote.jpg
|
166 |
|
167 | ```
|
168 |
|
169 | ![](https://res.cloudinary.com/cloudinary/image/upload/see_more_bullet.png) **See [our documentation](https://cloudinary.com/documentation/node_image_upload) for plenty more options of uploading to the cloud from your Node.js code or directly from the browser**.
|
170 |
|
171 | ### cloudinary.upload_stream
|
172 |
|
173 | You can use cloudinary.upload_stream to write to the uploader as a stream:
|
174 |
|
175 | ```js
|
176 | var fs = require('fs');
|
177 | var stream = cloudinary.uploader.upload_stream(function(error, result) { console.log(result); });
|
178 | var file_reader = fs.createReadStream('my_picture.jpg', {encoding: 'binary'}).on('data', stream.write).on('end', stream.end);
|
179 | ```
|
180 |
|
181 | #### Version 1.1 upload_stream change notes
|
182 | The `upload_stream` method was modified to return a `Transform` stream object, we advise to change the `on('data')` and `on('end')` to pipe API:
|
183 |
|
184 | ```js
|
185 | var file_reader = fs.createReadStream('my_picture.jpg').pipe(stream);
|
186 |
|
187 | ```
|
188 | if you still need to use event chanining, you can wrap `stream.write` and `stream.end` with wrapper functions
|
189 |
|
190 | ```js
|
191 | var file_reader = fs.createReadStream('my_picture.jpg', {encoding: 'binary'})
|
192 | .on('data', function(data){stream.write(data)})
|
193 | .on('end', function(){stream.end()});
|
194 | ```
|
195 | ### cloudinary.image
|
196 |
|
197 | Returns an html image tag pointing to Cloudinary.
|
198 |
|
199 | Usage:
|
200 |
|
201 | ```js
|
202 | cloudinary.image("sample", {format: "png", width: 100, height: 100, crop: "fill"})
|
203 |
|
204 | // <img src='http://res.cloudinary.com/demo/image/upload/c_fill,h_100,w_100/sample.png' height='100' width='100'/>
|
205 | ```
|
206 |
|
207 | ### Typescript
|
208 |
|
209 | 🎉New 🎉TypeScript support was just added. Check out the [declaration file](https://github.com/cloudinary/cloudinary_npm/blob/master/types/index.d.ts).
|
210 |
|
211 | ### Samples
|
212 |
|
213 | You can find our simple and ready-to-use samples projects, along with documentation in the [samples folder](https://github.com/cloudinary/cloudinary_npm/tree/master/samples).
|
214 | Please consult with the [README file](https://github.com/cloudinary/cloudinary_npm/blob/master/samples/readme.md), for usage and explanations.
|
215 |
|
216 |
|
217 | ## Additional resources ##########################################################
|
218 |
|
219 | Additional resources are available at:
|
220 |
|
221 | * [Website](https://cloudinary.com)
|
222 | * [Interactive demo](https://demo.cloudinary.com/default)
|
223 | * [Documentation](https://cloudinary.com/documentation)
|
224 | * [Knowledge Base](https://support.cloudinary.com/hc/en-us)
|
225 | * [Documentation for Node.js integration](https://cloudinary.com/documentation/node_integration)
|
226 | * [Node.js image upload documentation](https://cloudinary.com/documentation/node_image_upload)
|
227 | * [Node.js image manipulation documentation](https://cloudinary.com/documentation/node_image_manipulation)
|
228 | * [Image transformations documentation](https://cloudinary.com/documentation/image_transformations)
|
229 |
|
230 | ## Run test
|
231 |
|
232 | ```
|
233 | npm run test
|
234 | ```
|
235 |
|
236 | ## Node support
|
237 | This SDK requires node >= 8.
|
238 |
|
239 | ## Support
|
240 |
|
241 | You can [open an issue through GitHub](https://github.com/cloudinary/cloudinary_npm/issues).
|
242 |
|
243 | Contact us [https://cloudinary.com/contact](https://cloudinary.com/contact)
|
244 |
|
245 | Stay tuned for updates, tips and tutorials: [Blog](https://cloudinary.com/blog), [Twitter](https://twitter.com/cloudinary), [Facebook](https://www.facebook.com/Cloudinary).
|
246 |
|
247 | ## Join the Community ##########################################################
|
248 |
|
249 | Impact the product, hear updates, test drive new features and more! Join [here](https://www.facebook.com/groups/CloudinaryCommunity).
|
250 |
|
251 |
|
252 | ## License #######################################################################
|
253 |
|
254 | Released under the MIT license.
|
255 |
|
256 | Test resources include the video [Cloud Book Study](https://vimeo.com/27172301)
|
257 | which was created by [Heidi Neilson](https://vimeo.com/heidineilson)
|
258 | and is distributed under the Creative commons - attribution license (CC BY 3.0)
|