0
# Image Sources
1

2
Factory methods for creating image sources from files, buffers, or URLs. Sources represent images that can be processed with various transformations.
3

4
## Capabilities
5

6
### From File Path
7

8
Create a source from a local file path. The file will be read and uploaded to the Tinify API.
9

10
```typescript { .api }
11
/**
12
 * Create a source from a local file path
13
 * @param path - Path to the image file on the local filesystem
14
 * @returns Source instance for chaining transformations
15
 * @example tinify.fromFile("./images/photo.jpg")
16
 */
17
function fromFile(path: string): Source;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
const tinify = require("tinify");
24

25
tinify.key = "your-api-key";
26

27
// Basic compression
28
const source = tinify.fromFile("./images/photo.jpg");
29
await source.toFile("./images/compressed.jpg");
30

31
// With transformations
32
await tinify.fromFile("./images/large-photo.png")
33
  .resize({ method: "fit", width: 800, height: 600 })
34
  .toFile("./images/resized.png");
35
```
36

37
### From Buffer
38

39
Create a source from image data in memory as a string or Uint8Array buffer.
40

41
```typescript { .api }
42
/**
43
 * Create a source from image data in memory
44
 * @param data - Image data as string or Uint8Array buffer
45
 * @returns Source instance for chaining transformations
46
 * @example tinify.fromBuffer(imageBuffer)
47
 */
48
function fromBuffer(data: string | Uint8Array): Source;
49
```
50

51
**Usage Examples:**
52

53
```typescript
54
const tinify = require("tinify");
55
import * as fs from "fs";
56

57
tinify.key = "your-api-key";
58

59
// From file buffer
60
const imageBuffer = fs.readFileSync("./images/photo.jpg");
61
const source = tinify.fromBuffer(imageBuffer);
62
await source.toFile("./images/compressed.jpg");
63

64
// From API response
65
const response = await fetch("https://api.example.com/generate-image");
66
const imageData = await response.arrayBuffer();
67
await tinify.fromBuffer(new Uint8Array(imageData))
68
  .convert({ type: "image/webp" })
69
  .toFile("./images/converted.webp");
70
```
71

72
### From URL
73

74
Create a source from an image URL. The image will be downloaded by the Tinify API.
75

76
```typescript { .api }
77
/**
78
 * Create a source from an image URL
79
 * @param url - URL of the image to process
80
 * @returns Source instance for chaining transformations
81
 * @example tinify.fromUrl("https://example.com/image.jpg")
82
 */
83
function fromUrl(url: string): Source;
84
```
85

86
**Usage Examples:**
87

88
```typescript
89
const tinify = require("tinify");
90

91
tinify.key = "your-api-key";
92

93
// Process image from URL
94
await tinify.fromUrl("https://example.com/large-image.png")
95
  .toFile("./images/compressed.png");
96

97
// URL with transformations
98
await tinify.fromUrl("https://example.com/photo.jpg")
99
  .resize({ method: "cover", width: 400, height: 300 })
100
  .preserve("copyright", "location")
101
  .toFile("./images/thumbnail.jpg");
102

103
// Convert format from URL
104
const source = tinify.fromUrl("https://example.com/image.png")
105
  .convert({ type: ["image/webp", "image/avif"] });
106

107
const result = source.result();
108
const extension = await result.extension();
109
await source.toFile(`./images/converted.${extension}`);
110
```
111

112
## Source Class
113

114
All factory methods return a `Source` instance that provides a fluent API for chaining transformations.
115

116
```typescript { .api }
117
class Source {
118
  // Transformation methods (see transformations.md)
119
  resize(options: ResizeOptions): Source;
120
  convert(options: ConvertOptions): Source;
121
  preserve(options: string[]): Source;
122
  transform(options: object): Source;
123
  
124
  // Output methods (see results.md)
125
  result(): Result;
126
  toFile(path: string): Promise<void>;
127
  toBuffer(): Promise<Uint8Array>;
128
  
129
  // Cloud storage (see cloud-storage.md)
130
  store(options: StoreOptions): ResultMeta;
131
}
132
```
133

134
## Error Handling
135

136
Source creation methods can throw the following errors:
137

138
- **ClientError**: Invalid file path, unsupported image format, or malformed URL
139
- **ConnectionError**: Network issues when downloading from URL
140
- **AccountError**: API key issues or monthly limit exceeded
141
- **ServerError**: Temporary API service issues
142

143
**Error Handling Example:**
144

145
```typescript
146
const tinify = require("tinify");
147

148
tinify.key = "your-api-key";
149

150
try {
151
  const source = tinify.fromFile("./images/photo.jpg");
152
  await source.toFile("./images/compressed.jpg");
153
} catch (error) {
154
  if (error instanceof tinify.AccountError) {
155
    console.error("Account issue:", error.message);
156
  } else if (error instanceof tinify.ClientError) {
157
    console.error("Client error:", error.message);
158
  } else if (error instanceof tinify.ConnectionError) {
159
    console.error("Network error:", error.message);
160
  }
161
}
162
```