Documentation
¶
Overview ¶
Package image defines the serializable image-generation protocol and its single-method Model capability.
NewRequest captures the prompt; Options carries shared per-call overrides such as dimensions, negative prompt, seed, and output MIME type. Outputs use media.Media and preserve every image returned by the provider. Provider-only options use Options.SetExtension so Extensions remains JSON-safe; Request has no arbitrary parameter bag. Implementations and defaults live outside Core.
Example ¶
package main
import (
"fmt"
"github.com/Tangerg/scope/core/image"
)
func main() {
request, err := image.NewRequest("A scope walking through snow")
if err != nil {
panic(err)
}
options := image.Options{Model: "image-model"}
err = options.Validate()
if err != nil {
panic(err)
}
options.OutputFormat = "image/png"
request.Options = options
fmt.Println(request.Options.Model, request.Options.OutputFormat)
}
Output: image-model image/png
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
Functions ¶
This section is empty.
Types ¶
type Model ¶
type Model interface {
// Call performs one image-generation request after validating all prompt and
// option invariants. It must not retain or mutate request and transfers
// ownership of the provider-neutral response to the caller. Context
// cancellation remains identifiable through errors.Is.
Call(ctx context.Context, request *Request) (*Response, error)
}
Model is the complete provider-neutral image generation SPI. Call implementations validate requests before I/O, reject explicit options they cannot represent, preserve context error identity, and return responses that pass Validate. Provider defaults and identity belong to provider construction and observability.
type Options ¶
type Options struct {
// Model is the provider model identifier (e.g. "dall-e-3").
Model string `json:"model"`
// NegativePrompt describes what should not appear in the image.
NegativePrompt string `json:"negative_prompt"`
// Width / Height set the output dimensions in pixels.
Width *int64 `json:"width,omitempty"`
Height *int64 `json:"height,omitempty"`
// Seed pins the RNG so repeated calls produce the same image.
Seed *int64 `json:"seed,omitempty"`
// OutputFormat picks the image MIME type of the rendered bytes.
// Empty leaves the format to the provider.
OutputFormat string `json:"output_format,omitempty"`
// Extensions carries JSON-safe provider-specific options unknown to this
// struct.
Extensions metadata.Extensions `json:"extensions,omitzero"`
}
Options holds per-request configuration for an image-generation call. Pointer fields preserve the distinction between an override and a provider default. Resolve snapshots mutable values and overlays only fields explicitly supplied by the request.
func (Options) MarshalJSON ¶
func (*Options) UnmarshalJSON ¶
type Output ¶
type Output struct {
// Media holds the generated image as bytes or an absolute URI.
Media *media.Media `json:"media,omitempty"`
// Metadata carries per-image extras.
Metadata metadata.Map `json:"metadata,omitzero"`
}
Output is one generated image plus its metadata.
func (Output) MarshalJSON ¶
func (*Output) UnmarshalJSON ¶
type Request ¶
type Request struct {
// Prompt is the natural-language description of the desired image.
Prompt string `json:"prompt"`
Options Options `json:"options,omitzero"`
}
Request is one image-generation call: the prompt and explicit options.
func NewRequest ¶
func (Request) MarshalJSON ¶
func (*Request) UnmarshalJSON ¶
type Response ¶
type Response struct {
// Outputs contains every image returned by the provider, in provider order.
Outputs []*Output `json:"outputs,omitzero"`
// Metadata carries shared response-level fields.
Metadata *ResponseMetadata `json:"metadata,omitempty"`
}
Response is the full image-generation output: every rendered image plus shared response metadata.
func NewResponse ¶
func NewResponse(outputs []*Output, metadata *ResponseMetadata) (*Response, error)
func (Response) MarshalJSON ¶
func (*Response) UnmarshalJSON ¶
type ResponseMetadata ¶
type ResponseMetadata struct {
// Created is the provider-reported creation time, Unix seconds.
Created int64 `json:"created"`
// Extra carries JSON-safe provider-specific metadata.
Extra metadata.Map `json:"extra,omitzero"`
}
ResponseMetadata holds response-level metadata for an image generation request.
func (ResponseMetadata) MarshalJSON ¶
func (r ResponseMetadata) MarshalJSON() ([]byte, error)
func (*ResponseMetadata) UnmarshalJSON ¶
func (r *ResponseMetadata) UnmarshalJSON(data []byte) error
Source Files