1 | Cloudinary
|
2 | ==========
|
3 |
|
4 | Cloudinary is a cloud service that offers a solution to a web application's entire image management pipeline.
|
5 |
|
6 | 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.
|
7 |
|
8 | Cloudinary offers comprehensive APIs and administration capabilities and is easy to integrate with any web application, existing or new.
|
9 |
|
10 | Cloudinary provides URL and HTTP based APIs that can be easily integrated with any Web development framework.
|
11 |
|
12 | For Node.js, Cloudinary provides an extension for simplifying the integration even further.
|
13 |
|
14 | ## Getting started guide
|
15 | ![](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)**.
|
16 |
|
17 |
|
18 | ## Setup ######################################################################
|
19 |
|
20 | npm install cloudinary
|
21 |
|
22 | ## Try it right away
|
23 |
|
24 | 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.
|
25 |
|
26 | *Note: Replace `demo` in all the following examples with your Cloudinary's `cloud name`.*
|
27 |
|
28 | Accessing an uploaded image with the `sample` public ID through a CDN:
|
29 |
|
30 | http://res.cloudinary.com/demo/image/upload/sample.jpg
|
31 |
|
32 | ![Sample](https://res.cloudinary.com/demo/image/upload/w_0.4/sample.jpg "Sample")
|
33 |
|
34 | Generating a 150x100 version of the `sample` image and downloading it through a CDN:
|
35 |
|
36 | http://res.cloudinary.com/demo/image/upload/w_150,h_100,c_fill/sample.jpg
|
37 |
|
38 | ![Sample 150x100](https://res.cloudinary.com/demo/image/upload/w_150,h_100,c_fill/sample.jpg "Sample 150x100")
|
39 |
|
40 | Converting to a 150x100 PNG with rounded corners of 20 pixels:
|
41 |
|
42 | http://res.cloudinary.com/demo/image/upload/w_150,h_100,c_fill,r_20/sample.png
|
43 |
|
44 | ![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")
|
45 |
|
46 | For plenty more transformation options, see our [image transformations documentation](http://cloudinary.com/documentation/image_transformations).
|
47 |
|
48 | Generating a 120x90 thumbnail based on automatic face detection of the Facebook profile picture of Bill Clinton:
|
49 |
|
50 | http://res.cloudinary.com/demo/image/facebook/c_thumb,g_face,h_90,w_120/billclinton.jpg
|
51 |
|
52 | ![Facebook 90x120](https://res.cloudinary.com/demo/image/facebook/c_thumb,g_face,h_90,w_120/billclinton.jpg "Facebook 90x200")
|
53 |
|
54 | 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.
|
55 |
|
56 |
|
57 | ## Usage
|
58 |
|
59 | ### Configuration
|
60 |
|
61 | Each request for building a URL of a remote cloud resource must have the `cloud_name` parameter set.
|
62 | 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.
|
63 |
|
64 | 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.
|
65 |
|
66 | ### Overriding the request agent
|
67 | To override the request agent pass the agent into any method that makes a
|
68 | request and it will be used instead of the normal https agent. e.g
|
69 | ```js
|
70 |
|
71 | cloudinary.uploader.upload_stream(
|
72 | function(result) { console.log(result); },
|
73 | { agent: myAgent }
|
74 | );
|
75 |
|
76 | ```
|
77 |
|
78 | ### Embedding and transforming images
|
79 |
|
80 | Any image uploaded to Cloudinary can be transformed and embedded using powerful view helper methods:
|
81 |
|
82 | The following example generates the url for accessing an uploaded `sample` image while transforming it to fill a 100x150 rectangle:
|
83 |
|
84 | cloudinary.url("sample.jpg", {width: 100, height: 150, crop: "fill"})
|
85 |
|
86 | Another example, emedding a smaller version of an uploaded image while generating a 90x90 face detection based thumbnail:
|
87 |
|
88 | cloudinary.url("woman.jpg", {width: 90, height: 90, crop: "thumb", gravity: "face"})
|
89 |
|
90 | You can provide either a Facebook name or a numeric ID of a Facebook profile or a fan page.
|
91 |
|
92 | Embedding a Facebook profile to match your graphic design is very simple:
|
93 |
|
94 | cloudinary.url("billclinton.jpg", {width: 90, height: 130, type: "facebook", crop: "fill", gravity: "north_west"})
|
95 |
|
96 | Same goes for Twitter:
|
97 |
|
98 | cloudinary.url("billclinton.jpg", {type: "twitter_name"})
|
99 |
|
100 | ![](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**.
|
101 |
|
102 | ### Upload
|
103 |
|
104 | Assuming you have your Cloudinary configuration parameters defined (`cloud_name`, `api_key`, `api_secret`), uploading to Cloudinary is very simple.
|
105 |
|
106 | The following example uploads a local JPG to the cloud:
|
107 |
|
108 | var cloudinary = require('cloudinary')
|
109 |
|
110 | cloudinary.uploader.upload("my_picture.jpg", function(result) { console.log(result) })
|
111 |
|
112 | Below is an example of an upload's result:
|
113 |
|
114 | { public_id: '4srvcynxrf5j87niqcx6w',
|
115 | version: 1340625837,
|
116 | signature: '01234567890abcdef01234567890abcdef012345',
|
117 | width: 200,
|
118 | height: 200,
|
119 | format: 'jpg',
|
120 | resource_type: 'image',
|
121 | url: 'http://res.cloudinary.com/demo/image/upload/v1340625837/4srvcynxrf5j87niqcx6w.jpg',
|
122 | secure_url: 'https://res.cloudinary.com/demo/image/upload/v1340625837/4srvcynxrf5j87niqcx6w.jpg' }
|
123 |
|
124 | The uploaded image is assigned a randomly generated public ID. The image is immediately available for download through a CDN:
|
125 |
|
126 | cloudinary.url("abcfrmo8zul1mafopawefg.jpg")
|
127 |
|
128 | http://res.cloudinary.com/demo/image/upload/abcfrmo8zul1mafopawefg.jpg
|
129 |
|
130 | You can also specify your own public ID:
|
131 |
|
132 | cloudinary.uploader.upload("http://www.example.com/image.jpg", function(result) { console.log(result) }, {public_id: 'sample_remote'})
|
133 |
|
134 | cloudinary.url("sample_remote.jpg")
|
135 |
|
136 | http://res.cloudinary.com/demo/image/upload/sample_remote.jpg
|
137 |
|
138 | ![](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**.
|
139 |
|
140 | ### cloudinary.upload_stream
|
141 |
|
142 | You can use cloudinary.upload_stream to write to the uploader as a stream:
|
143 |
|
144 | var fs = require('fs');
|
145 | var stream = cloudinary.uploader.upload_stream(function(result) { console.log(result); });
|
146 | var file_reader = fs.createReadStream('my_picture.jpg', {encoding: 'binary'}).on('data', stream.write).on('end', stream.end);
|
147 |
|
148 | #### Version 1.1 upload_stream change notes
|
149 | 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:
|
150 |
|
151 | var file_reader = fs.createReadStream('my_picture.jpg').pipe(stream);
|
152 |
|
153 | if you still need to use event chanining, you can wrap `stream.write` and `stream.end` with wrapper functions
|
154 |
|
155 | var file_reader = fs.createReadStream('my_picture.jpg', {encoding: 'binary'}).
|
156 | on('data', function(data){stream.write(data)}).on('end', function(){stream.end()});
|
157 |
|
158 | ### cloudinary.image
|
159 |
|
160 | Returns an html image tag pointing to Cloudinary.
|
161 |
|
162 | Usage:
|
163 |
|
164 | cloudinary.image("sample", {format: "png", width: 100, height: 100, crop: "fill"})
|
165 |
|
166 | // <img src='http://res.cloudinary.com/demo/image/upload/c_fill,h_100,w_100/sample.png' height='100' width='100'/>
|
167 |
|
168 | ### Samples
|
169 |
|
170 | 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).
|
171 | Please consult with the [README file](https://github.com/cloudinary/cloudinary_npm/blob/master/samples/README.md), for usage and explanations.
|
172 |
|
173 |
|
174 | ## Additional resources ##########################################################
|
175 |
|
176 | Additional resources are available at:
|
177 |
|
178 | * [Website](https://cloudinary.com)
|
179 | * [Interactive demo](https://demo.cloudinary.com/default)
|
180 | * [Documentation](https://cloudinary.com/documentation)
|
181 | * [Knowledge Base](https://support.cloudinary.com/hc/en-us)
|
182 | * [Documentation for Node.js integration](https://cloudinary.com/documentation/node_integration)
|
183 | * [Node.js image upload documentation](https://cloudinary.com/documentation/node_image_upload)
|
184 | * [Node.js image manipulation documentation](https://cloudinary.com/documentation/node_image_manipulation)
|
185 | * [Image transformations documentation](https://cloudinary.com/documentation/image_transformations)
|
186 |
|
187 | ## Run test
|
188 |
|
189 | ```
|
190 | npm run test
|
191 | ```
|
192 |
|
193 | ## Support
|
194 |
|
195 | You can [open an issue through GitHub](https://github.com/cloudinary/cloudinary_npm/issues).
|
196 |
|
197 | Contact us [https://cloudinary.com/contact](https://cloudinary.com/contact)
|
198 |
|
199 | Stay tuned for updates, tips and tutorials: [Blog](https://cloudinary.com/blog), [Twitter](https://twitter.com/cloudinary), [Facebook](https://www.facebook.com/Cloudinary).
|
200 |
|
201 | ## Join the Community ##########################################################
|
202 |
|
203 | Impact the product, hear updates, test drive new features and more! Join [here](https://www.facebook.com/groups/CloudinaryCommunity).
|
204 |
|
205 |
|
206 | ## License #######################################################################
|
207 |
|
208 | Released under the MIT license.
|
209 |
|
210 | Test resources include the video [Cloud Book Study](https://vimeo.com/27172301)
|
211 | which was created by [Heidi Neilson](https://vimeo.com/heidineilson)
|
212 | and is distributed under the Creative commons - attribution license (CC BY 3.0)
|