// Copyright 2026 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.ads.googleads.v22.services;

import "google/ads/googleads/v22/enums/advertising_channel_type.proto";
import "google/ads/googleads/v22/enums/asset_field_type.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";

option csharp_namespace = "Google.Ads.GoogleAds.V22.Services";
option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v22/services;services";
option java_multiple_files = true;
option java_outer_classname = "AssetGenerationServiceProto";
option java_package = "com.google.ads.googleads.v22.services";
option objc_class_prefix = "GAA";
option php_namespace = "Google\\Ads\\GoogleAds\\V22\\Services";
option ruby_package = "Google::Ads::GoogleAds::V22::Services";

// Service for generating new assets with generative AI.
service AssetGenerationService {
  option (google.api.default_host) = "googleads.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/adwords";

  // Uses generative AI to generate text that can be used as assets in a
  // campaign.
  //
  // List of thrown errors:
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [AssetGenerationError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QuotaError]()
  //   [RequestError]()
  rpc GenerateText(GenerateTextRequest) returns (GenerateTextResponse) {
    option (google.api.http) = {
      post: "/v22/customers/{customer_id=*}/assetGenerations:generateText"
      body: "*"
    };
  }

  // Uses generative AI to generate images that can be used as assets in a
  // campaign.
  //
  // List of thrown errors:
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [AssetGenerationError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QuotaError]()
  //   [RequestError]()
  rpc GenerateImages(GenerateImagesRequest) returns (GenerateImagesResponse) {
    option (google.api.http) = {
      post: "/v22/customers/{customer_id=*}/assetGenerations:generateImages"
      body: "*"
    };
  }
}

// Request message for
// [AssetGenerationService.GenerateText][google.ads.googleads.v22.services.AssetGenerationService.GenerateText]
message GenerateTextRequest {
  // Required. The ID of the customer to generate assets for. Required.
  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. Which field types text is being generated for. Supported values
  // are: HEADLINE, LONG_HEADLINE, DESCRIPTION. Required.
  repeated google.ads.googleads.v22.enums.AssetFieldTypeEnum.AssetFieldType
      asset_field_types = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. Final url to use as a source for generating assets.
  // Required if existing_generation_context is not provided
  // or does not have a final url associated with it.
  string final_url = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A freeform description of what assets should be generated.
  // The string length must be between 1 and 1500, inclusive.
  string freeform_prompt = 6 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A freeform list of keywords that are relevant,
  // used to inform asset generation.
  repeated string keywords = 7 [(google.api.field_behavior) = OPTIONAL];

  // Additional context to guide the generation process.
  oneof context {
    // Optional. The setting for which assets are being generated, such as an
    // existing AssetGroup or AdGroupAd.
    AssetGenerationExistingContext existing_generation_context = 3
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. The advertising channel for which to generate assets. Required
    // if existing_context is not provided.
    //
    // Supported channel types:
    // SEARCH, PERFORMANCE_MAX, DISPLAY, and DEMAND_GEN
    google.ads.googleads.v22.enums.AdvertisingChannelTypeEnum
        .AdvertisingChannelType advertising_channel_type = 4
        [(google.api.field_behavior) = OPTIONAL];
  }
}

// Response message for
// [AssetGenerationService.GenerateText][google.ads.googleads.v22.services.AssetGenerationService.GenerateText]
message GenerateTextResponse {
  // List of text that was generated and the field type to use it as.
  repeated GeneratedText generated_text = 1;
}

// Data and metadata about a piece of generated text.
message GeneratedText {
  // A string of text that was generated.
  string text = 1;

  // The type of asset this text is intended to be used as.
  google.ads.googleads.v22.enums.AssetFieldTypeEnum.AssetFieldType
      asset_field_type = 2;
}

// Request message for
// [AssetGenerationService.GenerateImages][google.ads.googleads.v22.services.AssetGenerationService.GenerateImages]
message GenerateImagesRequest {
  // Required. The ID of the customer for whom the images are being generated.
  // Required.
  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Output field types for generated images. Supported values are
  // MARKETING_IMAGE, SQUARE_MARKETING_IMAGE, PORTRAIT_MARKETING_IMAGE, and
  // TALL_PORTRAIT_MARKETING_IMAGE. All specified field types must be
  // compatible with the `advertising_channel_type` or
  // `existing_generation_context` (whichever is set). If no field types are
  // provided, images will be generated for all compatible field types.
  repeated google.ads.googleads.v22.enums.AssetFieldTypeEnum.AssetFieldType
      asset_field_types = 4 [(google.api.field_behavior) = OPTIONAL];

  // Additional context to guide image generation.
  oneof context {
    // Optional. The advertising channel type for which the images are being
    // generated. This field is required if `existing_generation_context` is not
    // provided. Supported channel types include SEARCH, PERFORMANCE_MAX,
    // DISPLAY, and DEMAND_GEN.
    google.ads.googleads.v22.enums.AdvertisingChannelTypeEnum
        .AdvertisingChannelType advertising_channel_type = 2
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Type of image generation to apply. Required.
  oneof generation_type {
    // Optional. Generate images from a final url.
    FinalUrlImageGenerationInput final_url_generation = 5
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Generate images from a freeform prompt.
    FreeformImageGenerationInput freeform_generation = 6
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Generate new images by recontextualizing existing product
    // images.
    ProductRecontextGenerationImageInput product_recontext_generation = 7
        [(google.api.field_behavior) = OPTIONAL];
  }
}

// Input for guiding image asset generation with a final url.
message FinalUrlImageGenerationInput {
  // Required. A final url to guide the image generation process. Required.
  string final_url = 1 [(google.api.field_behavior) = REQUIRED];
}

// Input for guiding image asset generation with a freeform prompt.
message FreeformImageGenerationInput {
  // Required. A freeform text description to guide the image generation
  // process. The maximum length is 1500 characters. Required.
  string freeform_prompt = 1 [(google.api.field_behavior) = REQUIRED];
}

// Input for generating new images by recontextualizing existing product images.
message ProductRecontextGenerationImageInput {
  // Optional. A freeform description of the assets to be generated.
  // Maximum character limit is 1500.
  string prompt = 1 [(google.api.field_behavior) = OPTIONAL];

  // Required. Product images to use for generating new images.
  // 1-3 images must be provided.
  repeated SourceImage source_images = 2
      [(google.api.field_behavior) = REQUIRED];
}

// Response message for
// [AssetGenerationService.GenerateImages][google.ads.googleads.v22.services.AssetGenerationService.GenerateImages]
message GenerateImagesResponse {
  // Successfully generated images.
  repeated GeneratedImage generated_images = 1;
}

// A source image to be used in the generation process.
message SourceImage {
  // The image to be used as a source.
  oneof image {
    // Optional. Raw bytes of the image to use.
    bytes image_data = 1 [(google.api.field_behavior) = OPTIONAL];
  }
}

// Generated image data and metadata.
message GeneratedImage {
  // A temporary URL for the generated image.
  string image_temporary_url = 1;

  // The intended field type for this generated image.
  google.ads.googleads.v22.enums.AssetFieldTypeEnum.AssetFieldType
      asset_field_type = 2;
}

// The context for which assets are being generated, such as an existing
// AssetGroup or AdGroupAd.
message AssetGenerationExistingContext {
  // An existing context to generate assets for.
  oneof existing_context {
    // Resource name of an existing AssetGroup for which these assets are being
    // generated.
    string existing_asset_group = 1 [(google.api.resource_reference) = {
      type: "googleads.googleapis.com/AssetGroup"
    }];

    // Resource name of an existing AdGroupAd for which these assets are being
    // generated.
    string existing_ad_group_ad = 2 [(google.api.resource_reference) = {
      type: "googleads.googleapis.com/AdGroupAd"
    }];
  }
}