# oss-image

Part of **OSS**

# Object Storage Service Image Processing CLI Reference

## Command Overview

| Command | Purpose | Syntax |
|--------|---------|--------|
| `ossutil api put-style` | Create or update an image style in a bucket | `ossutil api put-style [flags]` |

## Command Details

### ossutil api put-style

**Purpose**: Creates or updates an image style in the specified bucket. An image style defines one or more image processing parameters (e.g., resize, crop, watermark) that can be applied to images stored in OSS.

**Syntax**:
```bash
ossutil api put-style --bucket <bucket-name> --style-name <style-name> --style <style-config>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--bucket` | — | string | Yes | The name of the target bucket. |
| `--style-name` | — | string | Yes | The name to assign to the image style. |
| `--style` | — | string | Yes | The image style configuration. Supports JSON or XML format. If the value starts with `file://`, the configuration is loaded from the specified local file. |

```bash
# Example 1: Create an image style from an XML file
ossutil api put-style --bucket examplebucket --style-name imageStyle --style file://style.xml

# Example 2: Create an image style from a JSON file
ossutil api put-style --bucket examplebucket --style-name imageStyle --style file://style.json

# Example 3: Create an image style using inline JSON (escaped)
ossutil api put-style --bucket examplebucket --style-name imageStyle --style "{\"Content\":\"image/resize,p_50\"}"
```

**Output Example**:
```text
Succeed: Total num: 1, size: 0. OK num: 1.
```

## Common Scenarios

### Scenario 1: Define and Apply a Thumbnail Style

```bash
# Step 1: Create a JSON file (thumb-style.json) with resize and quality settings
echo '{"Content":"image/resize,w_200,h_200/quality,q_80"}' > thumb-style.json

# Step 2: Upload the image style to your bucket
ossutil api put-style --bucket my-photos-bucket --style-name thumbnail --style file://thumb-style.json
```

### Scenario 2: Update an Existing Image Style Inline

```bash
# Replace the 'avatar' style with a new circular crop and resize definition
ossutil api put-style --bucket user-content --style-name avatar --style "{\"Content\":\"image/crop,w_100,h_100,g_center/radius,50\"}"
```

## Environment Setup

### Installation
Install `ossutil` by downloading the appropriate binary for your operating system from the official Object Storage Service documentation site. Follow the installation instructions provided in the "ossutil 2.0 command-line tool" guide.

### Configuration
Configure your credentials and default region before using image processing commands:

```bash
# Set access credentials and endpoint
ossutil config -e <endpoint> -i <access-key-id> -k <access-key-secret> -c ~/.ossutilconfig
```

Ensure the configured endpoint corresponds to the region where your bucket resides. Authentication uses API key headers, which must be set via the config file or environment variables (`OSS_ACCESS_KEY_ID`, `OSS_ACCESS_KEY_SECRET`).

## FAQ

Q: How do I configure credentials for the ossutil image processing commands?
A: Use `ossutil config` to set your AccessKey ID, AccessKey Secret, and endpoint, or set the `OSS_ACCESS_KEY_ID` and `OSS_ACCESS_KEY_SECRET` environment variables. The `put-style` command requires valid authentication to modify bucket-level image styles.

Q: What formats are supported for the `--style` parameter?
A: The `--style` parameter accepts configurations in either JSON or XML format. You can provide the content inline (as a JSON-escaped string) or reference a local file using the `file://` prefix (e.g., `file://style.json`).

Q: Can I use image styles immediately after creation?
A: Yes. Once created, an image style can be applied to any image object in the same bucket by appending `?x-oss-process=style/<style-name>` to the object URL.

Q: What image operations can be included in a style?
A: Supported operations include resize, crop, rotate, quality adjustment, format conversion (e.g., to WebP or JPEG), sharpen, blur, watermark, thumbnail generation, and avatar-specific transforms like circular masking.

Q: Why am I getting a permission error when running `put-style`?
A: The account must have the `oss:PutBucketImageStyle` permission on the target bucket. Verify your RAM policy or contact your administrator to grant the necessary permissions.