Documentation
¶
Overview ¶
Package pollinations implements a client for the Pollinations API.
It is described at https://github.com/pollinations/pollinations/blob/master/APIDOCS.md
Index ¶
- func ProcessStream(chunks iter.Seq[ChatStreamChunkResponse]) (iter.Seq[genai.Reply], func() (genai.Usage, [][]genai.Logprob, error))
- func Scoreboard() scoreboard.Score
- type ChatRequest
- type ChatResponse
- type ChatStreamChunkResponse
- type Client
- func (c *Client) GenStream(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (iter.Seq[genai.Reply], func() (genai.Result, error))
- func (c *Client) GenStreamRaw(ctx context.Context, in *ChatRequest) (iter.Seq[ChatStreamChunkResponse], func() error)
- func (c *Client) GenSync(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (genai.Result, error)
- func (c *Client) GenSyncRaw(ctx context.Context, in *ChatRequest, out *ChatResponse) error
- func (c *Client) HTTPClient() *http.Client
- func (c *Client) ListImageGenModels(ctx context.Context) ([]genai.Model, error)
- func (c *Client) ListModels(ctx context.Context) ([]genai.Model, error)
- func (c *Client) ListTextModels(ctx context.Context) ([]genai.Model, error)
- func (c *Client) ModelID() string
- func (c *Client) Name() string
- func (c *Client) OutputModalities() genai.Modalities
- func (c *Client) Scoreboard() scoreboard.Score
- type CodeValue
- type Content
- type ContentFilterResult
- type ContentType
- type Contents
- type ErrorResponse
- type ErrorValue
- type FinishReason
- type ImageModel
- type ImageModelsResponse
- type Message
- type MessageResponse
- type PromptFilterResult
- type ReasoningEffort
- type Strings
- type TextModel
- type TextModelsResponse
- type Tool
- type ToolCall
- type UnionError
- type Usage
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ChatRequest ¶
type ChatRequest struct {
Messages []Message `json:"messages"`
MaxTokens int64 `json:"max_tokens,omitzero"`
Model string `json:"model"`
Seed int64 `json:"seed,omitzero"`
Stream bool `json:"stream"`
ResponseFormat struct {
Type string `json:"type,omitzero"` // "json_object"
} `json:"response_format,omitzero"`
Tools []Tool `json:"tools,omitzero"`
ToolChoice string `json:"tool_choice,omitzero"` // "none", "auto", "required", or struct {"type": "function", "function": {"name": "my_function"}}
Private bool `json:"private,omitzero"` // Set to true to prevent the response from appearing in the public feed.
ReasoningEffort ReasoningEffort `json:"reasoning_format,omitzero"`
// https://github.com/pollinations/pollinations/blob/master/APIDOCS.md
Modalities []string `json:"modalities,omitzero"`
Audio struct {
Voice string `json:"voice,omitzero"`
Format string `json:"format,omitzero"` // "pcm16"
} `json:"audio,omitzero"`
// These are not documented at all.
Temperature float64 `json:"temperature,omitzero"`
TopP float64 `json:"top_p,omitzero"` // [0, 1.0]
Stop []string `json:"stop,omitzero"` // Up to 4 sequences
StreamOptions struct {
IncludeUsage bool `json:"include_usage,omitzero"`
} `json:"stream_options,omitzero"`
Logprobs bool `json:"logprobs,omitzero"`
TopLogprobs int64 `json:"top_logprobs,omitzero"`
}
ChatRequest is barely documented at https://github.com/pollinations/pollinations/blob/master/APIDOCS.md#text--multimodal-openai-compatible-post-%EF%B8%8F%EF%B8%8F
The structure is severely underdocumented.
func (*ChatRequest) Init ¶
Init initializes the provider specific completion request with the generic completion request.
func (*ChatRequest) SetStream ¶
func (c *ChatRequest) SetStream(stream bool)
SetStream sets the streaming mode.
type ChatResponse ¶
type ChatResponse struct {
ID string `json:"id"`
Object string `json:"object"` // "chat.completion"
Created base.Time `json:"created"`
Model string `json:"model"` // The actual model name, which is likely different from the alias.
Choices []struct {
Index int64 `json:"index"`
Message MessageResponse `json:"message"`
FinishReason FinishReason `json:"finish_reason"`
StopReason struct{} `json:"stop_reason"`
Logprobs struct{} `json:"logprobs"`
ContentFilterResults ContentFilterResult `json:"content_filter_results"`
} `json:"choices"`
Usage Usage `json:"usage"`
PromptFilterResults []PromptFilterResult `json:"prompt_filter_results"`
SystemFingerprint string `json:"system_fingerprint"`
PromptLogprobs struct{} `json:"prompt_logprobs"`
KVTransferParams struct{} `json:"kv_transfer_params"`
UserTier string `json:"user_tier"`
}
ChatResponse is the provider-specific chat completion response.
type ChatStreamChunkResponse ¶
type ChatStreamChunkResponse struct {
ID string `json:"id"` //
Object string `json:"object"` // "chat.completion.chunk"
Created base.Time `json:"created"` //
Model string `json:"model"` // Original model full name
Choices []struct {
ContentFilterResults ContentFilterResult `json:"content_filter_results"`
Index int64 `json:"index"`
Logprobs struct{} `json:"logprobs"`
FinishReason FinishReason `json:"finish_reason"`
StopReason struct{} `json:"stop_reason"`
MatchedStop int64 `json:"matched_stop"`
Delta struct {
Role string `json:"role"`
Content string `json:"content"`
ReasoningContent string `json:"reasoning_content"`
ToolCalls []ToolCall `json:"tool_calls"`
Refusal struct{} `json:"refusal"`
} `json:"delta"`
} `json:"choices"`
PromptFilterResults []PromptFilterResult `json:"prompt_filter_results"`
SystemFingerprint string `json:"system_fingerprint"`
Usage Usage `json:"usage"`
}
ChatStreamChunkResponse is the provider-specific streaming chat chunk.
type Client ¶
type Client struct {
base.NotImplemented
// contains filtered or unexported fields
}
Client implements genai.Provider.
func New ¶
New creates a new client to talk to the Pollinations platform API.
The value for ProviderOptionAPIKey can be either an API key retrieved from https://auth.pollinations.ai/ or a referrer. https://github.com/pollinations/pollinations/blob/master/APIDOCS.md#referrer-
ProviderOptionAPIKey is optional. Providing one, either via environment variable POLLINATIONS_API_KEY, will increase quota.
To use multiple models, create multiple clients. Models are listed at https://docs.perplexity.ai/guides/model-cards
Example (HTTP_record) ¶
package main
import (
"context"
"fmt"
"log"
"net/http"
"os"
"github.com/maruel/genai"
"github.com/maruel/genai/httprecord"
"github.com/maruel/genai/providers/pollinations"
"gopkg.in/dnaeon/go-vcr.v4/pkg/recorder"
)
func main() {
// Example to do HTTP recording and playback for smoke testing.
// The example recording is in testdata/example.yaml.
var rr *recorder.Recorder
defer func() {
// In a smoke test, use t.Cleanup().
if rr != nil {
if err := rr.Stop(); err != nil {
log.Printf("Failed saving recordings: %v", err)
}
}
}()
// Simple trick to force recording via an environment variable.
mode := recorder.ModeRecordOnce
if os.Getenv("RECORD") == "1" {
mode = recorder.ModeRecordOnly
}
wrapper := func(h http.RoundTripper) http.RoundTripper {
var err error
rr, err = httprecord.New("testdata/example", h, recorder.WithMode(mode))
if err != nil {
log.Fatal(err)
}
return rr
}
// Pollinations API works without auth but rejects invalid keys.
// Don't set a placeholder key for playback - leave empty to skip auth header.
ctx := context.Background()
c, err := pollinations.New(ctx, genai.ProviderOptionTransportWrapper(wrapper))
if err != nil {
log.Fatal(err)
}
models, err := c.ListModels(ctx)
if err != nil {
log.Fatal(err)
}
if len(models) > 1 {
fmt.Println("Found multiple models")
}
}
Output: Found multiple models
func (*Client) GenStream ¶
func (c *Client) GenStream(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (iter.Seq[genai.Reply], func() (genai.Result, error))
GenStream implements genai.Provider.
func (*Client) GenStreamRaw ¶
func (c *Client) GenStreamRaw(ctx context.Context, in *ChatRequest) (iter.Seq[ChatStreamChunkResponse], func() error)
GenStreamRaw provides access to the raw API.
func (*Client) GenSync ¶
func (c *Client) GenSync(ctx context.Context, msgs genai.Messages, opts ...genai.GenOption) (genai.Result, error)
GenSync implements genai.Provider.
func (*Client) GenSyncRaw ¶
func (c *Client) GenSyncRaw(ctx context.Context, in *ChatRequest, out *ChatResponse) error
GenSyncRaw provides access to the raw API.
func (*Client) HTTPClient ¶
HTTPClient returns the HTTP client to fetch results (e.g. videos) generated by the provider.
func (*Client) ListImageGenModels ¶
ListImageGenModels lists available image generation models.
func (*Client) ListModels ¶
ListModels implements genai.Provider.
func (*Client) ListTextModels ¶
ListTextModels lists available text models.
func (*Client) OutputModalities ¶
func (c *Client) OutputModalities() genai.Modalities
OutputModalities implements genai.Provider.
It returns the output modalities, i.e. what kind of output the model will generate (text, audio, image, video, etc).
func (*Client) Scoreboard ¶
func (c *Client) Scoreboard() scoreboard.Score
Scoreboard implements genai.Provider.
type CodeValue ¶
type CodeValue string
CodeValue handles fields that can be either a string or a number.
func (*CodeValue) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler.
type Content ¶
type Content struct {
Type ContentType `json:"type,omitzero"`
// Type == "text"
Text string `json:"text,omitzero"`
// Type == "image_url"
ImageURL struct {
URL string `json:"url,omitzero"` // URL or base64 encoded image
} `json:"image_url,omitzero"`
// Type == "input_audio"
InputAudio struct {
Data []byte `json:"data,omitzero"` // base64 encoded audio
Format string `json:"format,omitzero"` // "wav"
} `json:"input_audio,omitzero"`
}
Content is a provider-specific content block.
type ContentFilterResult ¶
type ContentFilterResult struct {
CustomBlocklists struct {
Filtered bool `json:"filtered"`
Details []struct {
BlocklistName string `json:"blocklist_name"`
} `json:"details"`
} `json:"custom_blocklists"`
Hate struct {
Filtered bool `json:"filtered"`
Severity string `json:"severity"` // "safe"
} `json:"hate"`
Jailbreak struct {
Filtered bool `json:"filtered"`
Detected bool `json:"detected"`
} `json:"jailbreak"`
ProtectedMaterialCode struct {
Filtered bool `json:"filtered"`
Detected bool `json:"detected"`
} `json:"protected_material_code"`
ProtectedMaterialText struct {
Filtered bool `json:"filtered"`
Detected bool `json:"detected"`
} `json:"protected_material_text"`
SelfHarm struct {
Filtered bool `json:"filtered"`
Severity string `json:"severity"`
} `json:"self_harm"`
Sexual struct {
Filtered bool `json:"filtered"`
Severity string `json:"severity"`
} `json:"sexual"`
Violence struct {
Filtered bool `json:"filtered"`
Severity string `json:"severity"`
} `json:"violence"`
}
ContentFilterResult is the result of content filtering.
type ContentType ¶
type ContentType string
ContentType is a provider-specific content type.
const ( ContentText ContentType = "text" ContentImageURL ContentType = "image_url" ContentAudio ContentType = "input_audio" )
Content type values.
type Contents ¶
type Contents []Content
Contents exists to marshal single content text block as a string.
func (*Contents) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
func (*Contents) UnmarshalJSON ¶
UnmarshalJSON implements custom unmarshalling for Contents type to handle cases where content could be a string or a raw JSON object.
type ErrorResponse ¶
type ErrorResponse struct {
Success bool `json:"success,omitzero"`
ErrorVal ErrorValue `json:"error"`
Status int64 `json:"status"`
Details struct {
Detail string `json:"detail"`
Error struct {
Message string `json:"message"`
Type string `json:"type"`
Param string `json:"param"`
Code CodeValue `json:"code"`
} `json:"error"`
Message string `json:"message"`
QueueInfo map[string]string `json:"queueInfo"`
Timestamp string `json:"timestamp"`
Provider string `json:"provider"`
Errors []struct {
Path []string `json:"path"`
Message string `json:"message"`
Code string `json:"code"`
UnionErrors []UnionError `json:"unionErrors"`
} `json:"errors"`
Success bool `json:"success,omitzero"`
Result struct{} `json:"result"`
Messages []struct{} `json:"messages"`
} `json:"details"`
Message string `json:"message"`
Debug struct{} `json:"debug"`
DeprecatedEndpoint string `json:"deprecated_endpoint,omitzero"`
NewEndpoint string `json:"new_endpoint,omitzero"`
Documentation string `json:"documentation,omitzero"`
TimingInfo []struct {
Step string `json:"step"`
Timestamp int64 `json:"timestamp"`
} `json:"timingInfo"`
RequestID string `json:"requestId"`
RequestParameters map[string]any `json:"requestParameters"`
}
ErrorResponse is the provider-specific error response.
func (*ErrorResponse) Error ¶
func (er *ErrorResponse) Error() string
func (*ErrorResponse) IsAPIError ¶
func (er *ErrorResponse) IsAPIError() bool
IsAPIError implements base.ErrorResponseI.
type ErrorValue ¶
type ErrorValue struct {
Message string `json:"message"`
Code CodeValue `json:"code"`
Timestamp string `json:"timestamp"`
}
ErrorValue handles the "error" field which can be either a string or an object.
func (*ErrorValue) String ¶
func (e *ErrorValue) String() string
func (*ErrorValue) UnmarshalJSON ¶
func (e *ErrorValue) UnmarshalJSON(b []byte) error
UnmarshalJSON implements json.Unmarshaler.
type FinishReason ¶
type FinishReason string
FinishReason is a provider-specific finish reason.
const ( FinishStop FinishReason = "stop" FinishLength FinishReason = "length" FinishToolCalls FinishReason = "tool_calls" )
Finish reason values.
func (FinishReason) ToFinishReason ¶
func (f FinishReason) ToFinishReason() genai.FinishReason
ToFinishReason converts to a genai.FinishReason.
type ImageModel ¶
type ImageModel struct {
Aliases Strings `json:"aliases"`
Description string `json:"description"`
InputModalities []string `json:"input_modalities"`
Name string `json:"name"`
OutputModalities []string `json:"output_modalities"`
PaidOnly bool `json:"paid_only"`
Pricing struct {
AudioInputPrice float64 `json:"audio_input_price,omitzero"`
AudioOutputPrice float64 `json:"audio_output_price,omitzero"`
AudioTokenPrice float64 `json:"audio_token_price,omitzero"`
CachedTokenPrice float64 `json:"cached_token_price,omitzero"`
CompletionAudioSeconds float64 `json:"completionAudioSeconds,omitzero"`
CompletionImageTokens float64 `json:"completionImageTokens,omitzero"`
CompletionVideoSeconds float64 `json:"completionVideoSeconds,omitzero"`
CompletionVideoTokens float64 `json:"completionVideoTokens,omitzero"`
Currency string `json:"currency"`
ImagePrice float64 `json:"image_price"`
InputTokenPrice float64 `json:"input_token_price,omitzero"`
OutputTokenPrice float64 `json:"output_token_price,omitzero"`
PromptCachedTokens float64 `json:"promptCachedTokens,omitzero"`
PromptImageTokens float64 `json:"promptImageTokens,omitzero"`
PromptTextTokens float64 `json:"promptTextTokens,omitzero"`
} `json:"pricing,omitzero"`
}
ImageModel is the provider-specific image model metadata.
func (*ImageModel) Inputs ¶
func (i *ImageModel) Inputs() []string
Inputs returns the supported input modalities.
func (*ImageModel) Outputs ¶
func (i *ImageModel) Outputs() []string
Outputs returns the supported output modalities.
func (*ImageModel) String ¶
func (i *ImageModel) String() string
type ImageModelsResponse ¶
type ImageModelsResponse []ImageModel
ImageModelsResponse is a list of image model metadata.
func (*ImageModelsResponse) ToModels ¶
func (r *ImageModelsResponse) ToModels() []genai.Model
ToModels converts to a slice of genai.Model.
type Message ¶
type Message struct {
Role string `json:"role"` // "system", "assistant", "user"
Content Contents `json:"content,omitzero"`
ToolCalls []ToolCall `json:"tool_calls,omitzero"`
ToolCallID string `json:"tool_call_id,omitzero"`
}
Message is a provider-specific message.
type MessageResponse ¶
type MessageResponse struct {
Role string `json:"role"`
ReasoningContent string `json:"reasoning_content"`
Content Contents `json:"content"`
ToolCalls []ToolCall `json:"tool_calls"`
Annotations []struct{} `json:"annotations"`
Refusal struct{} `json:"refusal"`
Audio struct {
Data []byte `json:"data"`
} `json:"audio"`
}
MessageResponse is a message in a provider-specific response.
type PromptFilterResult ¶
type PromptFilterResult struct {
PromptIndex int64 `json:"prompt_index"`
// One of the following is set.
ContentFilterResults ContentFilterResult `json:"content_filter_results"`
ContentFilterResult ContentFilterResult `json:"content_filter_result"`
}
PromptFilterResult is the result of content filtering on a prompt.
type ReasoningEffort ¶
type ReasoningEffort string
ReasoningEffort is the effort the model should put into reasoning. Default is Medium.
const ( ReasoningEffortLow ReasoningEffort = "low" ReasoningEffortMedium ReasoningEffort = "medium" ReasoningEffortHigh ReasoningEffort = "high" )
Reasoning effort values.
type Strings ¶
type Strings []string
Strings is generally a list of strings but can be a single string.
func (*Strings) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler.
type TextModel ¶
type TextModel struct {
Aliases Strings `json:"aliases"`
Audio bool `json:"audio"`
Community bool `json:"community"`
ContextWindow int64 `json:"context_window"`
Description string `json:"description"`
InputModalities []string `json:"input_modalities"` // "text", "image", "audio"
IsSpecialized bool `json:"is_specialized,omitzero"`
MaxInputChars int64 `json:"maxInputChars"`
Name string `json:"name"`
OriginalName string `json:"original_name"`
OutputModalities []string `json:"output_modalities"` // "text", "image", "audio"
PaidOnly bool `json:"paid_only"`
Pricing struct {
AudioInputPrice float64 `json:"audio_input_price,omitzero"`
AudioOutputPrice float64 `json:"audio_output_price,omitzero"`
AudioTokenPrice float64 `json:"audio_token_price,omitzero"`
CachedTokenPrice float64 `json:"cached_token_price,omitzero"`
CompletionAudioTokens float64 `json:"completionAudioTokens,omitzero"`
CompletionTextTokens float64 `json:"completionTextTokens,omitzero"`
CompletionTokens float64 `json:"completion_tokens,omitzero"`
Currency string `json:"currency,omitzero"`
InputTokenPrice float64 `json:"input_token_price,omitzero"`
OutputTokenPrice float64 `json:"output_token_price,omitzero"`
PromptAudioTokens float64 `json:"promptAudioTokens,omitzero"`
PromptCachedTokens float64 `json:"promptCachedTokens,omitzero"`
PromptTextTokens float64 `json:"promptTextTokens,omitzero"`
PromptTokens float64 `json:"prompt_tokens,omitzero"`
} `json:"pricing,omitzero"`
Provider string `json:"provider"` // "api.navy", "azure", "bedrock", "scaleway"
Reasoning bool `json:"reasoning"`
Search bool `json:"search"`
SupportsSystemMessages bool `json:"supportsSystemMessages"`
Tier string `json:"tier"` // "anonymous", "seed", "flower"
Tools bool `json:"tools"`
Uncensored bool `json:"uncensored"`
Vision bool `json:"vision"`
Voices []string `json:"voices"`
}
TextModel is the provider-specific text model metadata.
type TextModelsResponse ¶
type TextModelsResponse []TextModel
TextModelsResponse is a list of text model metadata.
func (*TextModelsResponse) ToModels ¶
func (r *TextModelsResponse) ToModels() []genai.Model
ToModels converts to a slice of genai.Model.
type Tool ¶
type Tool struct {
Type string `json:"type,omitzero"` // "function"
Function struct {
Name string `json:"name,omitzero"`
Description string `json:"description,omitzero"`
Parameters *jsonschema.Schema `json:"parameters,omitzero"`
} `json:"function,omitzero"`
}
Tool is a provider-specific tool definition.
type ToolCall ¶
type ToolCall struct {
Type string `json:"type,omitzero"` // "function"
ID string `json:"id,omitzero"`
Index int64 `json:"index,omitzero"`
Function struct {
Name string `json:"name,omitzero"`
Arguments string `json:"arguments,omitzero"`
} `json:"function,omitzero"`
}
ToolCall is a provider-specific tool call.
type UnionError ¶
type UnionError struct {
Issues []struct {
Code string `json:"code"`
Expected string `json:"expected"`
Received string `json:"received"`
Path []string `json:"path"`
Message string `json:"message"`
UnionErrors []UnionError `json:"unionErrors"`
} `json:"issues"`
Name string `json:"name"`
}
UnionError represents an error with multiple possible types.
type Usage ¶
type Usage struct {
PromptTokens int64 `json:"prompt_tokens"`
AudioPromptTokens int64 `json:"audio_prompt_tokens"`
CompletionTokens int64 `json:"completion_tokens"`
TotalTokens int64 `json:"total_tokens"`
CompletionTokensDetails struct {
AcceptedPredictionTokens int64 `json:"accepted_prediction_tokens"`
AudioTokens int64 `json:"audio_tokens"`
ReasoningTokens int64 `json:"reasoning_tokens"`
RejectedPredictionTokens int64 `json:"rejected_prediction_tokens"`
TextTokens int64 `json:"text_tokens"`
} `json:"completion_tokens_details"`
PromptTokensDetails struct {
AudioTokens int64 `json:"audio_tokens"`
CachedTokens int64 `json:"cached_tokens"`
ImageTokens int64 `json:"image_tokens"`
TextTokens int64 `json:"text_tokens"`
} `json:"prompt_tokens_details"`
}
Usage is the provider-specific token usage.