// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.shopping.merchant.productstudio.v1alpha;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/timestamp.proto";
import "google/shopping/merchant/productstudio/v1alpha/productstudio_common.proto";

option go_package = "cloud.google.com/go/shopping/merchant/productstudio/apiv1alpha/productstudiopb;productstudiopb";
option java_multiple_files = true;
option java_outer_classname = "ImageProto";
option java_package = "com.google.shopping.merchant.productstudio.v1alpha";

// Service that exposes Generative AI (GenAI) endpoints for creating and
// enhancing product image content.
service ImageService {
  option (google.api.default_host) = "merchantapi.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/content";

  // GenerateProductImageBackground generates a new image where the background
  // of the original image is replaced by an AI generated scene based on
  // provided product information and a text prompt.
  rpc GenerateProductImageBackground(GenerateProductImageBackgroundRequest)
      returns (GenerateProductImageBackgroundResponse) {
    option (google.api.http) = {
      post: "/productstudio/v1alpha/{name=accounts/*}/generatedImages:generateProductImageBackground"
      body: "*"
    };
    option (google.api.method_signature) = "name";
  }

  // RemoveProductImageBackground generates a new image where the background of
  // the original image is removed.
  rpc RemoveProductImageBackground(RemoveProductImageBackgroundRequest)
      returns (RemoveProductImageBackgroundResponse) {
    option (google.api.http) = {
      post: "/productstudio/v1alpha/{name=accounts/*}/generatedImages:removeProductImageBackground"
      body: "*"
    };
    option (google.api.method_signature) = "name";
  }

  // UpscaleProductImage generates a new image where the resolution of the
  // original image is enhanced.
  rpc UpscaleProductImage(UpscaleProductImageRequest)
      returns (UpscaleProductImageResponse) {
    option (google.api.http) = {
      post: "/productstudio/v1alpha/{name=accounts/*}/generatedImages:upscaleProductImage"
      body: "*"
    };
    option (google.api.method_signature) = "name";
  }
}

// Request message for the GenerateProductImageBackground method.
message GenerateProductImageBackgroundRequest {
  // Required. The account for which to generate an image. This acts as a
  // container for the request and does not affect the generation itself.
  // Format: accounts/{account}
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Configuration for how the output image should be returned.
  OutputImageConfig output_config = 2 [(google.api.field_behavior) = OPTIONAL];

  // Required. The input image.
  InputImage input_image = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. Configuration parameters for the generation of the background.
  GenerateImageBackgroundConfig config = 4
      [(google.api.field_behavior) = REQUIRED];
}

// Response message for the GenerateProductImageBackground method.
message GenerateProductImageBackgroundResponse {
  // The generated output image.
  GeneratedImage generated_image = 1;
}

// Request message for the RemoveProductImageBackground method.
message RemoveProductImageBackgroundRequest {
  // Required. The account for which to generate an image. This acts as a
  // container for the request and does not affect the generation itself.
  // Format: accounts/{account}
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Configuration for how the output image should be returned.
  OutputImageConfig output_config = 2 [(google.api.field_behavior) = OPTIONAL];

  // Required. The input image.
  InputImage input_image = 3 [(google.api.field_behavior) = REQUIRED];

  // Optional. Configuration parameters for the removal of the background.
  RemoveImageBackgroundConfig config = 4
      [(google.api.field_behavior) = OPTIONAL];
}

// Response message for the RemoveProductImageBackground method.
message RemoveProductImageBackgroundResponse {
  // The generated output image.
  GeneratedImage generated_image = 1;
}

// Request message for the UpscaleProductImage method.
message UpscaleProductImageRequest {
  // Required. The account for which to generate an image. This acts as a
  // container for the request and does not affect the generation itself.
  // Format: accounts/{account}
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Configuration for how the output image should be returned.
  OutputImageConfig output_config = 2 [(google.api.field_behavior) = OPTIONAL];

  // Required. The input image.
  InputImage input_image = 3 [(google.api.field_behavior) = REQUIRED];
}

// Response message for the UpscaleProductImage method.
message UpscaleProductImageResponse {
  // The generated output image.
  GeneratedImage generated_image = 1;
}

// Represents a generated image object.
message GeneratedImage {
  option (google.api.resource) = {
    type: "merchantapi.googleapis.com/GeneratedImage"
    pattern: "accounts/{account}/generatedImages/{generated_image}"
    plural: "generatedImages"
    singular: "generatedImage"
  };

  // The generated image.
  oneof image {
    // Generally web-requestable URI of the generated image. This is a temporary
    // URI and will expire after 6 months. A URI may not be populated
    // immediately after generation. Use get or list api using image_id to get
    // the URI.
    string uri = 2;

    // Raw bytes for the image.
    bytes image_bytes = 3;
  }

  // Identifier. The unique key for the image.
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // The timestamp when the image was generated.
  google.protobuf.Timestamp generation_time = 4;
}

// Configuration for how the output image should be returned.
message OutputImageConfig {
  // Optional. If true, returns the output images as serving uris instead of
  // bytes.
  bool return_image_uri = 1 [(google.api.field_behavior) = OPTIONAL];
}

// Client provided input configuration for generating the background.
message GenerateImageBackgroundConfig {
  // Required. Example: "Hat on a baseball field"
  // "Hat" = product description
  // Description of product.
  string product_description = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. Example: "Hat on a baseball field"
  // "on a baseball field" = background description
  // Description of wanted background.
  string background_description = 2 [(google.api.field_behavior) = REQUIRED];
}

// Client provided input configuration for removing the background.
message RemoveImageBackgroundConfig {
  // Optional. If set, the result of background removal will be an RGB image
  // with this given color as the background, instead of an RGBA 4-channel
  // transparent image.
  RgbColor background_color = 1 [(google.api.field_behavior) = OPTIONAL];
}

// Represents a color in RGB format.
message RgbColor {
  // Optional. Values in [0, 255].
  int32 red = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Values in [0, 255].
  int32 green = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Values in [0, 255].
  int32 blue = 3 [(google.api.field_behavior) = OPTIONAL];
}