feat: add wanx background image generation api support

Author: ikesnowy

src/Cnblogs.DashScope.Sdk/BackgroundGenerationInput.cs

@@ -0,0 +1,37 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The input of background generation task.
+/// </summary>
+public class BackgroundGenerationInput
+{
+    /// <summary>
+    /// The image url to generation background on.
+    /// </summary>
+    public required string BaseImageUrl { get; set; }
+
+    /// <summary>
+    /// The reference image url for.
+    /// </summary>
+    public string? RefImageUrl { get; set; }
+
+    /// <summary>
+    /// The prompt the background would generation from.
+    /// </summary>
+    public string? RefPrompt { get; set; }
+
+    /// <summary>
+    /// The negative prompt.
+    /// </summary>
+    public string? NegRefPrompt { get; set; }
+
+    /// <summary>
+    /// The title to be put in generated image, max length is 8.
+    /// </summary>
+    public string? Title { get; set; }
+
+    /// <summary>
+    /// Valid when <see cref="Title"/> is set, max length is 10.
+    /// </summary>
+    public string? SubTitle { get; set; }
+}

src/Cnblogs.DashScope.Sdk/BackgroundGenerationOutput.cs

@@ -0,0 +1,17 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The output of background generation task.
+/// </summary>
+public record BackgroundGenerationOutput : DashScopeTaskOutput
+{
+    /// <summary>
+    /// The generated image urls.
+    /// </summary>
+    public List<BackgroundGenerationResult>? Results { get; set; }
+
+    /// <summary>
+    /// The generated result of texts.
+    /// </summary>
+    public BackgroundGenerationTextResult? TextResults { get; set; }
+}

src/Cnblogs.DashScope.Sdk/BackgroundGenerationParameters.cs

@@ -0,0 +1,22 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The parameters of background generation task.
+/// </summary>
+public class BackgroundGenerationParameters
+{
+    /// <summary>
+    /// The number of images to be generated.
+    /// </summary>
+    public int? N { get; set; }
+
+    /// <summary>
+    /// Range at [0, 999], controls the distance from generated image to reference image.
+    /// </summary>
+    public int? NoiseLevel { get; set; }
+
+    /// <summary>
+    /// Range at [0,1]. When RefImageUrl and RefPrompt are both set, controls the percentage of ref prompt weight.
+    /// </summary>
+    public float? RefPromptWeight { get; set; }
+}

src/Cnblogs.DashScope.Sdk/BackgroundGenerationResult.cs

@@ -0,0 +1,7 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The result of background generation task.
+/// </summary>
+/// <param name="Url">The url of generated image.</param>
+public record BackgroundGenerationResult(string Url);

src/Cnblogs.DashScope.Sdk/BackgroundGenerationTextResult.cs

@@ -0,0 +1,10 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The results of background generation task.
+/// </summary>
+/// <param name="Urls">The urls of images that put texts on.</param>
+/// <param name="Params">The generated texts for image.</param>
+public record BackgroundGenerationTextResult(
+    List<BackgroundGenerationTextResultUrl> Urls,
+    List<BackgroundGenerationTextResultParams>? Params);

src/Cnblogs.DashScope.Sdk/BackgroundGenerationTextResultGradient.cs

@@ -0,0 +1,18 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The gradient of background generation text.
+/// </summary>
+/// <param name="Type">Type of gradient. e.g. <c>linear</c></param>
+/// <param name="GradientUnits">Unit of gradient. e.g. <c>pixels</c></param>
+/// <param name="ColorStops">Color stops of gradient.</param>
+public record BackgroundGenerationTextResultGradient(
+    string Type,
+    string GradientUnits,
+    List<BackgroundGenerationTextResultGradientColorStop> ColorStops)
+{
+    /// <summary>
+    /// Coords of each stop, use "x1", "y1", "x2", "y2"... to access the coords.
+    /// </summary>
+    public Dictionary<string, int>? Coords { get; set; }
+}

src/Cnblogs.DashScope.Sdk/BackgroundGenerationTextResultGradientColorStop.cs

@@ -0,0 +1,8 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The color stop of gradient in background generation result.
+/// </summary>
+/// <param name="Color">The color of current stop.</param>
+/// <param name="Offset">The position of current stop.</param>
+public record BackgroundGenerationTextResultGradientColorStop(string Color, float Offset);

src/Cnblogs.DashScope.Sdk/BackgroundGenerationTextResultLayer.cs

@@ -0,0 +1,60 @@
+using System.Text.Json.Serialization;
+using Cnblogs.DashScope.Sdk.Internals;
+
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// Represents one layer of background generation text result.
+/// </summary>
+/// <param name="Idx">The if of the layer.</param>
+/// <param name="Type">The type of layer, can be "text" or "text_mask".</param>
+/// <param name="Top">The top position of the layer.</param>
+/// <param name="Left">The left position of the layer.</param>
+/// <param name="Width">The width of the layer.</param>
+/// <param name="Height">The height of the layer.</param>
+/// <param name="SubType">Available when type is "text". The type of text, can ba "Title" or "SubTitle".</param>
+/// <param name="Content">Available when type is "text". The content of the text.</param>
+/// <param name="FontFamily">Available when type is "text". The font family of the text.</param>
+/// <param name="FontSize">Available when type is "text". The font size of the text.</param>
+/// <param name="FontWeight">Available when type is "text". The font weight of the text. e.g. Medium.</param>
+/// <param name="FontColor">Available when type is "text". The color of the text in HEX format.</param>
+/// <param name="Direction">Available when type is "text". The direction of the text. e.g. vertical or horizontal.</param>
+/// <param name="Alignment">Available when type is "text". The alignment of the text, can be center, left or right.</param>
+/// <param name="LineHeight">Available when type is "text". The line height of the text.</param>
+/// <param name="FontItalic">Available when type is "text". Is the text needs to be italic.</param>
+/// <param name="FontLineThrough">Available when type is "text". Is the text has line through.</param>
+/// <param name="FontUnderLine">Available when type is "text". Is the text has underline.</param>
+/// <param name="TextShadow">Available when type is "text". The text shadow of the text. e.g. 2px 2px #80808080</param>
+/// <param name="TextStroke">Available when type is "text". The stroke of the text. e.g. 1px #fffffff0</param>
+/// <param name="Opacity">The opacity of the layer.</param>
+/// <param name="Radius">Available when type is "text_mask". The border radius of the mask.</param>
+/// <param name="BoxShadow">Available when type is "text_mask". The box shadow of the mask.</param>
+/// <param name="Color">Available when type is "text_mask". Color of the mask.</param>
+/// <param name="Gradient">Available when type is "text_mask". The gradient of the mask.</param>
+public record BackgroundGenerationTextResultLayer(
+    int Idx,
+    string Type,
+    int Top,
+    int Left,
+    int Width,
+    int Height,
+    string? SubType = null,
+    string? Content = null,
+    string? FontFamily = null,
+    int? FontSize = null,
+    string? FontWeight = null,
+    string? FontColor = null,
+    string? Direction = null,
+    string? Alignment = null,
+    float? LineHeight = null,
+    bool? FontItalic = null,
+    bool? FontLineThrough = null,
+    bool? FontUnderLine = null,
+    [property: JsonConverter(typeof(DashScopeZeroAsNullConvertor))]
+    string? TextShadow = null,
+    string? TextStroke = null,
+    float? Opacity = null,
+    int? Radius = null,
+    string? BoxShadow = null,
+    string? Color = null,
+    BackgroundGenerationTextResultGradient? Gradient = null);

src/Cnblogs.DashScope.Sdk/BackgroundGenerationTextResultParams.cs

@@ -0,0 +1,8 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The generated styles of text in one image of background generation task.
+/// </summary>
+/// <param name="SampleIdx">The id of image.</param>
+/// <param name="Layers">The layers of styled text.</param>
+public record BackgroundGenerationTextResultParams(int SampleIdx, List<BackgroundGenerationTextResultLayer> Layers);

src/Cnblogs.DashScope.Sdk/BackgroundGenerationTextResultUrl.cs

@@ -0,0 +1,7 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The generated background text url.
+/// </summary>
+/// <param name="Url">The url of generated text.</param>
+public record BackgroundGenerationTextResultUrl(string Url);

src/Cnblogs.DashScope.Sdk/BackgroundGenerationUsage.cs

@@ -0,0 +1,7 @@
+namespace Cnblogs.DashScope.Sdk;
+
+/// <summary>
+/// The usage of background generation task.
+/// </summary>
+/// <param name="ImageCount">The count of generated image.</param>
+public record BackgroundGenerationUsage(int ImageCount);

src/Cnblogs.DashScope.Sdk/DashScopeClientCore.cs

@@ -190,6 +190,15 @@ public async Task<ModelResponse<ImageGenerationOutput, ImageGenerationUsage>> Cr
             !;
     }
 
+    /// <inheritdoc />
+    public async Task<ModelResponse<BackgroundGenerationOutput, BackgroundGenerationUsage>> CreateBackgroundGenerationTaskAsync(ModelRequest<BackgroundGenerationInput, BackgroundGenerationParameters> input, CancellationToken cancellationToken = default)
+    {
+        var request = BuildRequest(HttpMethod.Post, ApiLinks.BackgroundGeneration, input, isTask: true);
+        return (await SendAsync<ModelResponse<BackgroundGenerationOutput, BackgroundGenerationUsage>>(
+            request,
+            cancellationToken))!;
+    }
+
     private static HttpRequestMessage BuildSseRequest<TPayload>(HttpMethod method, string url, TPayload payload)
         where TPayload : class
     {

src/Cnblogs.DashScope.Sdk/IDashScopeClient.cs

@@ -138,4 +138,15 @@ Task<ModelResponse<TokenizationOutput, TokenizationUsage>> TokenizeAsync(
     Task<ModelResponse<ImageGenerationOutput, ImageGenerationUsage>> CreateImageGenerationTaskAsync(
         ModelRequest<ImageGenerationInput> input,
         CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Create a background image generation task.
+    /// </summary>
+    /// <param name="input">The input of the task.</param>
+    /// <param name="cancellationToken">The cancellation token to use.</param>
+    /// <returns></returns>
+    public Task<ModelResponse<BackgroundGenerationOutput, BackgroundGenerationUsage>>
+        CreateBackgroundGenerationTaskAsync(
+            ModelRequest<BackgroundGenerationInput, BackgroundGenerationParameters> input,
+            CancellationToken cancellationToken = default);
 }

src/Cnblogs.DashScope.Sdk/Internals/DashScopeZeroAsNullConvertor.cs

@@ -0,0 +1,34 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Cnblogs.DashScope.Sdk.Internals;
+
+internal class DashScopeZeroAsNullConvertor : JsonConverter<string>
+{
+    /// <inheritdoc />
+    public override string? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+    {
+        if (reader.TokenType is JsonTokenType.Null or JsonTokenType.None)
+        {
+            return null;
+        }
+
+        if (reader.TokenType is JsonTokenType.String)
+        {
+            return reader.GetString();
+        }
+
+        if (reader.TokenType is JsonTokenType.Number)
+        {
+            return reader.GetInt32() == 0 ? null : throw new JsonException("Invalid number for string");
+        }
+
+        throw new JsonException("Invalid type for string");
+    }
+
+    /// <inheritdoc />
+    public override void Write(Utf8JsonWriter writer, string value, JsonSerializerOptions options)
+    {
+        JsonSerializer.Serialize(writer, value, options);
+    }
+}

src/Cnblogs.DashScope.Sdk/Wanx/WanxBackgroundGenerationModel.cs

@@ -0,0 +1,12 @@
+namespace Cnblogs.DashScope.Sdk.Wanx;
+
+/// <summary>
+/// Models for background generation model.
+/// </summary>
+public enum WanxBackgroundGenerationModel
+{
+    /// <summary>
+    /// wanx-background-generation-v2
+    /// </summary>
+    WanxBackgroundGenerationV2 = 1
+}

src/Cnblogs.DashScope.Sdk/Wanx/WanxGenerationApi.cs

@@ -128,4 +128,74 @@ public static Task<DashScopeTask<ImageGenerationOutput, ImageGenerationUsage>>
     {
         return dashScopeClient.GetTaskAsync<ImageGenerationOutput, ImageGenerationUsage>(taskId, cancellationToken);
     }
+
+    /// <summary>
+    /// Create wanx background generation task.
+    /// </summary>
+    /// <param name="dashScopeClient">The <see cref="IDashScopeClient"/>.</param>
+    /// <param name="model">The model to use.</param>
+    /// <param name="input">The input that generate background images from.</param>
+    /// <param name="parameters">Optional parameters for generation.</param>
+    /// <param name="cancellationToken">The cancellation token to use.</param>
+    /// <returns></returns>
+    public static async Task<DashScopeTaskOutput> CreateWanxBackgroundGenerationTaskAsync(
+        this IDashScopeClient dashScopeClient,
+        WanxBackgroundGenerationModel model,
+        BackgroundGenerationInput input,
+        BackgroundGenerationParameters? parameters = null,
+        CancellationToken cancellationToken = default)
+    {
+        var response = await dashScopeClient.CreateBackgroundGenerationTaskAsync(
+            new()
+            {
+                Model = model.GetModelName(),
+                Input = input,
+                Parameters = parameters
+            },
+            cancellationToken);
+        return response.Output;
+    }
+
+    /// <summary>
+    /// Create wanx background generation task.
+    /// </summary>
+    /// <param name="dashScopeClient">The <see cref="IDashScopeClient"/>.</param>
+    /// <param name="model">The model to use.</param>
+    /// <param name="input">The input that generate background images from.</param>
+    /// <param name="parameters">Optional parameters for generation.</param>
+    /// <param name="cancellationToken">The cancellation token to use.</param>
+    /// <returns></returns>
+    public static async Task<DashScopeTaskOutput> CreateWanxBackgroundGenerationTaskAsync(
+        this IDashScopeClient dashScopeClient,
+        string model,
+        BackgroundGenerationInput input,
+        BackgroundGenerationParameters? parameters = null,
+        CancellationToken cancellationToken = default)
+    {
+        var response = await dashScopeClient.CreateBackgroundGenerationTaskAsync(
+            new()
+            {
+                Model = model,
+                Input = input,
+                Parameters = parameters
+            },
+            cancellationToken);
+        return response.Output;
+    }
+
+    /// <summary>
+    /// Query wanx background generation task status.
+    /// </summary>
+    /// <param name="client">The <see cref="IDashScopeClient"/>.</param>
+    /// <param name="taskId">The task id to query.</param>
+    /// <param name="cancellationToken">The cancellation token to use.</param>
+    /// <returns></returns>
+    public static Task<DashScopeTask<BackgroundGenerationOutput, BackgroundGenerationUsage>>
+        GetWanxBackgroundGenerationTaskAsync(
+            this IDashScopeClient client,
+            string taskId,
+            CancellationToken cancellationToken = default)
+    {
+        return client.GetTaskAsync<BackgroundGenerationOutput, BackgroundGenerationUsage>(taskId, cancellationToken);
+    }
 }

src/Cnblogs.DashScope.Sdk/Wanx/WanxModelNames.cs

@@ -21,4 +21,13 @@ public static string GetModelName(this WanxStyleRepaintModel model)
             _ => ThrowHelper.UnknownModelName(nameof(model), model)
         };
     }
+
+    public static string GetModelName(this WanxBackgroundGenerationModel model)
+    {
+        return model switch
+        {
+            WanxBackgroundGenerationModel.WanxBackgroundGenerationV2 => "wanx-background-generation-v2",
+            _ => ThrowHelper.UnknownModelName(nameof(model), model)
+        };
+    }
 }