Skip to content

Commit

Permalink
api docs 4.2
Browse files Browse the repository at this point in the history
  • Loading branch information
@rodber
rodber committed Oct 15, 2024
1 parent 581c6c3 commit fd5d0eb
Showing 1 changed file with 123 additions and 114 deletions.
237 changes: 123 additions & 114 deletions developer/api/api-v1.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# API Version 1.1

Chevereto API V1 was introduced in Chevereto V2 and it allows to upload pictures as guest to a Chevereto website.

Chevereto V4 updates API V1 to 1.1 introducing support for **user API keys** and more upload parameters including title, width, and more.
Chevereto API enables programmatic file uploads, allowing you to seamlessly integrate our uploading functionality into your own applications.

## Key

API V1.1 works with an user key which is available for each user at `/settings/api`. Admin user can set the public API key for guest uploads at the [Dashboard panel](https://v4-admin.chevereto.com/settings/guest-api.html#public-api-key).
API V1.1 works with an user key which is available for each user at `/settings/api`.

Admin user can set the public API key for guest uploads at the [Dashboard panel](https://v4-admin.chevereto.com/settings/guest-api.html#public-api-key).

## Request method

Expand All @@ -25,76 +25,63 @@ http://mysite.com/api/1/upload
API V1.1 supports header authorization by passing the `X-API-Key` header with an API key.

```plain
X-API-Key: chv_asd_somekeyhere
X-API-Key: chv_key_here
```

## Parameters

### Required Parameters

| Name | Description |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| source | A image URL or a [base64](https://en.wikipedia.org/wiki/Base64) encoded image string. Also supports `FILES["source"]`. |

### Optional Parameters

| Name | Description |
| ----------- | ------------------------------------------------------------- |
| title | Image title |
| description | Image description |
| album_id | Image album id, must be owned by the user (encoded string) |
| category_id | Category id (integer) |
| width | Target resize width (automatic height) |
| expiration | [Expiration](#expiration-table) time to auto-delete the image |
| nsfw | Not safe for work flag (integer `0`, `1`) |
| format | Return format, values `json`, `redirect`, `txt` |

### Legacy Parameters

| Name | Description |
| ---- | ------------------------------------------------- |
| key | The API key (see [Authorization](#authorization)) |

### Expiration table

Following values can be used for `expiration` parameter.

| Value | Expires after |
| ----- | ------------- |
| PT5M | 5 minutes |
| PT15M | 15 minutes |
| PT30M | 30 minutes |
| PT1H | 1 hour |
| PT3H | 3 hours |
| PT6H | 6 hours |
| PT12H | 12 hours |
| P1D | 1 day |
| P2D | 2 days |
| P3D | 3 days |
| P4D | 4 days |
| P5D | 5 days |
| P6D | 6 days |
| P1W | 1 week |
| P2W | 2 weeks |
| P3W | 3 weeks |
| P1M | 1 month |
| P2M | 2 months |
| P3M | 3 months |
| P4M | 4 months |
| P5M | 5 months |
| P6M | 6 months |
| P1Y | 1 year |

### Compatibility with ImgBB API

ImgBB is a popular image hosting service 100% based on Chevereto (V3).

Any existing [ImgBB API client](https://github.com/search?q=imgbb) is compatible with Chevereto V4's API V1.1, simple as change the domain name.
### source

A binary file, base64 data, or a URL for an image.

### key (optional)

The API key. You can use this parameter if unable to provide auth via headers.

### title (optional)

File title. This is automatically detected from metadata if not provided.

### description (optional)

File description. This is automatically detected from metadata if not provided.

### tags (optional)

File tag(s). Comma separated list of tags.

### album_id (optional)

File album id, must be owned by the API key user.

### category_id (optional)

Category id. Determines the file category to assign.

### width (optional)

Target resize width, will automatic detect height.

### expiration (optional)

Expiration time to auto-delete the file in date interval format. For example, PT5M for five minutes in the future. P3D for three days in the future.

### nsfw (optional)

Not safe for work flag `[0, 1]`.

### format (optional)

Return format `[json, redirect, txt]`.

## Example call

```plain
POST http://mysite.com/api/1/upload
curl --fail-with-body -X POST \
-H "X-API-Key: $key" \
-H "Content-Type: multipart/form-data" \
-F "source=@image.jpeg" \
http://mysite.com/api/1/upload
```

## API response
Expand All @@ -115,83 +102,99 @@ When using JSON the response output will contain the `status_txt` and `status_co
{
"status_code": 200,
"success": {
"message": "image uploaded",
"message": "file uploaded",
"code": 200
},
"image": {
"name": "cannon-zoom-lens",
"extension": "jpeg",
"size": 296362,
"width": 1920,
"height": 1280,
"date": "2024-03-20 15:49:31",
"date_gmt": "2024-03-20 18:49:31",
"title": "cannon zoom lens",
"name": "Badgers-animated-music-video",
"extension": "mp4",
"size": 3011299,
"width": 496,
"height": 360,
"date": "2024-10-10 16:58:00",
"date_gmt": "2024-10-10 19:58:00",
"title": "Badgers animated music video MrWeebl",
"tags": [],
"description": null,
"nsfw": 0,
"storage_mode": "datefolder",
"md5": "fde3bfd2a50ce00f0be0c32ec7088240",
"md5": "7a120d5c28de264bdbb934f023a628fd",
"source_md5": null,
"original_filename": "cannon-zoom-lens.jpg",
"original_exifdata": "{\"FileName\":\"chvtempQmM74X\",\"FileDateTime\":\"1710960571\",\"FileSize\":\"296362\",\"FileType\":\"2\",\"MimeType\":\"image\\/jpeg\",\"SectionsFound\":\"\",\"COMPUTED\":{\"html\":\"width=\\\"1920\\\" height=\\\"1280\\\"\",\"Height\":\"1280\",\"Width\":\"1920\",\"IsColor\":\"1\"},\"IPTC\":[],\"width\":\"1920\",\"height\":\"1280\"}",
"original_filename": "Badgers _ animated music video _ MrWeebl.mp4",
"original_exifdata": null,
"views": 0,
"category_id": null,
"chain": 7,
"thumb_size": 35327,
"medium_size": 48481,
"expiration_date_gmt": null,
"chain": 21,
"thumb_size": 21212,
"medium_size": 0,
"frame_size": 19804,
"expiration_date_gmt": "2024-10-10 20:28:00",
"likes": 0,
"is_animated": 0,
"is_approved": 1,
"is_360": 0,
"duration": 73,
"type": "video",
"tags_string": "",
"file": {
"resource": {
"type": "path"
"type": "url"
}
},
"id_encoded": "vZxn",
"filename": "cannon-zoom-lens.jpeg",
"mime": "image/jpeg",
"url": "http://localhost/images/2024/03/20/cannon-zoom-lens.jpeg",
"url_viewer": "http://localhost/image/cannon-zoom-lens.vZxn",
"path_viewer": "/image/cannon-zoom-lens.vZxn",
"url_short": "http://localhost/image/vZxn",
"image": {
"filename": "cannon-zoom-lens.jpeg",
"name": "cannon-zoom-lens",
"id_encoded": "ZfGd",
"filename": "Badgers-animated-music-video.mp4",
"mime": "video/mp4",
"url": "http://localhost/images/2024/10/10/Badgers-animated-music-video.mp4",
"ratio": 1.3777777777777778,
"size_formatted": "3 MB",
"frame": {
"filename": "Badgers-animated-music-video.fr.jpeg",
"name": "Badgers-animated-music-video.fr",
"mime": "image/jpeg",
"extension": "jpeg",
"url": "http://localhost/images/2024/03/20/cannon-zoom-lens.jpeg",
"size": 296362
"url": "http://localhost/images/2024/10/10/Badgers-animated-music-video.fr.jpeg",
"size": 19804
},
"image": {
"filename": "Badgers-animated-music-video.mp4",
"name": "Badgers-animated-music-video",
"mime": "video/mp4",
"extension": "mp4",
"url": "http://localhost/images/2024/10/10/Badgers-animated-music-video.mp4",
"size": 3011299
},
"thumb": {
"filename": "cannon-zoom-lens.th.jpeg",
"name": "cannon-zoom-lens.th",
"filename": "Badgers-animated-music-video.th.jpeg",
"name": "Badgers-animated-music-video.th",
"mime": "image/jpeg",
"extension": "jpeg",
"url": "http://localhost/images/2024/03/20/cannon-zoom-lens.th.jpeg",
"size": 35327
"url": "http://localhost/images/2024/10/10/Badgers-animated-music-video.th.jpeg",
"size": 21212
},
"url_frame": "http://localhost/images/2024/10/10/Badgers-animated-music-video.fr.jpeg",
"medium": {
"filename": "cannon-zoom-lens.md.jpeg",
"name": "cannon-zoom-lens.md",
"mime": "image/jpeg",
"extension": "jpeg",
"url": "http://localhost/images/2024/03/20/cannon-zoom-lens.md.jpeg",
"size": 48481
"filename": null,
"name": null,
"mime": null,
"extension": null,
"url": null
},
"size_formatted": "296.4 KB",
"display_url": "http://localhost/images/2024/03/20/cannon-zoom-lens.md.jpeg",
"display_width": "500",
"display_height": 333,
"duration_time": "01:13",
"url_viewer": "http://localhost/clip/Badgers-animated-music-video-MrWeebl.ZfGd",
"path_viewer": "/clip/Badgers-animated-music-video-MrWeebl.ZfGd",
"url_short": "http://localhost/clip/ZfGd",
"display_url": "http://localhost/images/2024/10/10/Badgers-animated-music-video.fr.jpeg",
"display_width": 496,
"display_height": 360,
"views_label": "views",
"likes_label": "likes",
"how_long_ago": "moments ago",
"date_fixed_peer": "2024-03-20 18:49:31",
"title_truncated": "cannon zoom lens",
"title_truncated_html": "cannon zoom lens",
"date_fixed_peer": "2024-10-10 19:58:00",
"title_truncated": "Badgers animated music vi...",
"title_truncated_html": "Badgers animated music vi...",
"is_use_loader": false,
"delete_url": "http://localhost/image/vZxn/delete/9ed729f18b596631068d19f3d22bd5fff3a2a1d4c57d13cd"
"display_title": "Badgers animated music video MrWeebl",
"delete_url": "http://localhost/clip/ZfGd/delete/e8b07479818bc58d3b9849c431e9c2b28827ccce7809ed4f"
},
"status_txt": "OK"
}
Expand All @@ -200,5 +203,11 @@ When using JSON the response output will contain the `status_txt` and `status_co
## Example response (txt)

```plain
http://127.0.0.1/images/2014/06/04/example.png
http://localhost/images/2024/10/10/Badgers-animated-music-video.mp4
```

## Example response (redirect)

```plain
Location: /clip/Badgers-animated-music-video-MrWeebl.ZfGd
```

0 comments on commit fd5d0eb

Please sign in to comment.