Initial commit

2025-11-30 08:24:18 +08:00
commit b0e1f6dfe3
25 changed files with 6267 additions and 0 deletions
--- a/references/api-reference.md
+++ b/references/api-reference.md
@@ -0,0 +1,403 @@
+# Cloudflare Images API Reference
+
+Complete API endpoints for Cloudflare Images.
+
+**Base URL**: `https://api.cloudflare.com/client/v4/accounts/{account_id}`
+**Batch API**: `https://batch.imagedelivery.net`
+
+---
+
+## Authentication
+
+All requests require an API token with **Cloudflare Images: Edit** permission.
+
+```bash
+Authorization: Bearer <API_TOKEN>
+```
+
+Get API token: Dashboard → My Profile → API Tokens → Create Token
+
+---
+
+## Upload Endpoints
+
+### Upload Image (File)
+
+`POST /accounts/{account_id}/images/v1`
+
+Upload an image file.
+
+**Headers**:
+- `Authorization: Bearer <API_TOKEN>`
+- `Content-Type: multipart/form-data`
+
+**Form Fields**:
+- `file` (required): Image file
+- `id` (optional): Custom ID (auto-generated if not provided)
+- `requireSignedURLs` (optional): `true` for private images
+- `metadata` (optional): JSON object (max 1024 bytes)
+
+**Example**:
+```bash
+curl --request POST \
+  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1 \
+  --header "Authorization: Bearer <API_TOKEN>" \
+  --form 'file=@./image.jpg' \
+  --form 'requireSignedURLs=false' \
+  --form 'metadata={"key":"value"}'
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "result": {
+    "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
+    "filename": "image.jpg",
+    "uploaded": "2022-01-31T16:39:28.458Z",
+    "requireSignedURLs": false,
+    "variants": [
+      "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0.../public"
+    ]
+  }
+}
+```
+
+---
+
+### Upload via URL
+
+`POST /accounts/{account_id}/images/v1`
+
+Ingest image from external URL.
+
+**Form Fields**:
+- `url` (required): Image URL to ingest
+- `id` (optional): Custom ID
+- `requireSignedURLs` (optional): `true` for private images
+- `metadata` (optional): JSON object
+
+**Example**:
+```bash
+curl --request POST \
+  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1 \
+  --header "Authorization: Bearer <API_TOKEN>" \
+  --form 'url=https://example.com/image.jpg' \
+  --form 'metadata={"source":"external"}'
+```
+
+**Note**: Cannot use both `file` and `url` in same request.
+
+---
+
+### Direct Creator Upload
+
+`POST /accounts/{account_id}/images/v2/direct_upload`
+
+Generate one-time upload URL for user uploads.
+
+**Headers**:
+- `Authorization: Bearer <API_TOKEN>`
+- `Content-Type: application/json`
+
+**Body**:
+```json
+{
+  "requireSignedURLs": false,
+  "metadata": {"userId": "12345"},
+  "expiry": "2025-10-26T18:00:00Z",
+  "id": "custom-id"
+}
+```
+
+**Fields**:
+- `requireSignedURLs` (optional): `true` for private images
+- `metadata` (optional): JSON object
+- `expiry` (optional): ISO 8601 timestamp (default: 30min, max: 6hr)
+- `id` (optional): Custom ID (cannot use with `requireSignedURLs=true`)
+
+**Response**:
+```json
+{
+  "success": true,
+  "result": {
+    "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
+    "uploadURL": "https://upload.imagedelivery.net/..."
+  }
+}
+```
+
+**Frontend Upload**:
+```javascript
+const formData = new FormData();
+formData.append('file', fileInput.files[0]); // MUST be named 'file'
+
+await fetch(uploadURL, {
+  method: 'POST',
+  body: formData // NO Content-Type header
+});
+```
+
+---
+
+## Image Management
+
+### List Images
+
+`GET /accounts/{account_id}/images/v2`
+
+List all images (paginated).
+
+**Query Params**:
+- `page` (optional): Page number (default: 1)
+- `per_page` (optional): Results per page (default: 100, max: 100)
+
+**Example**:
+```bash
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v2?page=1&per_page=50" \
+  --header "Authorization: Bearer <API_TOKEN>"
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "result": {
+    "images": [
+      {
+        "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
+        "filename": "image.jpg",
+        "uploaded": "2022-01-31T16:39:28.458Z",
+        "requireSignedURLs": false,
+        "variants": ["https://imagedelivery.net/.../public"]
+      }
+    ]
+  }
+}
+```
+
+---
+
+### Get Image Details
+
+`GET /accounts/{account_id}/images/v1/{image_id}`
+
+Get details of specific image.
+
+**Example**:
+```bash
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/{image_id}" \
+  --header "Authorization: Bearer <API_TOKEN>"
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "result": {
+    "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
+    "filename": "image.jpg",
+    "uploaded": "2022-01-31T16:39:28.458Z",
+    "requireSignedURLs": false,
+    "draft": false,
+    "variants": ["https://imagedelivery.net/.../public"]
+  }
+}
+```
+
+**Note**: `draft: true` means Direct Creator Upload not completed yet.
+
+---
+
+### Delete Image
+
+`DELETE /accounts/{account_id}/images/v1/{image_id}`
+
+Delete an image.
+
+**Example**:
+```bash
+curl --request DELETE \
+  "https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/{image_id}" \
+  --header "Authorization: Bearer <API_TOKEN>"
+```
+
+**Response**:
+```json
+{
+  "success": true
+}
+```
+
+---
+
+## Variants Management
+
+### Create Variant
+
+`POST /accounts/{account_id}/images/v1/variants`
+
+Create a new variant.
+
+**Body**:
+```json
+{
+  "id": "thumbnail",
+  "options": {
+    "fit": "cover",
+    "width": 300,
+    "height": 300,
+    "metadata": "none"
+  },
+  "neverRequireSignedURLs": false
+}
+```
+
+**Options**:
+- `fit`: `scale-down`, `contain`, `cover`, `crop`, `pad`
+- `width`: Max width in pixels
+- `height`: Max height in pixels
+- `metadata`: `none`, `copyright`, `keep`
+
+**Example**:
+```bash
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/variants" \
+  --header "Authorization: Bearer <API_TOKEN>" \
+  --header "Content-Type: application/json" \
+  --data '{"id":"thumbnail","options":{"fit":"cover","width":300,"height":300}}'
+```
+
+---
+
+### List Variants
+
+`GET /accounts/{account_id}/images/v1/variants`
+
+List all variants.
+
+**Example**:
+```bash
+curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/variants" \
+  --header "Authorization: Bearer <API_TOKEN>"
+```
+
+---
+
+### Get Variant
+
+`GET /accounts/{account_id}/images/v1/variants/{variant_id}`
+
+Get specific variant details.
+
+---
+
+### Update Variant
+
+`PATCH /accounts/{account_id}/images/v1/variants/{variant_id}`
+
+Update existing variant.
+
+**Body**:
+```json
+{
+  "options": {
+    "width": 350,
+    "height": 350
+  }
+}
+```
+
+---
+
+### Delete Variant
+
+`DELETE /accounts/{account_id}/images/v1/variants/{variant_id}`
+
+Delete a variant.
+
+---
+
+### Enable Flexible Variants
+
+`PATCH /accounts/{account_id}/images/v1/config`
+
+Enable or disable flexible variants (dynamic transformations).
+
+**Body**:
+```json
+{
+  "flexible_variants": true
+}
+```
+
+---
+
+## Batch API
+
+Same endpoints as regular API, but different host and authentication.
+
+**Host**: `https://batch.imagedelivery.net`
+**Auth**: Batch token (create in Dashboard → Images → Batch API)
+
+**Endpoints**:
+- `POST /images/v1` - Upload image
+- `GET /images/v2` - List images
+- `DELETE /images/v1/{image_id}` - Delete image
+
+**Example**:
+```bash
+curl "https://batch.imagedelivery.net/images/v1" \
+  --header "Authorization: Bearer <BATCH_TOKEN>" \
+  --form 'file=@./image.jpg'
+```
+
+---
+
+## Error Codes
+
+### HTTP Status Codes
+- `200 OK` - Request successful
+- `400 Bad Request` - Invalid request (check error message)
+- `401 Unauthorized` - Invalid or missing API token
+- `403 Forbidden` - Insufficient permissions
+- `404 Not Found` - Resource not found
+- `413 Payload Too Large` - File too large
+- `429 Too Many Requests` - Rate limit exceeded
+- `500 Internal Server Error` - Cloudflare error
+- `502 Bad Gateway` - Transformation error
+
+### Cloudflare Errors
+Check `errors` array in response:
+```json
+{
+  "success": false,
+  "errors": [
+    {
+      "code": 5400,
+      "message": "Error description"
+    }
+  ]
+}
+```
+
+Common error codes:
+- `5400` - Invalid request
+- `5408` - Upload timeout
+- `5454` - Unsupported protocol
+
+---
+
+## Rate Limits
+
+- **Standard uploads**: No published rate limits
+- **Direct Creator Upload**: Limited by one-time URL expiry (default 30min, max 6hr)
+- **Batch API**: Contact Cloudflare for high-volume needs
+
+---
+
+## Official Documentation
+
+- **Images API**: https://developers.cloudflare.com/api/resources/images/
+- **Upload Images**: https://developers.cloudflare.com/images/upload-images/
+- **Direct Creator Upload**: https://developers.cloudflare.com/images/upload-images/direct-creator-upload/
+- **Variants**: https://developers.cloudflare.com/images/manage-images/create-variants/