newapi

Documentation

Overview

Package newapi 对接 New API 文档中的大模型 HTTP 接口（图像 / 视频 / 语音等）。

BaseURL 可为网关 origin（https://host）或常见写法 https://host/v1；内部会规范为 origin， 再拼接绝对路径，以便同时支持 /v1/...、/kling/...、/jimeng/... 等。

通过 Config.Route 选择路径族（可灵、即梦、Sora、通义千问图、Gemini 等）；未指定时按 MediaKind 使用 OpenAI 兼容默认路由。 Config.DisableRemoteMediaFetch 为 true 时，图中 image_url/audio_url 不会发起 HTTP GET（降低 SSRF 风险）。

文档片段见仓库：other/new-api-docs-v1/openapi/generated/ai-model/ 下各子目录。

Index

• Variables
• func ConfigSchema() []engine.ConfigField
• func DefaultProvider() engine.Provider
• func DiscoverModels(ctx context.Context, baseURL, apiKey string) (map[string][]string, error)
• func InferFromModelName(model string) (Route, MediaKind, string)
• func LookupRoute(model string, capability string) (Route, MediaKind, string)
• func ModelInfos() []engine.ModelInfo
• func ModelsByCapability() map[string][]string
• type Config
• type Engine
  • func New(cfg Config) *Engine
  • func (e *Engine) Capabilities() engine.Capability
  • func (e *Engine) Execute(ctx context.Context, g workflow.Graph) (engine.Result, error)
  • func (e *Engine) Resume(ctx context.Context, remoteID string) (engine.Result, error)
• type MediaKind
• type ModelEntry
• type Route

Variables

var (
	ErrMissingPrompt  = errors.New("newapi: prompt not found in workflow graph")
	ErrMissingVoice   = errors.New("newapi: voice not found for speech (use AudioOptions.voice)")
	ErrMissingBaseURL = errors.New("newapi: BaseURL is empty (set Config.BaseURL or NEWAPI_BASE_URL)")

	ErrMissingImageSource  = errors.New("newapi: image source for edits not found in graph")
	ErrMissingAudioSource  = errors.New("newapi: audio source for whisper not found in graph")
	ErrMissingJimengReqKey = errors.New("newapi: jimeng req_key missing (graph input req_key / jimeng_req_key)")
	ErrRemoteMediaDisabled = errors.New("newapi: remote media URL fetch disabled (set DisableRemoteMediaFetch=false to allow image_url/audio_url)")
)

Functions

func ConfigSchema

func ConfigSchema() []engine.ConfigField

ConfigSchema returns the configuration fields required by the NewAPI engine.

func DefaultProvider

func DefaultProvider() engine.Provider

DefaultProvider returns preset engine configurations for newapi.

func DiscoverModels

func DiscoverModels(ctx context.Context, baseURL, apiKey string) (map[string][]string, error)

DiscoverModels calls GET /v1/models on the given gateway and returns models grouped by capability. For each model, capability is determined via:

1. The "capability" field in the API response (if the gateway provides it)
2. knownModels exact match
3. Model name pattern inference

Models that cannot be classified are placed under the "unknown" key.

func InferFromModelName

func InferFromModelName(model string) (Route, MediaKind, string)

InferFromModelName attempts to determine the capability, route, and kind from a model name using prefix/substring heuristics.

func LookupRoute

func LookupRoute(model string, capability string) (Route, MediaKind, string)

LookupRoute resolves the Route, MediaKind, and capability for a model using a three-tier decision chain:

1. knownModels exact match (highest priority)
2. Model name pattern inference (prefix/substring heuristics)
3. Capability fallback from EngineConfig.Capability

Returns (RouteAuto, "", "") when no tier matches — the caller must handle this.

func ModelInfos

func ModelInfos() []engine.ModelInfo

ModelInfos returns i18n metadata for all known NewAPI gateway models. Model names are prefixed with "newapi/" to avoid conflicts with native engine registrations.

func ModelsByCapability

func ModelsByCapability() map[string][]string

ModelsByCapability returns all known newapi models grouped by capability.

Types

type Config

type Config struct {
	APIKey  string
	BaseURL string // 网关 origin 或以 /v1 结尾的写法均可，见 NormalizeOrigin
	Model   string
	// Route 非空时优先；否则按 Kind 选择默认 OpenAI 路径族。
	Route Route
	Kind  MediaKind

	HTTPClient *http.Client
	// 图像
	Quality string
	Style   string
	// gpt-image-* 专属可选参数
	Background        string // transparent | opaque | auto
	OutputFormat      string // png | jpeg | webp
	Moderation        string // low | auto
	OutputCompression int    // 0-100, 仅 jpeg/webp 生效
	// 视频
	WaitForCompletion bool
	PollInterval      time.Duration
	// 即梦
	JimengVersion string // 查询参数 Version，默认 2022-08-31
	// DisableRemoteMediaFetch 为 true 时，图中 image_url/audio_url 不再发起 HTTP GET（降低 SSRF 风险；默认 false）。
	DisableRemoteMediaFetch bool
}

Config 配置 New API 引擎。

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine 实现 engine.Engine。

func New

func New(cfg Config) *Engine

New 创建引擎。Kind 为空且 Route 为空时，默认 KindImage。

func (*Engine) Capabilities

func (e *Engine) Capabilities() engine.Capability

Capabilities implements engine.Describer.

func (*Engine) Execute

func (e *Engine) Execute(ctx context.Context, g workflow.Graph) (engine.Result, error)

Execute 按 Route/Kind 调用对应 HTTP 接口。

func (*Engine) Resume

func (e *Engine) Resume(ctx context.Context, remoteID string) (engine.Result, error)

Resume implements engine.Resumer — resumes polling a previously submitted task. Jimeng route is not supported because polling requires a req_key that is only available at submission time.

type MediaKind

type MediaKind string

MediaKind 在未指定 Route 时选择默认 OpenAI 兼容族。

const (
	KindImage  MediaKind = "image"
	KindVideo  MediaKind = "video"
	KindSpeech MediaKind = "speech"
	KindVision MediaKind = "vision"
)

type ModelEntry

type ModelEntry struct {
	ID                     string   `json:"id"`
	Object                 string   `json:"object"`
	OwnedBy                string   `json:"owned_by,omitempty"`
	Capability             string   `json:"capability,omitempty"`
	SupportedEndpointTypes []string `json:"supported_endpoint_types,omitempty"`
}

ModelEntry represents a single model from the /v1/models response. Compatible with both standard OpenAI format and new-api extended format.

type Route

type Route string

Route 指定调用的网关路径族；为空时由 MediaKind 推导默认 OpenAI 兼容接口。

const (
	RouteAuto Route = ""

	// OpenAI 兼容（New API 统一路径）
	RouteOpenAIImagesGenerations Route = "openai_images_generations" // POST /v1/images/generations
	RouteOpenAIImagesEdits       Route = "openai_images_edits"       // POST /v1/images/edits (multipart)
	RouteOpenAIVideoGenerations  Route = "openai_video_generations"  // POST/GET /v1/video/generations
	RouteOpenAISpeech            Route = "openai_audio_speech"       // POST /v1/audio/speech
	RouteOpenAITranscriptions    Route = "openai_audio_transcriptions"
	RouteOpenAITranslations      Route = "openai_audio_translations"

	// 可灵 Kling
	RouteKlingText2Video  Route = "kling_text2video"
	RouteKlingImage2Video Route = "kling_image2video"

	// 即梦（火山系 Action+Version）
	RouteJimengVideo Route = "jimeng_video"

	// Sora（OpenAI 视频：multipart 创建 + 轮询 + /content 取流）
	RouteSoraVideos Route = "sora_v1_videos"

	// 通义千问图像（同路径 /v1/images/generations，请求体为 input.messages）
	RouteQwenImagesGenerations Route = "qwen_images_generations"

	// Gemini 原生 generateContent（图/音等）
	RouteGeminiGenerateContent Route = "gemini_generate_content"

	// OpenAI 兼容 chat completions（多模态理解：文本+图片+视频）
	RouteChatCompletions Route = "chat_completions"
)