feat(*): 插件中心与模型协议 - 完善声明式协议运行时并增加功能开放控制
This commit is contained in:
1 parent
70a6640ecf
commit
af41893678
106 files changed
+8816
-499
No files matched your search
@@ -0,0 +1,67 @@
|
||||
package protocol
|
||||
|
||||
import "context"
|
||||
|
||||
// Adapter owns only protocol translation. The host owns credentials, outbound
|
||||
// security, polling leases, billing, result downloads and task recovery.
|
||||
type Adapter interface {
|
||||
Metadata() Metadata
|
||||
BuildCreate(context.Context, RequestContext) (RequestSpec, error)
|
||||
ParseCreate(context.Context, []byte) (CreateResult, error)
|
||||
BuildPoll(context.Context, PollContext) (RequestSpec, error)
|
||||
ParsePoll(context.Context, PollContext, []byte) (PollResult, error)
|
||||
BuildCancel(context.Context, PollContext) (RequestSpec, error)
|
||||
}
|
||||
|
||||
// AgentAdapter is the optional protocol surface for tool-capable text calls.
|
||||
// The host still owns credentials, outbound policy and billing; a plugin only
|
||||
// maps the platform's agent request into the provider payload and parses the
|
||||
// provider response back into the platform tool-call contract.
|
||||
type AgentAdapter interface {
|
||||
BuildAgent(context.Context, AgentRequestContext) (RequestSpec, error)
|
||||
ParseAgent(context.Context, []byte) (AgentResult, error)
|
||||
}
|
||||
|
||||
type AgentRequestContext struct {
|
||||
BaseURL string
|
||||
Model string
|
||||
Request map[string]any
|
||||
}
|
||||
|
||||
type AgentToolCall struct {
|
||||
ID string
|
||||
Name string
|
||||
Arguments string
|
||||
}
|
||||
|
||||
type AgentResult struct {
|
||||
Text string
|
||||
Reasoning string
|
||||
ToolCalls []AgentToolCall
|
||||
}
|
||||
|
||||
type UnavailableAdapter struct {
|
||||
Info Metadata
|
||||
}
|
||||
|
||||
func (a UnavailableAdapter) Metadata() Metadata { return a.Info }
|
||||
|
||||
func (a UnavailableAdapter) BuildCreate(context.Context, RequestContext) (RequestSpec, error) {
|
||||
return RequestSpec{}, unavailable(a.Info)
|
||||
}
|
||||
|
||||
func (a UnavailableAdapter) ParseCreate(context.Context, []byte) (CreateResult, error) {
|
||||
return CreateResult{}, unavailable(a.Info)
|
||||
}
|
||||
|
||||
func (a UnavailableAdapter) BuildPoll(context.Context, PollContext) (RequestSpec, error) {
|
||||
return RequestSpec{}, unavailable(a.Info)
|
||||
}
|
||||
|
||||
func (a UnavailableAdapter) ParsePoll(context.Context, PollContext, []byte) (PollResult, error) {
|
||||
return PollResult{}, unavailable(a.Info)
|
||||
}
|
||||
|
||||
func (a UnavailableAdapter) BuildCancel(context.Context, PollContext) (RequestSpec, error) {
|
||||
return RequestSpec{}, unavailable(a.Info)
|
||||
}
|
||||
@@ -0,0 +1,876 @@
|
||||
package protocol
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"strconv"
|
||||
"strings"
|
||||
"sync"
|
||||
)
|
||||
|
||||
type builtinAdapter struct {
|
||||
info Metadata
|
||||
create func(GenerationRequest) (RequestSpec, error)
|
||||
parseCreate func(map[string]any) (CreateResult, error)
|
||||
poll func(PollContext) (RequestSpec, error)
|
||||
parsePoll func(PollContext, map[string]any) (PollResult, error)
|
||||
cancel func(PollContext) (RequestSpec, error)
|
||||
}
|
||||
|
||||
func (a builtinAdapter) Metadata() Metadata { return a.info }
|
||||
func (a builtinAdapter) BuildCreate(_ context.Context, c RequestContext) (RequestSpec, error) {
|
||||
if a.create == nil {
|
||||
return RequestSpec{}, unavailable(a.info)
|
||||
}
|
||||
return a.create(c.Request)
|
||||
}
|
||||
func (a builtinAdapter) ParseCreate(_ context.Context, body []byte) (CreateResult, error) {
|
||||
if a.parseCreate == nil {
|
||||
return CreateResult{}, unavailable(a.info)
|
||||
}
|
||||
payload, err := decodeObject(body)
|
||||
if err != nil {
|
||||
return CreateResult{}, err
|
||||
}
|
||||
return a.parseCreate(payload)
|
||||
}
|
||||
func (a builtinAdapter) BuildPoll(_ context.Context, c PollContext) (RequestSpec, error) {
|
||||
if a.poll == nil {
|
||||
return RequestSpec{}, unavailable(a.info)
|
||||
}
|
||||
return a.poll(c)
|
||||
}
|
||||
func (a builtinAdapter) ParsePoll(_ context.Context, c PollContext, body []byte) (PollResult, error) {
|
||||
if a.parsePoll == nil {
|
||||
return PollResult{}, unavailable(a.info)
|
||||
}
|
||||
payload, err := decodeObject(body)
|
||||
if err != nil {
|
||||
return PollResult{}, err
|
||||
}
|
||||
return a.parsePoll(c, payload)
|
||||
}
|
||||
func (a builtinAdapter) BuildCancel(_ context.Context, c PollContext) (RequestSpec, error) {
|
||||
if a.cancel == nil {
|
||||
return RequestSpec{}, fmt.Errorf("protocol %s does not support cancellation", a.info.ID)
|
||||
}
|
||||
return a.cancel(c)
|
||||
}
|
||||
|
||||
var builtinRegistry *Registry
|
||||
var builtinRegistryMu sync.Mutex
|
||||
|
||||
// Builtins returns the immutable process-wide registry of shipped protocol plugins.
|
||||
// The registry itself is safe for reads and can be extended by an installer during startup.
|
||||
func Builtins() *Registry {
|
||||
builtinRegistryMu.Lock()
|
||||
defer builtinRegistryMu.Unlock()
|
||||
if builtinRegistry != nil {
|
||||
return builtinRegistry
|
||||
}
|
||||
registry, err := NewRegistry(
|
||||
openAIChatAdapter(), openAIResponsesAdapter(), claudeAdapter(),
|
||||
openAIImagesAdapter(), grokImagesAdapter(), arkImagesAdapter(), jimengImagesAdapter(), geminiImagesAdapter(),
|
||||
openAIVideosAdapter(), newAPIChannel1Adapter(), newAPIVideosAdapter(), xAIVideosAdapter(), arkVideosAdapter(), jimengVideosAdapter(), geminiVeoAdapter(), novitaVideosAdapter(), miniMaxVideosAdapter(),
|
||||
openAIAudioAdapter(), asyncAudioAdapter(), agnesAdapter(),
|
||||
)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
builtinRegistry = registry
|
||||
return registry
|
||||
}
|
||||
|
||||
func allSurfaces() []Surface {
|
||||
return []Surface{SurfaceAdminSystemChannel, SurfaceUserCustomChannel, SurfaceCanvas, SurfaceCreation, SurfaceAgent}
|
||||
}
|
||||
|
||||
func metadata(id, name, vendor string, capability Capability, create, poll, contentType string) Metadata {
|
||||
return Metadata{ID: id, Version: "1.0.0", Name: name, Vendor: vendor, Categories: []Capability{capability}, Scopes: allSurfaces(), Create: create, Poll: poll, ContentType: contentType, Enabled: true, Installable: true}
|
||||
}
|
||||
|
||||
func mediaParams() []Parameter {
|
||||
return []Parameter{{Name: "model", Type: "string", Required: true, Mapping: "model"}, {Name: "prompt", Type: "string", Required: true, Mapping: "prompt"}, {Name: "images", Type: "media[]", Mapping: "provider-specific"}, {Name: "imageCount", Type: "integer", Mapping: "provider-specific"}, {Name: "aspectRatio", Type: "string", Mapping: "provider-specific"}, {Name: "resolution", Type: "string", Mapping: "provider-specific"}, {Name: "quality", Type: "string", Mapping: "provider-specific"}}
|
||||
}
|
||||
|
||||
func videoParams() []Parameter {
|
||||
return []Parameter{
|
||||
{Name: "model", Type: "string", Required: true, Mapping: "model", Description: "上游模型标识。"},
|
||||
{Name: "prompt", Type: "string", Required: true, Mapping: "prompt", Description: "视频生成提示词。"},
|
||||
{Name: "images", Type: "media[]", Mapping: "provider-specific", Description: "参考图片,由协议适配器转换为上游要求的 URL、Data URL 或 multipart 文件。"},
|
||||
{Name: "videos", Type: "media[]", Mapping: "provider-specific", Description: "参考视频;仅在上游协议支持时发送。"},
|
||||
{Name: "audios", Type: "media[]", Mapping: "provider-specific", Description: "参考音频或声音;仅在上游协议支持时发送。"},
|
||||
{Name: "duration", Type: "integer", Mapping: "provider-specific", Description: "视频时长,单位由上游协议决定。"},
|
||||
{Name: "aspectRatio", Type: "string", Mapping: "provider-specific", Description: "画幅比例或上游尺寸字段。"},
|
||||
{Name: "resolution", Type: "string", Mapping: "provider-specific", Description: "输出分辨率档位。"},
|
||||
{Name: "generateAudio", Type: "boolean", Mapping: "provider-specific", Description: "是否同时生成音频。"},
|
||||
{Name: "watermark", Type: "boolean", Mapping: "provider-specific", Description: "是否添加水印。"},
|
||||
}
|
||||
}
|
||||
|
||||
func openAIChatAdapter() Adapter {
|
||||
info := metadata("chat-completion", "OpenAI Chat Completions", "OpenAI", CapabilityText, "POST /v1/chat/completions", "", "application/json")
|
||||
info.Parameters = []Parameter{
|
||||
{Name: "model", Type: "string", Required: true, Mapping: "model", Description: "上游模型标识。"},
|
||||
{Name: "prompt", Type: "string", Required: true, Mapping: "messages[0].content", Description: "默认转换为一条 user message;extra.messages 可替换完整消息数组。"},
|
||||
{Name: "stream", Type: "boolean", Mapping: "stream", Description: "是否请求流式响应。"},
|
||||
}
|
||||
return builtinAdapter{info: info,
|
||||
create: func(r GenerationRequest) (RequestSpec, error) {
|
||||
body := map[string]any{"model": r.Model, "messages": []any{map[string]any{"role": "user", "content": r.Prompt}}}
|
||||
mergeExtra(body, r.Extra, "messages", "temperature", "top_p", "max_tokens", "stream", "tools", "response_format")
|
||||
return jsonSpec(http.MethodPost, "/v1/chat/completions", body), nil
|
||||
},
|
||||
parseCreate: parseChatResponse,
|
||||
}
|
||||
}
|
||||
|
||||
func openAIResponsesAdapter() Adapter {
|
||||
info := metadata("openai-response", "OpenAI Responses", "OpenAI", CapabilityText, "POST /v1/responses", "", "application/json")
|
||||
info.Parameters = []Parameter{
|
||||
{Name: "model", Type: "string", Required: true, Mapping: "model", Description: "上游模型标识。"},
|
||||
{Name: "prompt", Type: "string", Required: true, Mapping: "input", Description: "默认作为 input 字符串;extra.input 可提供结构化输入。"},
|
||||
{Name: "stream", Type: "boolean", Mapping: "stream", Description: "是否请求流式响应。"},
|
||||
}
|
||||
return builtinAdapter{info: info,
|
||||
create: func(r GenerationRequest) (RequestSpec, error) {
|
||||
input := any(r.Prompt)
|
||||
body := map[string]any{"model": r.Model, "input": input}
|
||||
mergeExtra(body, r.Extra, "input", "instructions", "temperature", "top_p", "max_output_tokens", "stream", "tools", "text")
|
||||
return jsonSpec(http.MethodPost, "/v1/responses", body), nil
|
||||
},
|
||||
parseCreate: parseResponsesResponse,
|
||||
}
|
||||
}
|
||||
|
||||
func claudeAdapter() Adapter {
|
||||
info := metadata("claude-api", "Claude API", "Anthropic", CapabilityText, "POST /v1/messages", "", "application/json")
|
||||
info.Parameters = []Parameter{
|
||||
{Name: "model", Type: "string", Required: true, Mapping: "model", Description: "Anthropic 模型标识。"},
|
||||
{Name: "prompt", Type: "string", Required: true, Mapping: "messages[0].content", Description: "默认转换为一条 user message;extra.messages 可替换完整消息数组。"},
|
||||
{Name: "stream", Type: "boolean", Mapping: "stream", Description: "是否请求流式响应。"},
|
||||
}
|
||||
info.LegacyAliases = []string{"anthropic-messages", "claude-messages"}
|
||||
return builtinAdapter{info: info,
|
||||
create: func(r GenerationRequest) (RequestSpec, error) {
|
||||
body := map[string]any{"model": r.Model, "max_tokens": 4096, "messages": []any{map[string]any{"role": "user", "content": r.Prompt}}}
|
||||
mergeExtra(body, r.Extra, "max_tokens", "system", "messages", "temperature", "top_p", "top_k", "tools", "tool_choice", "stream")
|
||||
spec := jsonSpec(http.MethodPost, "/v1/messages", body)
|
||||
spec.Headers = map[string]string{"anthropic-version": "2023-06-01"}
|
||||
return spec, nil
|
||||
},
|
||||
parseCreate: parseClaudeResponse,
|
||||
}
|
||||
}
|
||||
|
||||
func openAIImagesAdapter() Adapter {
|
||||
info := metadata("openai-image", "OpenAI Images", "OpenAI", CapabilityImage, "POST /v1/images/generations", "", "application/json or multipart/form-data")
|
||||
info.Parameters = mediaParams()
|
||||
return builtinAdapter{info: info,
|
||||
create: func(r GenerationRequest) (RequestSpec, error) {
|
||||
body := map[string]any{"model": r.Model, "prompt": r.Prompt}
|
||||
if r.ImageCount > 0 {
|
||||
body["n"] = r.ImageCount
|
||||
}
|
||||
copyIf(body, "size", r.AspectRatio)
|
||||
copyIf(body, "quality", r.Quality)
|
||||
mergeExtra(body, r.Extra, "size", "quality", "background", "response_format", "output_format", "style", "n")
|
||||
return jsonSpec(http.MethodPost, "/v1/images/generations", body), nil
|
||||
},
|
||||
parseCreate: parseImageResponse,
|
||||
}
|
||||
}
|
||||
|
||||
func grokImagesAdapter() Adapter {
|
||||
info := metadata("grok-image", "Grok Images", "xAI", CapabilityImage, "POST /v1/images/generations", "", "application/json")
|
||||
info.Parameters = mediaParams()
|
||||
return builtinAdapter{info: info,
|
||||
create: func(r GenerationRequest) (RequestSpec, error) {
|
||||
body := map[string]any{"model": r.Model, "prompt": r.Prompt, "aspect_ratio": defaultValue(r.AspectRatio, "1:1"), "resolution": defaultValue(r.Quality, "2k")}
|
||||
if len(r.Images) > 0 {
|
||||
body["image"] = mediaValue(r.Images[0])
|
||||
}
|
||||
return jsonSpec(http.MethodPost, "/v1/images/generations", body), nil
|
||||
},
|
||||
parseCreate: parseImageResponse,
|
||||
}
|
||||
}
|
||||
|
||||
func arkImagesAdapter() Adapter {
|
||||
info := metadata("volcengine-ark-image", "火山方舟图片", "Volcengine Ark", CapabilityImage, "POST /api/v3/images/generations", "", "application/json")
|
||||
info.Parameters = mediaParams()
|
||||
return builtinAdapter{info: info,
|
||||
create: func(r GenerationRequest) (RequestSpec, error) {
|
||||
body := map[string]any{"model": r.Model, "prompt": r.Prompt}
|
||||
if size := strings.TrimSpace(r.AspectRatio); size != "" {
|
||||
body["size"] = size
|
||||
}
|
||||
if len(r.Images) > 0 {
|
||||
body["image"] = mediaValues(r.Images)
|
||||
}
|
||||
mergeExtra(body, r.Extra, "size", "sequential_image_generation", "sequential_image_generation_options", "watermark")
|
||||
return jsonSpec(http.MethodPost, "/api/v3/images/generations", body), nil
|
||||
},
|
||||
parseCreate: parseImageResponse,
|
||||
}
|
||||
}
|
||||
|
||||
func jimengImagesAdapter() Adapter {
|
||||
info := metadata("volcengine-jimeng-image", "即梦官方图片", "Volcengine Jimeng", CapabilityImage, "POST CVSync2AsyncSubmitTask", "POST CVSync2AsyncGetResult", "application/json + AK/SK signature")
|
||||
info.Parameters = mediaParams()
|
||||
return builtinAdapter{info: info,
|
||||
create: func(r GenerationRequest) (RequestSpec, error) {
|
||||
body := map[string]any{"req_key": r.Model, "prompt": r.Prompt}
|
||||
if len(r.Images) > 0 {
|
||||
body["image_urls"] = mediaValues(r.Images)
|
||||
}
|
||||
mergeExtra(body, r.Extra, "req_key", "prompt", "image_urls", "seed", "width", "height")
|
||||
return jsonSpec(http.MethodPost, "/CVSync2AsyncSubmitTask", body), nil
|
||||
},
|
||||
parseCreate: parseJiMengCreate,
|
||||
poll: func(c PollContext) (RequestSpec, error) {
|
||||
return jsonSpec(http.MethodPost, "/CVSync2AsyncGetResult", map[string]any{"req_key": c.Model, "task_id": c.TaskID}), nil
|
||||
},
|
||||
parsePoll: parseJiMengPoll,
|
||||
}
|
||||
}
|
||||
|
||||
func geminiImagesAdapter() Adapter {
|
||||
info := metadata("gemini-image", "Gemini Images", "Google", CapabilityImage, "POST /v1beta/models/{model}:generateContent", "", "application/json")
|
||||
info.Parameters = mediaParams()
|
||||
return builtinAdapter{info: info,
|
||||
create: func(r GenerationRequest) (RequestSpec, error) {
|
||||
parts := []any{map[string]any{"text": r.Prompt}}
|
||||
for _, image := range r.Images {
|
||||
if image.DataURL != "" {
|
||||
parts = append(parts, map[string]any{"inline_data": map[string]any{"mime_type": dataMIME(image.DataURL), "data": dataPayload(image.DataURL)}})
|
||||
} else if image.URL != "" {
|
||||
parts = append(parts, map[string]any{"file_data": map[string]any{"file_uri": image.URL}})
|
||||
}
|
||||
}
|
||||
body := map[string]any{"contents": []any{map[string]any{"role": "user", "parts": parts}}}
|
||||
if r.AspectRatio != "" || r.Quality != "" {
|
||||
body["generationConfig"] = map[string]any{"imageConfig": compactMap(map[string]any{"aspectRatio": r.AspectRatio, "imageSize": r.Quality})}
|
||||
}
|
||||
mergeExtra(body, r.Extra, "generationConfig", "safetySettings", "systemInstruction")
|
||||
return jsonSpec(http.MethodPost, "/v1beta/models/"+url.PathEscape(r.Model)+":generateContent", body), nil
|
||||
},
|
||||
parseCreate: parseGeminiImageResponse,
|
||||
}
|
||||
}
|
||||
|
||||
func openAIVideosAdapter() Adapter {
|
||||
info := metadata("newapi", "OpenAI Videos", "OpenAI compatible", CapabilityVideo, "POST /v1/videos", "GET /v1/videos/{task_id}", "multipart/form-data")
|
||||
info.LegacyAliases = []string{"openai-video", "openai-videos"}
|
||||
info.Parameters = openAIVideoParams()
|
||||
return videoAdapter(info, func(r GenerationRequest) (RequestSpec, error) {
|
||||
body := map[string]any{"model": r.Model, "prompt": r.Prompt}
|
||||
if r.Duration > 0 {
|
||||
body["seconds"] = strconv.Itoa(r.Duration)
|
||||
}
|
||||
if r.AspectRatio != "" {
|
||||
body["size"] = r.AspectRatio
|
||||
}
|
||||
if len(r.Images) > 0 {
|
||||
body["input_reference"] = mediaValues(r.Images)
|
||||
}
|
||||
return RequestSpec{Method: http.MethodPost, Path: "/v1/videos", ContentType: "multipart/form-data", Body: body}, nil
|
||||
})
|
||||
}
|
||||
|
||||
func openAIVideoParams() []Parameter {
|
||||
return []Parameter{
|
||||
{Name: "model", Type: "string", Required: true, Mapping: "model", Description: "Sora 等视频模型标识。"},
|
||||
{Name: "prompt", Type: "string", Required: true, Mapping: "prompt", Description: "视频生成提示词。"},
|
||||
{Name: "images", Type: "media[]", Mapping: "input_reference", Description: "可选参考图,作为 multipart 文件上传到 input_reference。"},
|
||||
{Name: "duration", Type: "integer", Mapping: "seconds", Description: "视频时长,单位为秒。"},
|
||||
{Name: "aspectRatio", Type: "string", Mapping: "size", Description: "视频尺寸,例如 1280x720;该协议使用 size 而不是独立的 aspect_ratio。"},
|
||||
{Name: "videos", Type: "media[]", Mapping: "unsupported", Description: "OpenAI Videos 当前适配器不发送参考视频。"},
|
||||
{Name: "audios", Type: "media[]", Mapping: "unsupported", Description: "OpenAI Videos 当前适配器不发送参考音频。"},
|
||||
{Name: "resolution", Type: "string", Mapping: "unsupported", Description: "分辨率通过 size 表达。"},
|
||||
{Name: "generateAudio", Type: "boolean", Mapping: "unsupported", Description: "当前适配器不额外发送该字段。"},
|
||||
{Name: "watermark", Type: "boolean", Mapping: "unsupported", Description: "当前适配器不额外发送该字段。"},
|
||||
}
|
||||
}
|
||||
|
||||
func newAPIVideosAdapter() Adapter {
|
||||
info := metadata("newapi-channel-2", "NewAPI Video Generations", "NewAPI", CapabilityVideo, "POST /v1/video/generations", "GET /v1/video/generations/{task_id}", "application/json")
|
||||
info.LegacyAliases = []string{"newapi-video-generations"}
|
||||
info.Parameters = videoParams()
|
||||
return videoAdapter(info, func(r GenerationRequest) (RequestSpec, error) {
|
||||
body := map[string]any{"model": r.Model, "prompt": r.Prompt, "seconds": strconv.Itoa(defaultInt(r.Duration, 6)), "aspect_ratio": defaultValue(r.AspectRatio, "16:9")}
|
||||
copyIf(body, "resolution", r.Resolution)
|
||||
if r.GenerateAudio {
|
||||
body["generate_audio"] = true
|
||||
}
|
||||
if len(r.Images) > 0 {
|
||||
body["image_urls"] = mediaValues(r.Images)
|
||||
}
|
||||
if len(r.Videos) > 0 {
|
||||
body["video_urls"] = mediaValues(r.Videos)
|
||||
}
|
||||
if len(r.Audios) > 0 {
|
||||
body["audio_urls"] = mediaValues(r.Audios)
|
||||
}
|
||||
return jsonSpec(http.MethodPost, "/v1/video/generations", body), nil
|
||||
})
|
||||
}
|
||||
|
||||
func newAPIChannel1Adapter() Adapter {
|
||||
info := metadata("newapi-channel-1", "NewAPI 媒体任务", "NewAPI", CapabilityVideo, "POST /v1/videos", "GET /v1/videos/{task_id}", "application/json")
|
||||
info.Parameters = videoParams()
|
||||
return videoAdapter(info, func(r GenerationRequest) (RequestSpec, error) {
|
||||
media := make([]map[string]string, 0, len(r.Images)+len(r.Videos)+len(r.Audios))
|
||||
for _, image := range r.Images {
|
||||
media = append(media, map[string]string{"type": "reference_image", "url": mediaValue(image)})
|
||||
}
|
||||
for _, video := range r.Videos {
|
||||
media = append(media, map[string]string{"type": "reference_video", "url": mediaValue(video)})
|
||||
}
|
||||
for _, audio := range r.Audios {
|
||||
media = append(media, map[string]string{"type": "reference_voice", "url": mediaValue(audio)})
|
||||
}
|
||||
input := map[string]any{"prompt": r.Prompt}
|
||||
if len(media) > 0 {
|
||||
input["media"] = media
|
||||
}
|
||||
parameters := map[string]any{"resolution": defaultValue(r.Resolution, "720P"), "ratio": defaultValue(r.AspectRatio, "16:9"), "duration": defaultInt(r.Duration, 5)}
|
||||
if r.Watermark {
|
||||
parameters["watermark"] = true
|
||||
}
|
||||
return jsonSpec(http.MethodPost, "/v1/videos", map[string]any{"model": r.Model, "input": input, "parameters": parameters}), nil
|
||||
})
|
||||
}
|
||||
|
||||
func xAIVideosAdapter() Adapter {
|
||||
info := metadata("xai-video", "xAI 官方视频", "xAI", CapabilityVideo, "POST /v1/videos/generations", "GET /v1/videos/{request_id}", "application/json")
|
||||
info.Parameters = videoParams()
|
||||
return videoAdapter(info, func(r GenerationRequest) (RequestSpec, error) {
|
||||
body := map[string]any{"model": r.Model, "prompt": r.Prompt, "duration": defaultInt(r.Duration, 6), "aspect_ratio": defaultValue(r.AspectRatio, "16:9"), "resolution": defaultValue(r.Resolution, "720p")}
|
||||
if len(r.Images) == 1 {
|
||||
body["image"] = map[string]any{"url": mediaValue(r.Images[0])}
|
||||
} else if len(r.Images) > 1 {
|
||||
refs := make([]any, 0, len(r.Images))
|
||||
for _, image := range r.Images {
|
||||
refs = append(refs, map[string]any{"url": mediaValue(image)})
|
||||
}
|
||||
body["reference_images"] = refs
|
||||
}
|
||||
return jsonSpec(http.MethodPost, "/v1/videos/generations", body), nil
|
||||
})
|
||||
}
|
||||
|
||||
func arkVideosAdapter() Adapter {
|
||||
info := metadata("volcengine-ark-video", "火山方舟视频", "Volcengine Ark", CapabilityVideo, "POST /api/v3/contents/generations/tasks", "GET /api/v3/contents/generations/tasks/{task_id}", "application/json")
|
||||
info.Parameters = videoParams()
|
||||
return videoAdapter(info, func(r GenerationRequest) (RequestSpec, error) {
|
||||
content := []any{map[string]any{"type": "text", "text": r.Prompt}}
|
||||
for _, image := range r.Images {
|
||||
content = append(content, map[string]any{"type": "image_url", "image_url": map[string]any{"url": mediaValue(image)}, "role": "reference_image"})
|
||||
}
|
||||
body := map[string]any{"model": r.Model, "content": content, "ratio": defaultValue(r.AspectRatio, "16:9"), "resolution": defaultValue(r.Resolution, "720p"), "duration": defaultInt(r.Duration, 5)}
|
||||
if r.GenerateAudio {
|
||||
body["generate_audio"] = true
|
||||
}
|
||||
if r.Watermark {
|
||||
body["watermark"] = true
|
||||
}
|
||||
return jsonSpec(http.MethodPost, "/api/v3/contents/generations/tasks", body), nil
|
||||
})
|
||||
}
|
||||
|
||||
func jimengVideosAdapter() Adapter {
|
||||
info := metadata("volcengine-jimeng-video", "即梦官方视频", "Volcengine Jimeng", CapabilityVideo, "POST CVSync2AsyncSubmitTask", "POST CVSync2AsyncGetResult", "application/json + AK/SK signature")
|
||||
info.Parameters = videoParams()
|
||||
return videoAdapterWithPoll(info, func(r GenerationRequest) (RequestSpec, error) {
|
||||
body := map[string]any{"req_key": r.Model, "prompt": r.Prompt}
|
||||
if len(r.Images) > 0 {
|
||||
body["image_urls"] = mediaValues(r.Images)
|
||||
}
|
||||
mergeExtra(body, r.Extra, "req_key", "prompt", "image_urls", "duration", "ratio", "resolution")
|
||||
return jsonSpec(http.MethodPost, "/CVSync2AsyncSubmitTask", body), nil
|
||||
}, func(c PollContext) (RequestSpec, error) {
|
||||
return jsonSpec(http.MethodPost, "/CVSync2AsyncGetResult", map[string]any{"req_key": c.Model, "task_id": c.TaskID}), nil
|
||||
})
|
||||
}
|
||||
|
||||
func geminiVeoAdapter() Adapter {
|
||||
info := metadata("gemini-veo", "Gemini Veo", "Google", CapabilityVideo, "POST /v1beta/models/{model}:predictLongRunning", "GET /v1beta/{operation_name}", "application/json")
|
||||
info.Parameters = videoParams()
|
||||
create := func(r GenerationRequest) (RequestSpec, error) {
|
||||
instance := map[string]any{"prompt": r.Prompt}
|
||||
if len(r.Images) > 0 {
|
||||
image := r.Images[0]
|
||||
instance["image"] = map[string]any{"inlineData": map[string]any{"mimeType": dataMIME(image.DataURL), "data": dataPayload(image.DataURL)}}
|
||||
}
|
||||
body := map[string]any{"instances": []any{instance}, "parameters": compactMap(map[string]any{"aspectRatio": r.AspectRatio, "durationSeconds": r.Duration, "resolution": r.Resolution, "generateAudio": r.GenerateAudio})}
|
||||
return jsonSpec(http.MethodPost, "/v1beta/models/"+url.PathEscape(r.Model)+":predictLongRunning", body), nil
|
||||
}
|
||||
poll := func(c PollContext) (RequestSpec, error) {
|
||||
operation := strings.TrimPrefix(c.TaskID, "/")
|
||||
if !strings.HasPrefix(operation, "operations/") {
|
||||
operation = "operations/" + operation
|
||||
}
|
||||
return RequestSpec{Method: http.MethodGet, Path: "/v1beta/" + operation}, nil
|
||||
}
|
||||
return builtinAdapter{info: info, create: create, parseCreate: parseGeminiVeoCreate, poll: poll, parsePoll: parseGeminiVeoPoll}
|
||||
}
|
||||
|
||||
func novitaVideosAdapter() Adapter {
|
||||
info := metadata("novita-video", "Novita 视频", "Novita", CapabilityVideo, "POST /v3/video/create", "GET /v3/async/task-result?task_id={id}", "application/json")
|
||||
info.Parameters = videoParams()
|
||||
return videoAdapter(info, func(r GenerationRequest) (RequestSpec, error) {
|
||||
body := map[string]any{"model_name": r.Model, "prompt": r.Prompt, "duration": defaultInt(r.Duration, 5), "aspect_ratio": defaultValue(r.AspectRatio, "16:9")}
|
||||
if len(r.Images) > 0 {
|
||||
body["image_url"] = mediaValue(r.Images[0])
|
||||
}
|
||||
return jsonSpec(http.MethodPost, "/v3/video/create", body), nil
|
||||
})
|
||||
}
|
||||
|
||||
func miniMaxVideosAdapter() Adapter {
|
||||
info := metadata("minimax-video", "MiniMax 视频", "MiniMax", CapabilityVideo, "POST /v2/video_generation", "GET /v2/query/video_generation/{task_id}", "application/json")
|
||||
info.Parameters = videoParams()
|
||||
return videoAdapter(info, func(r GenerationRequest) (RequestSpec, error) {
|
||||
content := []any{map[string]any{"type": "text", "text": r.Prompt}}
|
||||
for _, image := range r.Images {
|
||||
content = append(content, map[string]any{"type": "image_url", "image_url": map[string]any{"url": mediaValue(image)}, "role": "reference_image"})
|
||||
}
|
||||
body := map[string]any{"model": r.Model, "prompt": r.Prompt, "duration": defaultInt(r.Duration, 6), "content": content}
|
||||
mergeExtra(body, r.Extra, "model", "prompt", "duration", "content", "resolution", "aspect_ratio")
|
||||
return jsonSpec(http.MethodPost, "/v2/video_generation", body), nil
|
||||
})
|
||||
}
|
||||
|
||||
func openAIAudioAdapter() Adapter {
|
||||
info := metadata("openai-audio", "OpenAI Audio", "OpenAI", CapabilityAudio, "POST /v1/audio/speech", "", "application/json")
|
||||
return builtinAdapter{info: info, create: func(r GenerationRequest) (RequestSpec, error) {
|
||||
return jsonSpec(http.MethodPost, "/v1/audio/speech", map[string]any{"model": r.Model, "input": r.Prompt}), nil
|
||||
}, parseCreate: parseAudioResponse}
|
||||
}
|
||||
|
||||
func asyncAudioAdapter() Adapter {
|
||||
info := metadata("async-audio", "异步音频任务", "OpenAI compatible", CapabilityAudio, "POST /v1/audio/tasks", "GET /v1/audio/tasks/{task_id}", "application/json")
|
||||
return asyncMediaAdapter(info, CapabilityAudio, func(r GenerationRequest) (RequestSpec, error) {
|
||||
return jsonSpec(http.MethodPost, "/v1/audio/tasks", map[string]any{"model": r.Model, "prompt": r.Prompt}), nil
|
||||
})
|
||||
}
|
||||
|
||||
func agnesAdapter() Adapter {
|
||||
info := metadata("agnes-video", "Agnes", "Agnes", CapabilityVideo, "", "", "")
|
||||
info.Enabled = false
|
||||
info.Installable = false
|
||||
info.UnavailableReason = "未提供可验证的官方请求、鉴权、轮询和响应协议资料"
|
||||
return UnavailableAdapter{Info: info}
|
||||
}
|
||||
|
||||
func videoAdapter(info Metadata, create func(GenerationRequest) (RequestSpec, error)) Adapter {
|
||||
return asyncMediaAdapterWithPoll(info, CapabilityVideo, create, func(c PollContext) (RequestSpec, error) {
|
||||
path := strings.TrimSpace(info.Poll)
|
||||
if index := strings.IndexByte(path, ' '); index > 0 {
|
||||
path = strings.TrimSpace(path[index+1:])
|
||||
}
|
||||
path = strings.Replace(path, "{task_id}", url.PathEscape(c.TaskID), 1)
|
||||
path = strings.Replace(path, "{request_id}", url.PathEscape(c.TaskID), 1)
|
||||
path = strings.Replace(path, "{id}", url.QueryEscape(c.TaskID), 1)
|
||||
return RequestSpec{Method: http.MethodGet, Path: path}, nil
|
||||
})
|
||||
}
|
||||
|
||||
func videoAdapterWithPoll(info Metadata, create func(GenerationRequest) (RequestSpec, error), poll func(PollContext) (RequestSpec, error)) Adapter {
|
||||
return asyncMediaAdapterWithPoll(info, CapabilityVideo, create, poll)
|
||||
|
||||
}
|
||||
|
||||
func asyncMediaAdapter(info Metadata, capability Capability, create func(GenerationRequest) (RequestSpec, error)) Adapter {
|
||||
return asyncMediaAdapterWithPoll(info, capability, create, func(c PollContext) (RequestSpec, error) {
|
||||
path := strings.TrimSpace(info.Poll)
|
||||
if index := strings.IndexByte(path, ' '); index > 0 {
|
||||
path = strings.TrimSpace(path[index+1:])
|
||||
}
|
||||
path = strings.Replace(path, "{task_id}", url.PathEscape(c.TaskID), 1)
|
||||
return RequestSpec{Method: http.MethodGet, Path: path}, nil
|
||||
})
|
||||
}
|
||||
|
||||
func asyncMediaAdapterWithPoll(info Metadata, capability Capability, create func(GenerationRequest) (RequestSpec, error), poll func(PollContext) (RequestSpec, error)) Adapter {
|
||||
return builtinAdapter{
|
||||
info: info, create: create, parseCreate: parseAsyncCreate, poll: poll,
|
||||
parsePoll: func(c PollContext, payload map[string]any) (PollResult, error) {
|
||||
return parseAsyncMediaPoll(c, payload, capability)
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
func jsonSpec(method, path string, body any) RequestSpec {
|
||||
return RequestSpec{Method: method, Path: path, ContentType: "application/json", Body: body}
|
||||
}
|
||||
|
||||
func parseChatResponse(payload map[string]any) (CreateResult, error) {
|
||||
choices, _ := payload["choices"].([]any)
|
||||
if len(choices) == 0 {
|
||||
return CreateResult{}, fmt.Errorf("chat response has no choices")
|
||||
}
|
||||
choice, _ := choices[0].(map[string]any)
|
||||
message, _ := choice["message"].(map[string]any)
|
||||
return CreateResult{Status: StatusSucceeded, Result: &Result{Text: firstString(message, "content"), Usage: object(payload["usage"])}}, nil
|
||||
}
|
||||
|
||||
func parseResponsesResponse(payload map[string]any) (CreateResult, error) {
|
||||
text := firstString(payload, "output_text", "text")
|
||||
if text == "" {
|
||||
if output, ok := payload["output"].([]any); ok {
|
||||
for _, item := range output {
|
||||
if m, ok := item.(map[string]any); ok {
|
||||
text = firstString(m, "text", "content")
|
||||
if text != "" {
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return CreateResult{Status: StatusSucceeded, Result: &Result{Text: text, Usage: object(payload["usage"])}}, nil
|
||||
}
|
||||
|
||||
func parseClaudeResponse(payload map[string]any) (CreateResult, error) {
|
||||
content, _ := payload["content"].([]any)
|
||||
text := ""
|
||||
for _, item := range content {
|
||||
if m, ok := item.(map[string]any); ok && firstString(m, "type") == "text" {
|
||||
text += firstString(m, "text")
|
||||
}
|
||||
}
|
||||
return CreateResult{Status: StatusSucceeded, Result: &Result{Text: text, Usage: object(payload["usage"])}}, nil
|
||||
}
|
||||
|
||||
func parseImageResponse(payload map[string]any) (CreateResult, error) {
|
||||
values, _ := payload["data"].([]any)
|
||||
images := make([]MediaReference, 0, len(values))
|
||||
for _, item := range values {
|
||||
media, _ := item.(map[string]any)
|
||||
if value := firstString(media, "url"); value != "" {
|
||||
images = append(images, MediaReference{URL: value, Kind: "image"})
|
||||
continue
|
||||
}
|
||||
if value := firstString(media, "b64_json", "data"); value != "" {
|
||||
if !strings.HasPrefix(value, "data:") {
|
||||
value = "data:image/png;base64," + value
|
||||
}
|
||||
images = append(images, MediaReference{DataURL: value, Kind: "image"})
|
||||
}
|
||||
}
|
||||
if len(images) == 0 {
|
||||
return CreateResult{}, fmt.Errorf("image response has no image data")
|
||||
}
|
||||
return CreateResult{Status: StatusSucceeded, Result: &Result{Images: images}}, nil
|
||||
}
|
||||
|
||||
func parseGeminiImageResponse(payload map[string]any) (CreateResult, error) {
|
||||
images := make([]MediaReference, 0)
|
||||
if candidates, ok := payload["candidates"].([]any); ok {
|
||||
for _, candidate := range candidates {
|
||||
if c, ok := candidate.(map[string]any); ok {
|
||||
content, _ := c["content"].(map[string]any)
|
||||
parts, _ := content["parts"].([]any)
|
||||
for _, part := range parts {
|
||||
if p, ok := part.(map[string]any); ok {
|
||||
data, _ := p["inlineData"].(map[string]any)
|
||||
if data == nil {
|
||||
data, _ = p["inline_data"].(map[string]any)
|
||||
}
|
||||
if data != nil {
|
||||
images = append(images, MediaReference{DataURL: "data:" + firstString(data, "mimeType", "mime_type") + ";base64," + firstString(data, "data")})
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
if len(images) == 0 {
|
||||
return CreateResult{}, fmt.Errorf("Gemini response has no inline image data")
|
||||
}
|
||||
return CreateResult{Status: StatusSucceeded, Result: &Result{Images: images}}, nil
|
||||
}
|
||||
|
||||
func parseJiMengCreate(payload map[string]any) (CreateResult, error) {
|
||||
id := firstString(payload, "task_id", "taskId", "id")
|
||||
if data := object(payload["data"]); data != nil {
|
||||
id = defaultValue(firstString(data, "task_id", "taskId", "id"), id)
|
||||
}
|
||||
if id == "" {
|
||||
return CreateResult{}, fmt.Errorf("Jimeng response has no task id")
|
||||
}
|
||||
return CreateResult{TaskID: id, Status: StatusPending}, nil
|
||||
}
|
||||
func parseJiMengPoll(c PollContext, payload map[string]any) (PollResult, error) {
|
||||
return parseAsyncMediaPoll(c, payload, CapabilityImage)
|
||||
}
|
||||
|
||||
func parseGeminiVeoCreate(payload map[string]any) (CreateResult, error) {
|
||||
id := firstString(payload, "name")
|
||||
if id == "" {
|
||||
return CreateResult{}, fmt.Errorf("Gemini Veo response has no operation name")
|
||||
}
|
||||
return CreateResult{TaskID: id, Status: StatusPending}, nil
|
||||
}
|
||||
|
||||
func parseGeminiVeoPoll(c PollContext, payload map[string]any) (PollResult, error) {
|
||||
id := defaultValue(firstString(payload, "name"), c.TaskID)
|
||||
if failure := object(payload["error"]); failure != nil {
|
||||
message := firstString(failure, "message", "status")
|
||||
if message == "" {
|
||||
message = "Gemini Veo operation failed"
|
||||
}
|
||||
return PollResult{TaskID: id, Status: StatusFailed, Message: message}, nil
|
||||
}
|
||||
done, _ := payload["done"].(bool)
|
||||
if !done {
|
||||
return PollResult{TaskID: id, Status: StatusProcessing}, nil
|
||||
}
|
||||
response := object(payload["response"])
|
||||
videos := geminiVeoVideos(response)
|
||||
if len(videos) == 0 {
|
||||
return PollResult{TaskID: id, Status: StatusSucceeded}, nil
|
||||
}
|
||||
return PollResult{TaskID: id, Status: StatusSucceeded, Result: &Result{Videos: videos}}, nil
|
||||
}
|
||||
|
||||
func geminiVeoVideos(response map[string]any) []MediaReference {
|
||||
if response == nil {
|
||||
return nil
|
||||
}
|
||||
containers := []map[string]any{response}
|
||||
for _, key := range []string{"generateVideoResponse", "generate_video_response"} {
|
||||
if nested := object(response[key]); nested != nil {
|
||||
containers = append(containers, nested)
|
||||
}
|
||||
}
|
||||
result := make([]MediaReference, 0)
|
||||
for _, container := range containers {
|
||||
for _, key := range []string{"generatedVideos", "generated_videos", "generatedSamples", "generated_samples", "videos"} {
|
||||
items, _ := container[key].([]any)
|
||||
for _, item := range items {
|
||||
entry := object(item)
|
||||
video := object(entry["video"])
|
||||
if video == nil {
|
||||
video = entry
|
||||
}
|
||||
if value := firstString(video, "uri", "url", "videoUri", "video_url"); value != "" {
|
||||
result = append(result, MediaReference{URL: value, Kind: string(CapabilityVideo)})
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
func parseAsyncCreate(payload map[string]any) (CreateResult, error) {
|
||||
id := firstString(payload, "id", "task_id", "taskId", "request_id")
|
||||
status := normalizeStatus(firstString(payload, "status", "state"))
|
||||
if task := object(payload["task"]); task != nil {
|
||||
id = defaultValue(firstString(task, "id", "task_id", "taskId", "request_id"), id)
|
||||
status = normalizeStatus(defaultValue(firstString(task, "status", "state"), string(status)))
|
||||
}
|
||||
if data := object(payload["data"]); data != nil {
|
||||
id = defaultValue(firstString(data, "id", "task_id", "taskId", "request_id"), id)
|
||||
status = normalizeStatus(defaultValue(firstString(data, "status", "state"), string(status)))
|
||||
}
|
||||
if id == "" {
|
||||
return CreateResult{}, fmt.Errorf("async response has no task id")
|
||||
}
|
||||
if status == "" {
|
||||
status = StatusPending
|
||||
}
|
||||
return CreateResult{TaskID: id, Status: status, Message: firstString(payload, "message", "error")}, nil
|
||||
}
|
||||
|
||||
func parseAsyncMediaPoll(c PollContext, payload map[string]any, capability Capability) (PollResult, error) {
|
||||
if capability != CapabilityImage && capability != CapabilityVideo && capability != CapabilityAudio {
|
||||
return PollResult{}, fmt.Errorf("unsupported async media capability %q", capability)
|
||||
}
|
||||
status := normalizeStatus(firstString(payload, "status", "state", "task_status"))
|
||||
if task := object(payload["task"]); task != nil {
|
||||
status = normalizeStatus(defaultValue(firstString(task, "status", "state"), string(status)))
|
||||
payload = mergeMaps(task, payload)
|
||||
}
|
||||
if data := object(payload["data"]); data != nil {
|
||||
payload = mergeMaps(data, payload)
|
||||
status = normalizeStatus(defaultValue(firstString(data, "status", "state"), string(status)))
|
||||
}
|
||||
if status == "" {
|
||||
status = StatusProcessing
|
||||
}
|
||||
result := &Result{}
|
||||
resultKind := string(capability)
|
||||
references := mediaFromArray(payload[resultKind+"s"], capability)
|
||||
references = append(references, mediaFromArray(payload["data"], capability)...)
|
||||
if content := object(payload["content"]); content != nil {
|
||||
references = append(references, mediaFromArray([]any{content}, capability)...)
|
||||
}
|
||||
keys := []string{resultKind + "_url", resultKind + "Url", "result_url", "url"}
|
||||
if resultKind == "video" {
|
||||
keys = append(keys, "object")
|
||||
}
|
||||
if value := firstString(payload, keys...); value != "" {
|
||||
references = append(references, MediaReference{URL: value, Kind: resultKind})
|
||||
}
|
||||
switch capability {
|
||||
case CapabilityImage:
|
||||
result.Images = references
|
||||
case CapabilityAudio:
|
||||
result.Audios = references
|
||||
case CapabilityVideo:
|
||||
result.Videos = references
|
||||
}
|
||||
if status == StatusSucceeded && len(references) == 0 {
|
||||
result = nil
|
||||
}
|
||||
return PollResult{TaskID: defaultValue(firstString(payload, "id", "task_id", "taskId"), c.TaskID), Status: status, Result: result, Message: firstString(payload, "message", "error", "fail_reason")}, nil
|
||||
}
|
||||
|
||||
func parseAudioResponse(payload map[string]any) (CreateResult, error) {
|
||||
value := firstString(payload, "url", "audio_url", "data")
|
||||
if value == "" {
|
||||
return CreateResult{}, fmt.Errorf("audio response has no result")
|
||||
}
|
||||
return CreateResult{Status: StatusSucceeded, Result: &Result{Audios: []MediaReference{{URL: value, Kind: "audio"}}}}, nil
|
||||
}
|
||||
|
||||
func normalizeStatus(raw string) Status {
|
||||
switch strings.ToLower(strings.TrimSpace(raw)) {
|
||||
case "queued", "pending", "created", "submitted", "in_queue", "task_status_queued":
|
||||
return StatusPending
|
||||
case "running", "processing", "in_progress", "executing", "task_status_running":
|
||||
return StatusProcessing
|
||||
case "succeeded", "success", "completed", "complete", "done", "task_status_succeed":
|
||||
return StatusSucceeded
|
||||
case "failed", "failure", "error", "cancelled", "canceled", "expired":
|
||||
return StatusFailed
|
||||
default:
|
||||
return ""
|
||||
}
|
||||
}
|
||||
|
||||
func decodeObject(body []byte) (map[string]any, error) {
|
||||
var payload map[string]any
|
||||
if err := json.Unmarshal(body, &payload); err != nil {
|
||||
return nil, fmt.Errorf("protocol response is not JSON: %w", err)
|
||||
}
|
||||
return payload, nil
|
||||
}
|
||||
func object(value any) map[string]any { result, _ := value.(map[string]any); return result }
|
||||
func mergeMaps(primary, fallback map[string]any) map[string]any {
|
||||
result := make(map[string]any, len(fallback)+len(primary))
|
||||
for k, v := range fallback {
|
||||
result[k] = v
|
||||
}
|
||||
for k, v := range primary {
|
||||
result[k] = v
|
||||
}
|
||||
return result
|
||||
}
|
||||
func firstString(payload map[string]any, keys ...string) string {
|
||||
for _, key := range keys {
|
||||
if value, ok := payload[key].(string); ok && strings.TrimSpace(value) != "" {
|
||||
return strings.TrimSpace(value)
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
func defaultValue(value, fallback string) string {
|
||||
if strings.TrimSpace(value) == "" {
|
||||
return fallback
|
||||
}
|
||||
return value
|
||||
}
|
||||
func defaultInt(value, fallback int) int {
|
||||
if value <= 0 {
|
||||
return fallback
|
||||
}
|
||||
return value
|
||||
}
|
||||
func copyIf(body map[string]any, key, value string) {
|
||||
if strings.TrimSpace(value) != "" {
|
||||
body[key] = value
|
||||
}
|
||||
}
|
||||
func mergeExtra(body map[string]any, extra map[string]any, keys ...string) {
|
||||
for _, key := range keys {
|
||||
if value, ok := extra[key]; ok {
|
||||
body[key] = value
|
||||
}
|
||||
}
|
||||
}
|
||||
func compactMap(body map[string]any) map[string]any {
|
||||
result := make(map[string]any)
|
||||
for key, value := range body {
|
||||
switch item := value.(type) {
|
||||
case string:
|
||||
if strings.TrimSpace(item) != "" {
|
||||
result[key] = value
|
||||
}
|
||||
case int:
|
||||
if item > 0 {
|
||||
result[key] = value
|
||||
}
|
||||
case bool:
|
||||
result[key] = value
|
||||
case nil:
|
||||
default:
|
||||
result[key] = item
|
||||
}
|
||||
}
|
||||
return result
|
||||
}
|
||||
func mediaValue(media MediaReference) string { return defaultValue(media.URL, media.DataURL) }
|
||||
func mediaValues(values []MediaReference) []string {
|
||||
result := make([]string, 0, len(values))
|
||||
for _, value := range values {
|
||||
if item := mediaValue(value); item != "" {
|
||||
result = append(result, item)
|
||||
}
|
||||
}
|
||||
return result
|
||||
}
|
||||
func mediaFromArray(value any, capability Capability) []MediaReference {
|
||||
values, _ := value.([]any)
|
||||
result := make([]MediaReference, 0, len(values))
|
||||
kind := string(capability)
|
||||
for _, item := range values {
|
||||
if value, ok := item.(string); ok && strings.TrimSpace(value) != "" {
|
||||
result = append(result, MediaReference{URL: strings.TrimSpace(value), Kind: kind})
|
||||
continue
|
||||
}
|
||||
if m, ok := item.(map[string]any); ok {
|
||||
if capability == CapabilityImage {
|
||||
if value := firstString(m, "b64_json", "data"); value != "" {
|
||||
if !strings.HasPrefix(value, "data:") {
|
||||
value = "data:image/png;base64," + value
|
||||
}
|
||||
result = append(result, MediaReference{DataURL: value, Kind: kind})
|
||||
continue
|
||||
}
|
||||
}
|
||||
if value := firstString(m, "url", "image_url", "video_url", "audio_url"); value != "" {
|
||||
result = append(result, MediaReference{URL: value, Kind: kind})
|
||||
}
|
||||
}
|
||||
}
|
||||
return result
|
||||
}
|
||||
func dataMIME(value string) string {
|
||||
if index := strings.Index(value, ";"); strings.HasPrefix(value, "data:") && index > 5 {
|
||||
return strings.TrimPrefix(value[5:index], "")
|
||||
}
|
||||
return "application/octet-stream"
|
||||
}
|
||||
func dataPayload(value string) string {
|
||||
if index := strings.Index(value, ","); strings.HasPrefix(value, "data:") && index >= 0 {
|
||||
return value[index+1:]
|
||||
}
|
||||
return value
|
||||
}
|
||||
@@ -0,0 +1,370 @@
|
||||
package protocol
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestBuiltinCatalogContainsRequestedProtocols(t *testing.T) {
|
||||
registry := Builtins()
|
||||
expected := []string{
|
||||
"chat-completion", "openai-response", "claude-api",
|
||||
"openai-image", "grok-image", "volcengine-ark-image", "volcengine-jimeng-image", "gemini-image",
|
||||
"newapi", "newapi-channel-2", "xai-video", "volcengine-ark-video", "volcengine-jimeng-video", "gemini-veo", "novita-video", "minimax-video", "agnes-video",
|
||||
}
|
||||
for _, id := range expected {
|
||||
if _, ok := registry.Get(id); !ok {
|
||||
t.Fatalf("missing builtin protocol %q", id)
|
||||
}
|
||||
}
|
||||
if _, ok := registry.Resolve("openai-video"); !ok {
|
||||
t.Fatal("legacy OpenAI video alias was not registered")
|
||||
}
|
||||
available := registry.List(SurfaceUserCustomChannel, CapabilityVideo, false)
|
||||
for _, item := range available {
|
||||
if item.ID == "agnes-video" {
|
||||
t.Fatal("unavailable Agnes adapter was selectable")
|
||||
}
|
||||
}
|
||||
all := registry.List(SurfaceAdminSystemChannel, CapabilityVideo, true)
|
||||
var found bool
|
||||
for _, item := range all {
|
||||
if item.ID == "agnes-video" {
|
||||
found = true
|
||||
if item.UnavailableReason == "" || item.Enabled {
|
||||
t.Fatalf("Agnes metadata must explain that it is disabled: %#v", item)
|
||||
}
|
||||
}
|
||||
}
|
||||
if !found {
|
||||
t.Fatal("Agnes metadata was omitted from the administrator catalog")
|
||||
}
|
||||
}
|
||||
|
||||
func TestTextAdaptersMapRequestsAndResponses(t *testing.T) {
|
||||
cases := []struct {
|
||||
id string
|
||||
path string
|
||||
body map[string]any
|
||||
resp string
|
||||
want string
|
||||
}{
|
||||
{"chat-completion", "/v1/chat/completions", map[string]any{"model": "gpt-test", "messages": []any{map[string]any{"role": "user", "content": "hello"}}}, `{"choices":[{"message":{"content":"chat answer"}}]}`, "chat answer"},
|
||||
{"openai-response", "/v1/responses", map[string]any{"model": "o-test", "input": "hello"}, `{"output_text":"response answer"}`, "response answer"},
|
||||
{"claude-api", "/v1/messages", map[string]any{"model": "claude-test", "max_tokens": float64(4096)}, `{"content":[{"type":"text","text":"claude answer"}]}`, "claude answer"},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.id, func(t *testing.T) {
|
||||
adapter, ok := Builtins().Get(tc.id)
|
||||
if !ok {
|
||||
t.Fatal("adapter missing")
|
||||
}
|
||||
spec, err := adapter.BuildCreate(context.Background(), RequestContext{Request: GenerationRequest{Model: tc.body["model"].(string), Prompt: "hello"}})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if spec.Method != http.MethodPost || spec.Path != tc.path {
|
||||
t.Fatalf("request = %#v", spec)
|
||||
}
|
||||
body, _ := json.Marshal(spec.Body)
|
||||
var got map[string]any
|
||||
if err := json.Unmarshal(body, &got); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for key, value := range tc.body {
|
||||
if key == "messages" {
|
||||
continue
|
||||
}
|
||||
if got[key] == nil {
|
||||
t.Fatalf("request missing %q: %#v", key, got)
|
||||
}
|
||||
_ = value
|
||||
}
|
||||
result, err := adapter.ParseCreate(context.Background(), []byte(tc.resp))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if result.Status != StatusSucceeded || result.Result == nil || result.Result.Text != tc.want {
|
||||
t.Fatalf("result = %#v", result)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestClaudeAdapterDeclaresAnthropicVersion(t *testing.T) {
|
||||
adapter, _ := Builtins().Get("claude-api")
|
||||
spec, err := adapter.BuildCreate(context.Background(), RequestContext{Request: GenerationRequest{Model: "claude-test", Prompt: "hello"}})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if spec.Headers["anthropic-version"] != "2023-06-01" {
|
||||
t.Fatalf("headers = %#v", spec.Headers)
|
||||
}
|
||||
}
|
||||
|
||||
func TestImageAndVideoAdaptersMapProviderShapes(t *testing.T) {
|
||||
cases := []struct {
|
||||
id, path, poll string
|
||||
request GenerationRequest
|
||||
}{
|
||||
{"openai-image", "/v1/images/generations", "", GenerationRequest{Model: "dall-e-test", Prompt: "a still", ImageCount: 2, AspectRatio: "1024x1024"}},
|
||||
{"grok-image", "/v1/images/generations", "", GenerationRequest{Model: "grok-imagine-image", Prompt: "a still", AspectRatio: "16:9"}},
|
||||
{"volcengine-ark-image", "/api/v3/images/generations", "", GenerationRequest{Model: "doubao-image", Prompt: "a still"}},
|
||||
{"volcengine-jimeng-image", "/CVSync2AsyncSubmitTask", "/CVSync2AsyncGetResult", GenerationRequest{Model: "jimeng_t2i_v40", Prompt: "a still"}},
|
||||
{"gemini-image", "/v1beta/models/gemini-image:generateContent", "", GenerationRequest{Model: "gemini-image", Prompt: "a still"}},
|
||||
{"newapi", "/v1/videos", "/v1/videos/video-1", GenerationRequest{Model: "video-model", Prompt: "a clip", Duration: 6}},
|
||||
{"newapi-channel-2", "/v1/video/generations", "/v1/video/generations/video-1", GenerationRequest{Model: "video-model", Prompt: "a clip", Duration: 6, AspectRatio: "16:9"}},
|
||||
{"xai-video", "/v1/videos/generations", "/v1/videos/video-1", GenerationRequest{Model: "grok-video", Prompt: "a clip"}},
|
||||
{"volcengine-ark-video", "/api/v3/contents/generations/tasks", "/api/v3/contents/generations/tasks/video-1", GenerationRequest{Model: "seedance", Prompt: "a clip"}},
|
||||
{"volcengine-jimeng-video", "/CVSync2AsyncSubmitTask", "/CVSync2AsyncGetResult", GenerationRequest{Model: "jimeng_video", Prompt: "a clip"}},
|
||||
{"gemini-veo", "/v1beta/models/veo-test:predictLongRunning", "/v1beta/operations/video-1", GenerationRequest{Model: "veo-test", Prompt: "a clip"}},
|
||||
{"novita-video", "/v3/video/create", "/v3/async/task-result?task_id=video-1", GenerationRequest{Model: "novita", Prompt: "a clip"}},
|
||||
{"minimax-video", "/v2/video_generation", "/v2/query/video_generation/video-1", GenerationRequest{Model: "MiniMax-H3", Prompt: "a clip"}},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.id, func(t *testing.T) {
|
||||
adapter, ok := Builtins().Get(tc.id)
|
||||
if !ok {
|
||||
t.Fatal("adapter missing")
|
||||
}
|
||||
create, err := adapter.BuildCreate(context.Background(), RequestContext{Request: tc.request})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if create.Path != tc.path {
|
||||
t.Fatalf("create path = %q, want %q", create.Path, tc.path)
|
||||
}
|
||||
if tc.poll != "" {
|
||||
poll, err := adapter.BuildPoll(context.Background(), PollContext{Model: tc.request.Model, TaskID: "video-1"})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if poll.Path != tc.poll {
|
||||
t.Fatalf("poll path = %q, want %q", poll.Path, tc.poll)
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestAsyncVideoResponseNormalizesStatusAndResult(t *testing.T) {
|
||||
adapter, _ := Builtins().Get("minimax-video")
|
||||
created, err := adapter.ParseCreate(context.Background(), []byte(`{"task":{"id":"mm-1","status":"processing"}}`))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if created.TaskID != "mm-1" || created.Status != StatusProcessing {
|
||||
t.Fatalf("created = %#v", created)
|
||||
}
|
||||
polled, err := adapter.ParsePoll(context.Background(), PollContext{TaskID: created.TaskID}, []byte(`{"task":{"id":"mm-1","status":"succeeded","content":{"url":"https://cdn.example/video.mp4"}}}`))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if polled.Status != StatusSucceeded || polled.Result == nil || len(polled.Result.Videos) != 1 || polled.Result.Videos[0].URL != "https://cdn.example/video.mp4" {
|
||||
t.Fatalf("polled = %#v", polled)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAgnesIsExplicitlyUnavailable(t *testing.T) {
|
||||
adapter, _ := Builtins().Get("agnes-video")
|
||||
_, err := adapter.BuildCreate(context.Background(), RequestContext{Request: GenerationRequest{Model: "agnes", Prompt: "test"}})
|
||||
if err == nil {
|
||||
t.Fatal("Agnes unexpectedly accepted a request")
|
||||
}
|
||||
if _, ok := err.(UnavailableError); !ok {
|
||||
t.Fatalf("error = %T %v", err, err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDeclarativeManifestMapsFieldsAndResponses(t *testing.T) {
|
||||
manifest := []byte(`{
|
||||
"apiVersion":"v1",
|
||||
"metadata":{"id":"example-video","version":"1.0.0","name":"Example Video","vendor":"Example","categories":["video"],"scopes":["admin.system-channel","user.custom-channel"],"documentation":"# Example Video"},
|
||||
"create":{"method":"POST","path":"/v1/tasks","fields":{"model":"request.model","input.prompt":"request.prompt","input.seconds":"request.duration"}},
|
||||
"poll":{"method":"GET","path":"/v1/tasks/{{taskId}}"},
|
||||
"response":{"taskIdPaths":["id","data.id"],"statusPaths":["status","data.status"],"resultUrlPaths":["result.video_url","data.result.video_url"],"resultKind":"video"}
|
||||
}`)
|
||||
adapter, err := LoadManifest(manifest)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
create, err := adapter.BuildCreate(context.Background(), RequestContext{Request: GenerationRequest{Model: "example", Prompt: "hello", Duration: 5}})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if create.Path != "/v1/tasks" || create.Method != http.MethodPost {
|
||||
t.Fatalf("create = %#v", create)
|
||||
}
|
||||
body, _ := json.Marshal(create.Body)
|
||||
var got map[string]any
|
||||
if err := json.Unmarshal(body, &got); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
input := got["input"].(map[string]any)
|
||||
if input["prompt"] != "hello" || input["seconds"].(float64) != 5 {
|
||||
t.Fatalf("body = %#v", got)
|
||||
}
|
||||
poll, err := adapter.BuildPoll(context.Background(), PollContext{Model: "example", TaskID: "task-1"})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if poll.Path != "/v1/tasks/task-1" {
|
||||
t.Fatalf("poll = %#v", poll)
|
||||
}
|
||||
result, err := adapter.ParsePoll(context.Background(), PollContext{TaskID: "task-1"}, []byte(`{"data":{"id":"task-1","status":"succeeded","result":{"video_url":"https://cdn.example/clip.mp4"}}}`))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if result.Status != StatusSucceeded || result.Result == nil || len(result.Result.Videos) != 1 || result.Result.Videos[0].URL != "https://cdn.example/clip.mp4" {
|
||||
t.Fatalf("result = %#v", result)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDeclarativeManifestRequiresDocumentation(t *testing.T) {
|
||||
manifest := Manifest{
|
||||
APIVersion: "v1",
|
||||
Metadata: Metadata{
|
||||
ID: "missing-docs", Version: "1.0.0", Name: "Missing Docs",
|
||||
Categories: []Capability{CapabilityVideo},
|
||||
Scopes: []Surface{SurfaceAdminSystemChannel},
|
||||
},
|
||||
Create: ManifestOperation{Method: http.MethodPost, Path: "/v1/tasks"},
|
||||
}
|
||||
if err := ValidateManifest(manifest); err == nil {
|
||||
t.Fatal("manifest without documentation was accepted")
|
||||
}
|
||||
}
|
||||
|
||||
func TestBuiltinDocumentationMatchesTextRequestShape(t *testing.T) {
|
||||
cases := []struct {
|
||||
id, mapping, requestField string
|
||||
}{
|
||||
{"chat-completion", "messages[0].content", `"messages"`},
|
||||
{"openai-response", "input", `"input"`},
|
||||
{"claude-api", "messages[0].content", `"messages"`},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.id, func(t *testing.T) {
|
||||
adapter, ok := Builtins().Get(tc.id)
|
||||
if !ok {
|
||||
t.Fatal("adapter missing")
|
||||
}
|
||||
metadata := adapter.Metadata()
|
||||
AttachDocumentation(&metadata)
|
||||
if !strings.Contains(metadata.Documentation, tc.mapping) || !strings.Contains(metadata.Documentation, tc.requestField) {
|
||||
t.Fatalf("documentation does not match request shape:\n%s", metadata.Documentation)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestEveryBuiltinHasDetailedDocumentation(t *testing.T) {
|
||||
requiredSections := []string{"## 接口", "## 模型", "## 参数", "## 官方", "## 影策运行时合同"}
|
||||
for _, metadata := range Builtins().List("", "", true) {
|
||||
t.Run(metadata.ID, func(t *testing.T) {
|
||||
AttachDocumentation(&metadata)
|
||||
document := metadata.Documentation
|
||||
if len([]rune(document)) < 900 {
|
||||
t.Fatalf("documentation is too short: %d runes", len([]rune(document)))
|
||||
}
|
||||
for _, section := range requiredSections {
|
||||
if !strings.Contains(document, section) {
|
||||
t.Errorf("documentation is missing section %q", section)
|
||||
}
|
||||
}
|
||||
for _, operation := range []string{metadata.Create, metadata.Poll} {
|
||||
parts := strings.SplitN(operation, " ", 2)
|
||||
if len(parts) == 2 && !strings.Contains(document, parts[1]) {
|
||||
t.Errorf("documentation is missing operation path %q", parts[1])
|
||||
}
|
||||
}
|
||||
for _, parameter := range metadata.Parameters {
|
||||
if !strings.Contains(document, "`"+parameter.Name+"`") {
|
||||
t.Errorf("documentation is missing parameter %q", parameter.Name)
|
||||
}
|
||||
}
|
||||
if strings.Contains(document, "{{") {
|
||||
t.Errorf("documentation contains an unresolved template marker")
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestImageResponseKeepsBase64AsDataURL(t *testing.T) {
|
||||
adapter, _ := Builtins().Get("openai-image")
|
||||
result, err := adapter.ParseCreate(context.Background(), []byte(`{"data":[{"b64_json":"aW1hZ2U="}]}`))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if result.Result == nil || len(result.Result.Images) != 1 || result.Result.Images[0].URL != "" || result.Result.Images[0].DataURL != "data:image/png;base64,aW1hZ2U=" {
|
||||
t.Fatalf("images = %#v", result.Result)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAsyncMediaPollKeepsResultKind(t *testing.T) {
|
||||
cases := []struct {
|
||||
id, payload, want string
|
||||
}{
|
||||
{"volcengine-jimeng-image", `{"data":{"status":"completed","images":["https://cdn.example/image.png"]}}`, "image"},
|
||||
{"async-audio", `{"task":{"id":"audio-1","status":"completed","audio_url":"https://cdn.example/audio.mp3"}}`, "audio"},
|
||||
{"minimax-video", `{"task":{"id":"video-1","status":"succeeded","content":{"url":"https://cdn.example/video.mp4"}}}`, "video"},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.id, func(t *testing.T) {
|
||||
adapter, _ := Builtins().Get(tc.id)
|
||||
result, err := adapter.ParsePoll(context.Background(), PollContext{TaskID: "fallback"}, []byte(tc.payload))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if result.Status != StatusSucceeded || result.Result == nil {
|
||||
t.Fatalf("result = %#v", result)
|
||||
}
|
||||
switch tc.want {
|
||||
case "image":
|
||||
if len(result.Result.Images) != 1 || len(result.Result.Videos) != 0 || len(result.Result.Audios) != 0 {
|
||||
t.Fatalf("media = %#v", result.Result)
|
||||
}
|
||||
case "audio":
|
||||
if len(result.Result.Audios) != 1 || len(result.Result.Images) != 0 || len(result.Result.Videos) != 0 {
|
||||
t.Fatalf("media = %#v", result.Result)
|
||||
}
|
||||
case "video":
|
||||
if len(result.Result.Videos) != 1 || len(result.Result.Images) != 0 || len(result.Result.Audios) != 0 {
|
||||
t.Fatalf("media = %#v", result.Result)
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestGeminiVeoParsesLongRunningOperation(t *testing.T) {
|
||||
adapter, _ := Builtins().Get("gemini-veo")
|
||||
created, err := adapter.ParseCreate(context.Background(), []byte(`{"name":"operations/veo-1"}`))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if created.TaskID != "operations/veo-1" || created.Status != StatusPending {
|
||||
t.Fatalf("created = %#v", created)
|
||||
}
|
||||
|
||||
result, err := adapter.ParsePoll(context.Background(), PollContext{TaskID: created.TaskID}, []byte(`{
|
||||
"name":"operations/veo-1",
|
||||
"done":true,
|
||||
"response":{"generateVideoResponse":{"generatedSamples":[{"video":{"uri":"https://cdn.example/veo.mp4"}}]}}
|
||||
}`))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if result.Status != StatusSucceeded || result.Result == nil || len(result.Result.Videos) != 1 || result.Result.Videos[0].URL != "https://cdn.example/veo.mp4" {
|
||||
t.Fatalf("result = %#v", result)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAsyncMediaPollRejectsUnsupportedCapability(t *testing.T) {
|
||||
if _, err := parseAsyncMediaPoll(PollContext{TaskID: "task-1"}, map[string]any{"status": "completed"}, CapabilityText); err == nil {
|
||||
t.Fatal("text capability was accepted by async media parser")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,46 @@
|
||||
# Agnes 视频协议(当前不可用)
|
||||
|
||||
Agnes 作为内置占位插件保留,是为了让历史模型配置能显示明确的不可用原因,而不是静默消失。当前仓库没有可验证的官方接口、鉴权、模型、轮询和响应资料,因此插件被强制禁用,也不可安装或选择。
|
||||
|
||||
## 接口与当前状态
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
创建、轮询、取消路径均为空。调用 `BuildCreate` 会返回 `UnavailableError`:`未提供可验证的官方请求、鉴权、轮询和响应协议资料`。页面展示该条目不代表可以发送任务。
|
||||
|
||||
## 模型与能力状态
|
||||
|
||||
当前没有任何经过验证的模型 ID、能力范围或计费规则。任何 Agnes 模型名都不可提交;只有取得官方模型目录并完成真实账户验证后,才能写入渠道模型配置。
|
||||
|
||||
## 参数与字段状态
|
||||
|
||||
当前 metadata 没有参数映射,创建请求也不存在。`model`、`prompt`、参考素材、时长、比例、分辨率、音频和水印均不得推测或透传。
|
||||
|
||||
## 启用前必须补齐的事实
|
||||
|
||||
| 项目 | 必须取得的证据 | 验收方式 |
|
||||
| --- | --- | --- |
|
||||
| 服务入口 | 官方 Base URL、版本、区域 | 官方文档链接和最小健康探测 |
|
||||
| 鉴权 | Header、Token/签名算法、权限范围 | 不在 URL/日志泄露密钥的集成测试 |
|
||||
| 模型 | 精确模型 ID、能力和停用策略 | 真实账户模型发现或官方表 |
|
||||
| 创建 | Method、Path、Content-Type、完整字段 | 请求 fixture 与真实 2xx 响应 |
|
||||
| 轮询 | 任务 ID、状态枚举、失败结构 | queued -> running -> completed/failed fixture |
|
||||
| 结果 | 视频 URL、文件接口、有效期 | 下载并存入影策资源的冒烟测试 |
|
||||
| 取消与账务 | 是否支持取消、失败退款语义 | 官方合同与错误场景验证 |
|
||||
|
||||
## 禁止的临时处理
|
||||
|
||||
- 不得根据插件名猜测 `/v1/videos`、模型名或 Bearer 鉴权。
|
||||
- 不得复用其他视频供应商的字段并把 200 响应当兼容。
|
||||
- 不得用空任务 ID、默认成功状态或假 URL 让页面“看起来能用”。
|
||||
- 不得仅在前端隐藏;后端 registry 和写路径必须继续拒绝不可用协议。
|
||||
|
||||
## 未来实现结构
|
||||
|
||||
取得官方资料后,应新增独立 adapter、专属 create/poll/result fixture、错误码映射和一份替换本文的完整文档。若协议实际是已有供应商的别名,应迁移历史配置到明确的 canonical ID,而不是永久保留第二套执行逻辑。
|
||||
|
||||
## 官方资料
|
||||
|
||||
当前未找到可验证且与本插件对应的官方开发者资料。为避免误导,本页不引用搜索聚合、论坛转述或其他同名产品文档。
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,52 @@
|
||||
# 异步音频任务兼容协议
|
||||
|
||||
该插件定义一个简化的 OpenAI 风格异步音频合同:JSON 创建任务,轮询任务资源,成功后读取媒体 URL。它不是 OpenAI 官方 Speech API,也不代表某个固定供应商。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/audio/tasks
|
||||
GET {channel_base_url}/v1/audio/tasks/{task_id}
|
||||
Authorization: Bearer <CHANNEL_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型、声音与计费
|
||||
|
||||
模型 ID、任务类型、声音、语言、格式、时长限制、音色克隆权限和计费完全由实现该兼容接口的渠道决定。插件没有供应商白名单;管理员必须用该部署的接口文档校对。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
当前创建正文只包含:
|
||||
|
||||
```json
|
||||
{"model":"YOUR_ASYNC_AUDIO_MODEL","prompt":"低沉克制的男声旁白:风暴即将到来。"}
|
||||
```
|
||||
|
||||
没有映射 `voice`、`format`、`speed`、参考音频、歌词或音乐结构。若模型依赖这些字段,当前插件不适用。
|
||||
|
||||
## 创建、轮询与结果
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/audio/tasks" \
|
||||
-H "Authorization: Bearer <CHANNEL_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model":"YOUR_ASYNC_AUDIO_MODEL","prompt":"雨声环境音,逐渐增强"}'
|
||||
```
|
||||
|
||||
创建响应需包含任务 ID,查询路径使用该 ID。轮询 parser 按音频类型提取 `audios`、`audio_url`、`audioUrl`、`result_url` 或 `url`,不会把音频误写入视频结果。若部署返回其他深层结构,必须增加该渠道 fixture 和明确映射。
|
||||
|
||||
## 错误与安全
|
||||
|
||||
任务不存在、模型不支持、输入过长、声音授权或内容审核失败应原样返回。涉及真人声音克隆时必须确认授权;参考音频和生成链接不得写入公开日志。结果 URL 应尽快转存。
|
||||
|
||||
## 官方资料与边界
|
||||
|
||||
- 本页以影策当前 adapter 为唯一字段事实源。
|
||||
- 渠道部署方必须提供真实的模型、声音、错误码和计费文档;没有这些资料时不能对用户承诺能力。
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,62 @@
|
||||
# OpenAI Chat Completions
|
||||
|
||||
Chat Completions 是基于 `messages` 的同步或流式文本协议。影策默认把提示词包装成一条 `user` 消息;需要多轮上下文、工具调用或结构化输出时,通过模型扩展参数传入完整 OpenAI 字段。
|
||||
|
||||
## 接口、鉴权与请求模式
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/chat/completions
|
||||
Authorization: Bearer <API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
官方服务的 Base URL 通常以 `/v1` 结尾;在影策中应以渠道实际配置为准。同步请求返回单个 JSON;`stream: true` 时上游返回 SSE,影策文本任务流负责转发和组装事件。
|
||||
|
||||
## 模型与兼容边界
|
||||
|
||||
模型名不会由插件维护白名单,必须填写渠道实际暴露的模型 ID。OpenAI 新项目更推荐 Responses API;现有 Chat Completions 模型和兼容渠道仍可使用本插件。兼容渠道可能只实现字段子集,不能因为路径相同就假定支持工具、视觉输入或 JSON Schema。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
可通过 `extra` 透传 `messages`、`temperature`、`top_p`、`max_tokens`、`stream`、`tools` 和 `response_format`。传入 `extra.messages` 时会替换默认单条消息,而不是追加。
|
||||
|
||||
## 完整请求示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/chat/completions" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "YOUR_MODEL",
|
||||
"messages": [
|
||||
{"role":"system","content":"你是影视分镜助理。"},
|
||||
{"role":"user","content":"把这场雨夜追逐拆成 6 个镜头。"}
|
||||
],
|
||||
"temperature": 0.7
|
||||
}'
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "chatcmpl_xxx",
|
||||
"choices": [{"message":{"role":"assistant","content":"1. 全景……"},"finish_reason":"stop"}],
|
||||
"usage": {"prompt_tokens":32,"completion_tokens":95,"total_tokens":127}
|
||||
}
|
||||
```
|
||||
|
||||
## 响应解析、流式与错误
|
||||
|
||||
同步解析只读取 `choices[0].message.content`,并保留顶层 `usage`。当前解析器不把 `tool_calls` 当文本结果;只有工具调用而没有正文时,应由调用方进入工具回合,不能当作普通文本成功。流式分片、结束标记和断线续传由文本任务 SSE 链路处理,不使用此同步 JSON 解析器硬拼。
|
||||
|
||||
常见失败包括模型不存在、上下文超限、字段不受兼容服务支持、额度或速率限制。应保留上游 HTTP 状态和错误正文,不改写为成功。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [OpenAI Chat Completions API Reference](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
|
||||
- [OpenAI Text generation guide](https://developers.openai.com/api/docs/guides/text)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,65 @@
|
||||
# Claude Messages API
|
||||
|
||||
Claude Messages 使用无状态 `messages` 请求生成内容。影策默认创建一条 `user` 消息、设置 `max_tokens: 4096`,并自动添加 `anthropic-version: 2023-06-01`。系统提示使用顶层 `system`,不能伪装成 `system` 角色消息。
|
||||
|
||||
## 接口、鉴权与版本头
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/messages
|
||||
x-api-key: <API_KEY>
|
||||
anthropic-version: 2023-06-01
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
影策的通用渠道中转也可能以 Bearer 方式连接兼容网关;直连 Anthropic 时必须按官方 `x-api-key` 规则配置渠道。版本头由适配器固定添加,Beta 能力需要额外头部时当前插件不会自动猜测。
|
||||
|
||||
## 模型与兼容边界
|
||||
|
||||
模型 ID 必须使用账户和区域实际可用的 Anthropic 模型名。AWS Bedrock、Google Vertex AI 与 Anthropic 原生 API 的鉴权、路径和模型名不同,不能把原生 Messages 插件直接当作云厂商协议使用,除非中间网关已完成协议转换。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
`extra` 可透传 `max_tokens`、`system`、`messages`、`temperature`、`top_p`、`top_k`、`tools`、`tool_choice` 和 `stream`。`extra.messages` 替换默认消息数组。`max_tokens` 是必需的上游字段,未覆盖时影策发送 4096。
|
||||
|
||||
## 请求示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/messages" \
|
||||
-H "x-api-key: <API_KEY>" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "YOUR_CLAUDE_MODEL",
|
||||
"max_tokens": 1200,
|
||||
"system": "你是影视剧本顾问。",
|
||||
"messages": [{"role":"user","content":"指出这一场戏的冲突升级点。"}]
|
||||
}'
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id":"msg_xxx",
|
||||
"type":"message",
|
||||
"role":"assistant",
|
||||
"content":[{"type":"text","text":"冲突分为三个阶段……"}],
|
||||
"stop_reason":"end_turn",
|
||||
"usage":{"input_tokens":31,"output_tokens":148}
|
||||
}
|
||||
```
|
||||
|
||||
## 多内容块、工具与流式
|
||||
|
||||
响应解析遍历 `content[]`,只拼接 `type: text` 的块。`tool_use`、thinking、引用等非文本块不会被误当成正文,但当前统一文本结果也不会保存这些块;需要工具循环或完整块语义时应走专用 Agent 执行层。`stream: true` 的事件流由文本任务链路处理,同步解析器只接收完整 JSON。
|
||||
|
||||
常见错误包括缺少版本头、模型 ID 无权限、交替角色结构不合法、`max_tokens` 缺失或上下文超限。兼容网关可能接受 Bearer 但不接受 `x-api-key`,需要在渠道层确认,不在插件里双发密钥。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [Anthropic Messages API](https://platform.claude.com/docs/en/api/messages)
|
||||
- [Anthropic Messages examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,61 @@
|
||||
# Gemini 图片生成
|
||||
|
||||
Gemini 图片插件调用 `generateContent`,把提示词和参考图组织为一个 `user` content。Data URL 被拆为 `inline_data`,外部 URL 被发送为 `file_data.file_uri`;响应从候选内容中的内联图片解析。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1beta/models/{model}:generateContent
|
||||
x-goog-api-key: <GEMINI_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
通过后端渠道中转时,API Key 必须留在服务端头部,不能放进浏览器 URL。Vertex AI 使用不同 Base URL、OAuth 与资源路径,除非网关转换协议,否则不能直接复用此插件。
|
||||
|
||||
## 模型与输出模式
|
||||
|
||||
只有支持原生图片输出的 Gemini 模型才能返回内联图片。模型 ID 原样放进 URL 并进行路径转义。插件不维护模型白名单、图片尺寸表或计费,因为这些应由官方模型页和渠道模型配置共同确定。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
`aspectRatio -> generationConfig.imageConfig.aspectRatio`,`quality -> generationConfig.imageConfig.imageSize`。`extra` 可替换 `generationConfig`、`safetySettings` 和 `systemInstruction`;替换完整配置时调用方必须保留所需图片输出配置。
|
||||
|
||||
## 文生图请求
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1beta/models/YOUR_MODEL:generateContent" \
|
||||
-H "x-goog-api-key: <GEMINI_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"contents":[{"role":"user","parts":[{"text":"复古科幻电影海报,中文标题清晰"}]}],
|
||||
"generationConfig":{"imageConfig":{"aspectRatio":"3:4","imageSize":"2K"}}
|
||||
}'
|
||||
```
|
||||
|
||||
## 参考图请求
|
||||
|
||||
```json
|
||||
{
|
||||
"contents":[{"role":"user","parts":[
|
||||
{"text":"保持人物一致,改为冬季服装"},
|
||||
{"inline_data":{"mime_type":"image/png","data":"<BASE64>"}}
|
||||
]}]
|
||||
}
|
||||
```
|
||||
|
||||
外部 URL 会被构造成 `file_data.file_uri`。该 URI 是否允许任意 HTTP URL 取决于上游;如果官方只接受 Files API URI,必须先上传文件,当前插件不会自动代传。
|
||||
|
||||
## 响应解析与安全
|
||||
|
||||
解析器遍历 `candidates[].content.parts[]`,识别 `inlineData` 或 `inline_data`,再生成 `data:<mime>;base64,...`。只有文本、finishReason 或安全反馈而没有内联图片时请求会失败。大图片不能进入 localStorage,应立即转存到影策资源存储。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [Gemini native image generation](https://ai.google.dev/gemini-api/docs/image-generation)
|
||||
- [Gemini generateContent API](https://ai.google.dev/api/generate-content)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,72 @@
|
||||
# Gemini Veo 长任务
|
||||
|
||||
Veo 插件通过 `predictLongRunning` 创建 Google long-running operation,再查询 operation 直到完成。提示词位于 `instances[0]`,当前最多取第一张参考图并以内联 Base64 发送。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1beta/models/{model}:predictLongRunning
|
||||
GET {channel_base_url}/v1beta/{operation_name}
|
||||
x-goog-api-key: <GEMINI_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
API Key 必须通过后端头部中转,不能放入浏览器 URL。Vertex AI Veo 的 OAuth、项目、区域和发布者路径不同,不能直接套用 Gemini Developer API Base URL。
|
||||
|
||||
## 模型与能力限制
|
||||
|
||||
模型 ID 原样放入创建路径。允许时长、比例、分辨率、音频、参考图类型、并发、结果保留期和计费以 Google 官方模型页及账户区域为准。插件不维护白名单。当前 adapter 只使用第一张图片;视频/音频参考和水印不发送。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
实际映射为 `aspectRatio`、`durationSeconds`、`resolution`、`generateAudio`,均放入 `parameters`。参考图固定为 `instances[0].image.inlineData`;没有 data URL 时 MIME 和数据会退化为空/通用值,因此远程 URL 应先下载并转为 data URL。
|
||||
|
||||
## 创建任务示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1beta/models/YOUR_VEO_MODEL:predictLongRunning" \
|
||||
-H "x-goog-api-key: <GEMINI_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"instances":[{
|
||||
"prompt":"夜间列车驶过雪原,航拍镜头缓慢下降",
|
||||
"image":{"inlineData":{"mimeType":"image/png","data":"<BASE64>"}}
|
||||
}],
|
||||
"parameters":{"aspectRatio":"16:9","durationSeconds":8,"resolution":"720p","generateAudio":true}
|
||||
}'
|
||||
```
|
||||
|
||||
## Operation 轮询与结果
|
||||
|
||||
创建响应返回 operation `name`。影策会移除开头斜杠,并在缺少 `operations/` 前缀时自动补齐,然后请求 `/v1beta/operations/...`。
|
||||
|
||||
```json
|
||||
{"name":"operations/op_xxx","done":false}
|
||||
```
|
||||
|
||||
该插件使用独立的 Google LRO parser,不经过通用 `status/state` 兼容分支:`done:false` 视为处理中,顶层 `error` 视为失败,`done:true` 后从 `response.generatedVideos[]` 或 `response.generateVideoResponse.generatedSamples[]` 的 `video.uri` 读取视频。成功但缺少视频地址会作为真实错误返回,不把 operation 完成误报为媒体已保存。
|
||||
|
||||
```json
|
||||
{
|
||||
"name":"operations/op_xxx",
|
||||
"done":true,
|
||||
"response":{
|
||||
"generateVideoResponse":{
|
||||
"generatedSamples":[
|
||||
{"video":{"uri":"https://generativelanguage.googleapis.com/v1beta/files/..."}}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [Gemini API video generation with Veo](https://ai.google.dev/gemini-api/docs/video)
|
||||
- [Google long-running operations](https://ai.google.dev/api/files#method:-operations.get)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,60 @@
|
||||
# xAI Grok Images
|
||||
|
||||
Grok Images 插件使用 OpenAI 风格的图片生成路径,但请求字段按 xAI 图片协议构造:`aspect_ratio`、`resolution`,并在有参考图时发送单个 `image`。它不是 OpenAI Images 插件的别名。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/images/generations
|
||||
Authorization: Bearer <XAI_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与支持边界
|
||||
|
||||
模型名由 xAI 账户当前可用模型决定。插件不写死模型、价格、并发或内容限制。当前实现只发送第一张参考图;多参考图、编辑专用路径、mask 和批量生成没有实现,不能因上游可能支持就展示为已支持。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
实际构造为:`aspectRatio -> aspect_ratio`,为空时默认 `1:1`;`quality -> resolution`,为空时默认 `2k`;`images[0] -> image`。`imageCount`、`resolution` 平台字段及其他图片不会发送。
|
||||
|
||||
## 文生图请求
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/images/generations" \
|
||||
-H "Authorization: Bearer <XAI_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_GROK_IMAGE_MODEL",
|
||||
"prompt":"太空港的清晨,宽银幕概念设计",
|
||||
"aspect_ratio":"16:9",
|
||||
"resolution":"2k"
|
||||
}'
|
||||
```
|
||||
|
||||
## 单图参考请求
|
||||
|
||||
```json
|
||||
{
|
||||
"model":"YOUR_GROK_IMAGE_MODEL",
|
||||
"prompt":"保持主体轮廓,改成铅笔分镜风格",
|
||||
"aspect_ratio":"16:9",
|
||||
"resolution":"2k",
|
||||
"image":"https://example.com/reference.png"
|
||||
}
|
||||
```
|
||||
|
||||
## 响应与错误
|
||||
|
||||
插件按 OpenAI Images 风格解析 `data[]` 中的 `url`、`b64_json` 或 `data`。如果 xAI 的实际响应结构发生变化或只返回异步任务,当前解析会失败而不是伪造结果。素材不可达、比例/分辨率不受模型支持、模型无权限和审核拒绝应原样暴露。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [xAI Image Generation](https://docs.x.ai/docs/guides/image-generation)
|
||||
- [xAI API Reference](https://docs.x.ai/docs/api-reference)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,59 @@
|
||||
# MiniMax 视频生成
|
||||
|
||||
MiniMax 视频插件使用 `/v2/video_generation` 创建异步任务。它同时发送顶层 `prompt` 和结构化 `content[]`:文本为 text item,参考图片为带 `reference_image` role 的 image URL item。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v2/video_generation
|
||||
GET {channel_base_url}/v2/query/video_generation/{task_id}
|
||||
Authorization: Bearer <MINIMAX_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与约束
|
||||
|
||||
当前 MiniMax V2 官方文档列出 `MiniMax-H3`,时长为 4–15 秒整数,分辨率为 `768P` 或 `2K`,比例支持 `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。当前 adapter 默认 6 秒;模型名和其他限制仍以账户实际开放能力为准。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
每张图片构造为 `content` 中的 `image_url` item。`extra` 可覆盖 `model`、`prompt`、`duration`、`content`、`resolution`、`aspect_ratio`。参考视频、参考音频、音频生成和水印当前不发送。
|
||||
|
||||
## 创建任务示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v2/video_generation" \
|
||||
-H "Authorization: Bearer <MINIMAX_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_MINIMAX_VIDEO_MODEL",
|
||||
"prompt":"保持角色一致,人物转身看向镜头",
|
||||
"duration":6,
|
||||
"content":[
|
||||
{"type":"text","text":"保持角色一致,人物转身看向镜头"},
|
||||
{"type":"image_url","image_url":{"url":"https://example.com/character.png"},"role":"reference_image"}
|
||||
],
|
||||
"resolution":"720P",
|
||||
"aspect_ratio":"16:9"
|
||||
}'
|
||||
```
|
||||
|
||||
## 查询、文件与结果
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v2/query/video_generation/task_xxx" \
|
||||
-H "Authorization: Bearer <MINIMAX_API_KEY>"
|
||||
```
|
||||
|
||||
当前 V2 官方成功响应在 `task.content.url` 返回视频地址,通用 parser 会先合并 `task`,再从 `content.url` 提取结果。官方仅允许查询最近 7 天任务,视频 URL 有时效,应立即转存。当前 adapter 尚未发送参考视频、参考音频、`callback_url` 或 `aigc_watermark`;虽然 V2 上游支持这些字段,影策不能宣称已支持。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [MiniMax 创建视频生成任务](https://platform.minimaxi.com/docs/api-reference/video-generation-v2-create)
|
||||
- [MiniMax 查询任务](https://platform.minimaxi.com/docs/api-reference/video-generation-v2-query)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,57 @@
|
||||
# NewAPI 媒体任务协议
|
||||
|
||||
该插件把多模态参考素材统一包装为 `input.media[]`,把分辨率、比例、时长和水印放入 `parameters`,使用 `/v1/videos` 创建与查询异步任务。它是影策适配的渠道合同,不是某一家模型厂商的官方协议。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/videos
|
||||
GET {channel_base_url}/v1/videos/{task_id}
|
||||
Authorization: Bearer <CHANNEL_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型、计费与素材上限
|
||||
|
||||
模型清单、计费、时长范围、素材数量和单文件大小均由当前 NewAPI 部署及其上游渠道决定。此插件不能把某个渠道的 Seedance、Veo 或 Kling 限制推广给所有部署。管理员应在模型配置中记录经过实际调用验证的模型 ID。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
实际映射:图片 -> `{type:"reference_image"}`,视频 -> `{type:"reference_video"}`,音频 -> `{type:"reference_voice"}`;均放入 `input.media`。默认 `resolution=720P`、`ratio=16:9`、`duration=5`。只有 `watermark=true` 时才发送水印字段;`generateAudio` 当前不发送。
|
||||
|
||||
## 多模态创建示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/videos" \
|
||||
-H "Authorization: Bearer <CHANNEL_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_CHANNEL_MODEL",
|
||||
"input":{
|
||||
"prompt":"保持人物外观,动作参考视频,节奏参考声音",
|
||||
"media":[
|
||||
{"type":"reference_image","url":"https://example.com/character.png"},
|
||||
{"type":"reference_video","url":"https://example.com/action.mp4"},
|
||||
{"type":"reference_voice","url":"https://example.com/beat.mp3"}
|
||||
]
|
||||
},
|
||||
"parameters":{"resolution":"720P","ratio":"16:9","duration":8,"watermark":false}
|
||||
}'
|
||||
```
|
||||
|
||||
## 响应、轮询与排错
|
||||
|
||||
创建响应必须在顶层、`task` 或 `data` 中包含 `id/task_id/taskId/request_id`。查询使用 URL 编码后的任务 ID。完成时解析视频数组或 `video_url/videoUrl/result_url/url`。如果渠道返回自己的深层字段,必须新增专属解析,不能把空结果标记成功。
|
||||
|
||||
常见问题包括渠道未映射模型、素材 URL 无法由上游下载、媒体类型命名不被该部署接受、默认参数超出模型范围。先检查部署版本和渠道日志,再修改适配器;不要反复添加兼容别名掩盖协议差异。
|
||||
|
||||
## 官方资料与边界
|
||||
|
||||
- NewAPI 项目与部署文档由具体运维方提供;本页以影策当前 adapter 的请求事实为准。
|
||||
- 上游模型官方文档只用于确认模型自身能力,不能替代 NewAPI 网关字段合同。
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,63 @@
|
||||
# NewAPI Video Generations
|
||||
|
||||
该插件使用 `/v1/video/generations` JSON 异步接口,直接发送图片、视频和音频 URL 数组。它适用于实现这一特定路径和字段集合的 NewAPI 渠道,不等同于 `/v1/videos` 媒体任务协议。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/video/generations
|
||||
GET {channel_base_url}/v1/video/generations/{task_id}
|
||||
Authorization: Bearer <CHANNEL_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与约束来源
|
||||
|
||||
可用模型、每种素材上限、时长范围、音频能力、分辨率和计费由该 NewAPI 部署映射的上游决定。插件没有通用白名单。用户示例中的 Seedance 限制只可用于实际连接该服务且管理员验证一致的渠道。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
实际字段为 `model`、`prompt`、`seconds`、`aspect_ratio`、可选 `resolution`、`generate_audio`、`image_urls`、`video_urls`、`audio_urls`。时长默认 6 秒并发送为字符串,比例默认 `16:9`。水印当前不发送。
|
||||
|
||||
## 完整多模态请求
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/video/generations" \
|
||||
-H "Authorization: Bearer <CHANNEL_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_VIDEO_MODEL",
|
||||
"prompt":"人物参考第一张图,镜头运动参考视频,节奏跟随音频",
|
||||
"seconds":"10",
|
||||
"aspect_ratio":"9:16",
|
||||
"resolution":"720p",
|
||||
"generate_audio":true,
|
||||
"image_urls":["https://example.com/subject.png"],
|
||||
"video_urls":["https://example.com/motion.mp4"],
|
||||
"audio_urls":["https://example.com/beat.mp3"]
|
||||
}'
|
||||
```
|
||||
|
||||
## 任务状态与结果
|
||||
|
||||
```json
|
||||
{"task_id":"task_xxx","status":"queued"}
|
||||
```
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/video/generations/task_xxx" \
|
||||
-H "Authorization: Bearer <CHANNEL_API_KEY>"
|
||||
```
|
||||
|
||||
状态会归一为等待、处理中、成功或失败。成功结果可来自视频数组或常见顶层 URL;当前没有取消路径。任务失败后的退款、额度释放和结果保留期属于部署方账务合同,影策不会在没有接口证据时承诺。
|
||||
|
||||
## 官方资料与边界
|
||||
|
||||
- 以连接的 NewAPI 部署接口文档、版本和渠道配置为准。
|
||||
- 素材必须能被网关和最终上游访问;网关可访问不代表最终供应商可访问。
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,66 @@
|
||||
# OpenAI Videos 兼容协议
|
||||
|
||||
该插件实现 `/v1/videos` 异步视频合同:以 multipart 创建任务,取得任务 ID 后查询同一路径下的任务资源。它用于 Sora/OpenAI Videos 风格渠道;模型、尺寸、时长、价格和保留期由实际渠道决定。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/videos
|
||||
GET {channel_base_url}/v1/videos/{task_id}
|
||||
Authorization: Bearer <API_KEY>
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
## 模型与能力边界
|
||||
|
||||
模型名必须是部署服务实际开放的视频模型。插件不把任意 `sora-*` 或 `sd-*` 名称视为可用,也不提供价格表。当前实现支持文生视频和单组参考图输入,不发送参考视频、参考音频、独立音频开关或水印。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
`duration -> seconds`,发送为十进制字符串;`aspectRatio -> size`,这里应填写上游尺寸而不是只写 `16:9`;`images -> input_reference` multipart 部件。空字段不发送。
|
||||
|
||||
## 文生视频示例
|
||||
|
||||
```bash
|
||||
curl -X POST "{channel_base_url}/v1/videos" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-F "model=YOUR_VIDEO_MODEL" \
|
||||
-F "prompt=清晨薄雾中的竹林,镜头缓慢向前推进" \
|
||||
-F "seconds=8" \
|
||||
-F "size=1280x720"
|
||||
```
|
||||
|
||||
## 图片参考示例
|
||||
|
||||
```bash
|
||||
curl -X POST "{channel_base_url}/v1/videos" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-F "model=YOUR_VIDEO_MODEL" \
|
||||
-F "prompt=保持参考图人物一致,镜头从中景推进到特写" \
|
||||
-F "seconds=8" \
|
||||
-F "size=720x1280" \
|
||||
-F "input_reference=@character.png"
|
||||
```
|
||||
|
||||
## 创建、轮询与下载
|
||||
|
||||
```json
|
||||
{"id":"task_xxx","status":"queued"}
|
||||
```
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/videos/task_xxx" -H "Authorization: Bearer <API_KEY>"
|
||||
```
|
||||
|
||||
完成响应可在顶层或嵌套对象提供 `url`、`video_url`、`result_url` 或视频数组。失败消息从 `message`、`error`、`fail_reason` 提取。当前插件没有取消接口,也不会自动删除上游任务;轮询间隔和下载有效期必须服从渠道说明。
|
||||
|
||||
## 官方与兼容资料
|
||||
|
||||
- [OpenAI Videos API reference](https://developers.openai.com/api/reference/resources/videos)
|
||||
- 若渠道是 NewAPI 或其他兼容实现,还必须核对该部署的版本说明;路径相同不等于字段和模型完全一致。
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,57 @@
|
||||
# Novita 视频异步 API
|
||||
|
||||
Novita 视频插件使用 `/v3/video/create` 创建任务,以 query 参数携带任务 ID 查询统一异步结果。模型字段名为 `model_name`,不是通用 `model`。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v3/video/create
|
||||
GET {channel_base_url}/v3/async/task-result?task_id={id}
|
||||
Authorization: Bearer <NOVITA_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与约束
|
||||
|
||||
Novita 聚合多个视频模型,不同 `model_name` 的字段、图片要求、时长、比例和价格可能不同。当前插件只提供共同子集:提示词、单张参考图、时长和比例;不能据此认定所有 Novita 视频模型都接受相同参数。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
`model -> model_name`,`images[0] -> image_url`,时长默认 5 秒,比例默认 `16:9`。`resolution`、参考视频、参考音频、音频生成和水印当前不发送。
|
||||
|
||||
## 创建请求示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v3/video/create" \
|
||||
-H "Authorization: Bearer <NOVITA_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model_name":"YOUR_NOVITA_VIDEO_MODEL",
|
||||
"prompt":"产品在黑色展台上缓慢旋转,轮廓光",
|
||||
"duration":5,
|
||||
"aspect_ratio":"16:9",
|
||||
"image_url":"https://example.com/product.png"
|
||||
}'
|
||||
```
|
||||
|
||||
## 查询与下载
|
||||
|
||||
创建响应应返回 `task_id/id`。查询时任务 ID会进行 URL query 编码:
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v3/async/task-result?task_id=task_xxx" \
|
||||
-H "Authorization: Bearer <NOVITA_API_KEY>"
|
||||
```
|
||||
|
||||
成功结果由统一 parser 从视频数组或 URL 字段读取。Novita 若针对某模型返回独特嵌套结构,应建立该模型 fixture,而不是继续扩展全局模糊字段。当前没有取消接口;任务退款和结果保留期以 Novita 当前规则为准。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [Novita Unified Video Generation](https://novita.ai/docs/api-reference/reference-unified-video-generation)
|
||||
- [Novita Task Result Query](https://novita.ai/docs/api-reference/model-apis-task-result)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,50 @@
|
||||
# OpenAI Audio Speech
|
||||
|
||||
该插件调用 OpenAI 风格的同步文字转语音接口,把影策提示词映射为 `input`。当前只发送模型与文本,声音、格式、语速和其他 TTS 选项尚未纳入 adapter。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/audio/speech
|
||||
Authorization: Bearer <API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型、声音与输出格式
|
||||
|
||||
模型、voice、格式、单次文本长度、流式能力和价格以 OpenAI 或兼容渠道实际文档为准。当前影策 metadata 没有声明参数表,这意味着只有 `model` 和 `prompt` 的内部映射稳定,不意味着上游没有必填 `voice`。若上游要求 voice,管理员必须先扩展 adapter,不能依赖未白名单的字段自动透传。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
实际请求正文固定为:
|
||||
|
||||
```json
|
||||
{"model":"YOUR_TTS_MODEL","input":"请在午夜前离开这座城市。"}
|
||||
```
|
||||
|
||||
完整上游常见请求参考:
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/audio/speech" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model":"YOUR_TTS_MODEL","voice":"YOUR_VOICE","input":"请在午夜前离开这座城市。","response_format":"mp3"}' \
|
||||
--output speech.mp3
|
||||
```
|
||||
|
||||
第二个示例包含当前 adapter 尚未发送的 `voice` 和 `response_format`,用于说明必须补齐的协议字段。
|
||||
|
||||
## 响应与当前实现差异
|
||||
|
||||
OpenAI 官方 Speech API 通常直接返回音频二进制流;当前 `parseAudioResponse` 却按 JSON 中的 `url/audio_url/data` 解析。因此本插件当前更适合“返回音频 URL JSON”的兼容渠道,不能宣称已经正确处理 OpenAI 官方二进制响应。直连官方服务前必须增加二进制响应合同、MIME/文件名处理和资源保存测试。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [OpenAI Text-to-speech guide](https://developers.openai.com/api/docs/guides/text-to-speech)
|
||||
- [OpenAI Audio Speech reference](https://developers.openai.com/api/reference/resources/audio/subresources/speech/methods/create)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,73 @@
|
||||
# OpenAI Images
|
||||
|
||||
OpenAI Images 插件实现 JSON 文生图请求,并解析 OpenAI Images 风格的 `data[]` 响应。上游官方还提供 multipart 图像编辑接口,但当前影策适配器的创建路径只构造 `/v1/images/generations`;详情中列出编辑接口是为了说明协议能力,不代表当前画布已发送编辑请求。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/images/generations
|
||||
Authorization: Bearer <API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
官方编辑接口为 `POST /v1/images/edits`、`multipart/form-data`。当前适配器未在有参考图时切换到该路径,这是明确的实现缺口。
|
||||
|
||||
## 模型、尺寸与质量
|
||||
|
||||
模型、允许尺寸、质量枚举、单次张数和计费会随上游服务变化,插件不维护可能过期的白名单。渠道若是 OpenAI 兼容实现,必须分别验证它是否支持 `n`、`quality`、`background`、`output_format` 和 Base64 响应。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
当前实现:`imageCount -> n`、`aspectRatio -> size`、`quality -> quality`;`extra` 可透传 `size`、`quality`、`background`、`response_format`、`output_format`、`style`、`n`。`images` 和 `resolution` 当前不会进入文生图请求。
|
||||
|
||||
## 文生图请求
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/images/generations" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_IMAGE_MODEL",
|
||||
"prompt":"雨夜便利店门口,青绿色霓虹,电影剧照",
|
||||
"size":"1536x1024",
|
||||
"quality":"high",
|
||||
"n":1
|
||||
}'
|
||||
```
|
||||
|
||||
URL 响应:
|
||||
|
||||
```json
|
||||
{"created":1780000000,"data":[{"url":"https://cdn.example/generated.png"}]}
|
||||
```
|
||||
|
||||
Base64 响应:
|
||||
|
||||
```json
|
||||
{"created":1780000000,"data":[{"b64_json":"iVBORw0KGgo..."}]}
|
||||
```
|
||||
|
||||
解析器遍历 `data[]`,优先识别 `url`,也接受 `b64_json` 或 `data`。URL 应立即下载;裸 Base64 会转为 `data:image/png;base64,...`,已带 data URL 前缀的值保持不变。若渠道使用 WebP/JPEG Base64 且响应不返回 MIME,当前协议无法可靠推断格式,应优先请求 URL 或补充带 MIME 的响应合同。
|
||||
|
||||
## 图像编辑参考请求
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/images/edits" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-F "model=YOUR_IMAGE_MODEL" \
|
||||
-F "image=@reference.png" \
|
||||
-F "prompt=保持人物一致,改成雨夜街道"
|
||||
```
|
||||
|
||||
该示例是上游协议参考;在影策中使用前必须补 multipart 构造、参考图数量与 MIME 校验、编辑响应测试。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [OpenAI Image generation guide](https://developers.openai.com/api/docs/guides/image-generation)
|
||||
- [OpenAI Images API reference](https://developers.openai.com/api/reference/resources/images)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,71 @@
|
||||
# OpenAI Responses API
|
||||
|
||||
Responses API 是 OpenAI 当前统一的文本与工具调用接口,输入使用 `input`,可同时承载简单字符串、结构化消息和工具回合。影策默认发送字符串提示词,并从同步响应的 `output_text` 或 `output[]` 中提取文本。
|
||||
|
||||
## 接口、鉴权与请求模式
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/responses
|
||||
Authorization: Bearer <API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与能力发现
|
||||
|
||||
插件不硬编码模型表。请使用渠道模型管理中已验证支持 Responses API 的模型 ID。兼容服务即使实现 `/v1/responses`,也可能不支持内置工具、状态延续、结构化输出或多模态输入,能力必须以该服务文档和实际探测为准。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
`extra` 可透传 `input`、`instructions`、`temperature`、`top_p`、`max_output_tokens`、`stream`、`tools` 和 `text`。`extra.input` 会替换默认字符串;复杂输入必须使用上游规定的 item 结构,不应把 Chat Completions 的 `messages` 原样塞进来。
|
||||
|
||||
## 请求示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/responses" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "YOUR_MODEL",
|
||||
"instructions": "输出可直接拍摄的镜头清单。",
|
||||
"input": "一名女孩在停电的商场里寻找出口。",
|
||||
"max_output_tokens": 1200
|
||||
}'
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "resp_xxx",
|
||||
"status": "completed",
|
||||
"output_text": "镜头 1……",
|
||||
"usage": {"input_tokens":28,"output_tokens":174,"total_tokens":202}
|
||||
}
|
||||
```
|
||||
|
||||
## 结构化输入示例
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "YOUR_MODEL",
|
||||
"input": [{
|
||||
"role": "user",
|
||||
"content": [{"type":"input_text","text":"分析这段剧情的节奏问题"}]
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
## 响应解析与限制
|
||||
|
||||
解析器优先读取顶层 `output_text`;缺失时遍历 `output`,尝试读取 item 的 `text` 或 `content`,并保留 `usage`。当前实现没有完整执行 function call、computer use、file search 等输出 item,也不通过 `previous_response_id` 自动续接状态。需要这些能力时必须在 Agent 调用链中显式实现,不能只靠文档声称支持。
|
||||
|
||||
流式响应由文本事件链路处理。上游拒绝、模型不支持、输入结构错误、输出 token 超限和工具参数校验失败均应作为失败返回。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [OpenAI Responses API Reference](https://developers.openai.com/api/reference/resources/responses/methods/create)
|
||||
- [OpenAI Responses migration guide](https://developers.openai.com/api/docs/guides/migrate-to-responses)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,61 @@
|
||||
# 火山方舟图片生成
|
||||
|
||||
本插件面向火山方舟 Ark 图片生成 JSON 接口。提示词直接发送,参考图数组映射到 `image`,连续生成和水印参数可从模型扩展字段透传。
|
||||
|
||||
## 接口、鉴权与区域
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/api/v3/images/generations
|
||||
Authorization: Bearer <ARK_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Base URL、鉴权方式和可用模型受火山方舟控制台、区域与接入方式影响。若使用 AK/SK 签名网关,应由渠道层完成签名,不能把 Secret Key 写入插件文档或浏览器。
|
||||
|
||||
## 模型与支持边界
|
||||
|
||||
模型 ID、尺寸范围与能力以火山方舟控制台为准。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
当前实现:`aspectRatio -> size`,所有 `images -> image[]`;`extra` 可透传 `size`、`sequential_image_generation`、`sequential_image_generation_options`、`watermark`。`imageCount`、`quality` 与 `resolution` 没有通用映射,必须按模型接口另行适配。
|
||||
|
||||
## 文生图示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/api/v3/images/generations" \
|
||||
-H "Authorization: Bearer <ARK_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_ARK_ENDPOINT_OR_MODEL",
|
||||
"prompt":"古城屋顶追逐,低机位,动态构图",
|
||||
"size":"2048x1152",
|
||||
"watermark":false
|
||||
}'
|
||||
```
|
||||
|
||||
## 参考图示例
|
||||
|
||||
```json
|
||||
{
|
||||
"model":"YOUR_ARK_ENDPOINT_OR_MODEL",
|
||||
"prompt":"保持人物服装和发型,生成侧面中景",
|
||||
"image":["https://example.com/character.png"],
|
||||
"size":"2048x1152"
|
||||
}
|
||||
```
|
||||
|
||||
## 响应解析与限制
|
||||
|
||||
响应按 `data[]` 图片数组解析,元素需包含 `url`、`b64_json` 或 `data`。当前插件没有为 Ark 特有错误码、任务模式或内容过滤结果做专属解包;渠道返回非兼容结构时会明确失败。模型尺寸、参考图数量、序列图上限、水印和计费以控制台当前模型说明为准,不能从插件默认值推断。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [火山方舟视觉模型 API 文档](https://www.volcengine.com/docs/82379)
|
||||
- [火山方舟 API 接入与鉴权文档](https://www.volcengine.com/docs/82379/1263279)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,57 @@
|
||||
# 火山方舟视频任务
|
||||
|
||||
本插件使用 Ark Contents Generations Tasks 异步接口。提示词和参考图组成 `content[]`;比例、分辨率、时长、音频和水印位于顶层任务参数。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/api/v3/contents/generations/tasks
|
||||
GET {channel_base_url}/api/v3/contents/generations/tasks/{task_id}
|
||||
Authorization: Bearer <ARK_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与约束
|
||||
|
||||
模型通常对应控制台可用模型或 endpoint ID。允许时长、分辨率、画幅、参考图数量、是否可生成音频及计费由具体模型决定。插件默认 5 秒、`16:9`、`720p`,默认值不是上游能力承诺。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
每张图片构造为 `{"type":"image_url","image_url":{"url":"..."},"role":"reference_image"}`。当前不发送参考视频与参考音频;`generate_audio` 和 `watermark` 只在 true 时发送。
|
||||
|
||||
## 创建任务示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/api/v3/contents/generations/tasks" \
|
||||
-H "Authorization: Bearer <ARK_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_ARK_VIDEO_MODEL",
|
||||
"content":[
|
||||
{"type":"text","text":"保持人物一致,镜头缓慢环绕"},
|
||||
{"type":"image_url","image_url":{"url":"https://example.com/subject.png"},"role":"reference_image"}
|
||||
],
|
||||
"ratio":"16:9",
|
||||
"resolution":"720p",
|
||||
"duration":5,
|
||||
"generate_audio":true,
|
||||
"watermark":false
|
||||
}'
|
||||
```
|
||||
|
||||
## 查询、状态与结果
|
||||
|
||||
创建响应任务 ID 由统一解析器从顶层、`task` 或 `data` 提取。查询成功后读取视频数组或常见 URL 字段。若 Ark 把结果放在其他嵌套路径,必须用真实 fixture 增加专属解析,不允许只根据 `completed` 返回空成功。
|
||||
|
||||
任务失败可能来自 endpoint 不可用、素材下载失败、参数组合不受支持、内容审核、并发或额度限制。上游 request ID 应保留用于排查,API Key 和素材正文不得进入日志。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [火山方舟视频生成 API](https://www.volcengine.com/docs/82379)
|
||||
- [火山方舟内容生成任务文档](https://www.volcengine.com/docs/82379/1520757)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,57 @@
|
||||
# 即梦官方图片异步 API
|
||||
|
||||
本插件使用即梦视觉异步任务模式:提交任务取得 `task_id`,再以相同 `req_key` 查询结果。接口由火山引擎视觉服务的 AK/SK 签名体系保护,不是 Bearer 兼容接口。
|
||||
|
||||
## 接口与签名
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
逻辑操作名为 `CVSync2AsyncSubmitTask` 和 `CVSync2AsyncGetResult`。实际主机、Query 参数、Service/Region 与签名头由渠道的火山签名实现负责;不能只对这两个字符串执行普通 HTTP POST。
|
||||
|
||||
## 模型与 req_key
|
||||
|
||||
影策模型 ID 映射为 `req_key`,必须与已开通的即梦能力完全一致。插件不提供可能过期的 `req_key` 白名单,也不根据名字推断文生图、图生图或版本能力。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
当前实现发送 `req_key`、`prompt`,有参考图时发送 `image_urls`。`extra` 可覆盖 `req_key`、`prompt`、`image_urls`、`seed`、`width`、`height`。平台的 `aspectRatio`、`quality`、`resolution` 和 `imageCount` 没有自动转换。
|
||||
|
||||
## 创建请求正文
|
||||
|
||||
```json
|
||||
{
|
||||
"req_key":"YOUR_JIMENG_REQ_KEY",
|
||||
"prompt":"悬疑短剧分镜,楼道尽头的逆光人影",
|
||||
"image_urls":["https://example.com/reference.png"],
|
||||
"width":1536,
|
||||
"height":1024,
|
||||
"seed":42
|
||||
}
|
||||
```
|
||||
|
||||
创建响应至少需要可识别任务 ID:
|
||||
|
||||
```json
|
||||
{"data":{"task_id":"task_xxx"}}
|
||||
```
|
||||
|
||||
## 轮询请求与结果
|
||||
|
||||
```json
|
||||
{"req_key":"YOUR_JIMENG_REQ_KEY","task_id":"task_xxx"}
|
||||
```
|
||||
|
||||
轮询响应从顶层、`task` 或 `data` 读取状态,并按图片类型提取 `images`、`image_url`、`imageUrl`、`result_url` 或 `url`;图片数组可包含 URL 字符串或对象。若结果只出现在即梦其他专属嵌套字段中,需要补 fixture 和专属解析,不能把“拿到 completed”当作已经保存图片。
|
||||
|
||||
## 错误与排查
|
||||
|
||||
签名时间偏差、Region/Service 错误、`req_key` 未开通、素材不可下载、宽高不支持和内容审核都会导致失败。日志可以记录请求 ID 和错误码,不得记录 Secret Key、完整签名或私有素材 data URL。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [火山引擎视觉智能开放平台](https://www.volcengine.com/docs/85621)
|
||||
- [火山引擎签名方法](https://www.volcengine.com/docs/6369/67269)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,55 @@
|
||||
# 即梦官方视频异步 API
|
||||
|
||||
即梦视频插件使用 `CVSync2AsyncSubmitTask` 创建、`CVSync2AsyncGetResult` 查询,并由渠道的火山 AK/SK 实现完成签名。创建与查询均为 POST,模型能力键通过 `req_key` 传递。
|
||||
|
||||
## 接口与签名
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
这两个名称是视觉服务 Action,实际 URL、Query、Region、Service、时间戳和签名头必须按火山官方签名规范生成。把 AK/SK 放入 JSON 或浏览器会造成密钥泄漏。
|
||||
|
||||
## 模型、版本与素材限制
|
||||
|
||||
`req_key` 必须是账户已开通的即梦视频能力键。每个版本对首帧/尾帧、参考图数量、时长、比例和分辨率的约束不同;插件不维护一张可能过期的模型表。当前只映射参考图片,不发送参考视频、音频、生成音频或水印。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
基础请求包含 `req_key`、`prompt`、可选 `image_urls`。`extra` 可透传并覆盖 `req_key`、`prompt`、`image_urls`、`duration`、`ratio`、`resolution`,适合管理员按已确认的官方版本补参数。
|
||||
|
||||
## 创建任务正文
|
||||
|
||||
```json
|
||||
{
|
||||
"req_key":"YOUR_JIMENG_VIDEO_REQ_KEY",
|
||||
"prompt":"保持参考人物,镜头从全景移动到近景",
|
||||
"image_urls":["https://example.com/subject.png"],
|
||||
"duration":5,
|
||||
"ratio":"16:9",
|
||||
"resolution":"720p"
|
||||
}
|
||||
```
|
||||
|
||||
创建响应:
|
||||
|
||||
```json
|
||||
{"data":{"task_id":"task_xxx"}}
|
||||
```
|
||||
|
||||
查询正文:
|
||||
|
||||
```json
|
||||
{"req_key":"YOUR_JIMENG_VIDEO_REQ_KEY","task_id":"task_xxx"}
|
||||
```
|
||||
|
||||
## 轮询、结果与失败
|
||||
|
||||
轮询响应由统一异步 parser 读取状态和视频 URL。查询必须继续携带创建时的模型 `req_key`,不能只传任务 ID。签名时间偏差、Region 错误、能力未开通、素材 URL 失效、参数不匹配和审核均会失败。当前没有取消接口,失败后的额度处理以官方账务为准。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [火山引擎视觉智能开放平台](https://www.volcengine.com/docs/85621)
|
||||
- [火山引擎 API 签名方法](https://www.volcengine.com/docs/6369/67269)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,55 @@
|
||||
# xAI 视频生成
|
||||
|
||||
xAI 视频插件创建异步 generation request,再按 request ID 查询。单张参考图发送为 `image`,多张参考图发送为 `reference_images`;时长、画幅和分辨率使用 xAI 风格字段。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/videos/generations
|
||||
GET {channel_base_url}/v1/videos/{request_id}
|
||||
Authorization: Bearer <XAI_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与当前支持
|
||||
|
||||
模型 ID、允许时长、比例、分辨率、参考图数量、审核规则和计费以 xAI 控制台及官方文档为准。当前 adapter 默认 6 秒、`16:9`、`720p`。视频参考、音频参考、音频生成开关和水印均不会发送。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
单图结构:`"image":{"url":"..."}`;多图结构:`"reference_images":[{"url":"..."}]`。URL 或 data URL 是否被具体模型接受,应在调用前验证。
|
||||
|
||||
## 请求示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/videos/generations" \
|
||||
-H "Authorization: Bearer <XAI_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_XAI_VIDEO_MODEL",
|
||||
"prompt":"雨夜都市追逐,手持摄影,真实运动模糊",
|
||||
"duration":8,
|
||||
"aspect_ratio":"16:9",
|
||||
"resolution":"720p",
|
||||
"image":{"url":"https://example.com/character.png"}
|
||||
}'
|
||||
```
|
||||
|
||||
## 创建、查询与下载
|
||||
|
||||
创建响应需包含 `request_id` 或其他统一解析器支持的任务字段。查询完成后从视频数组或 `video_url/result_url/url` 读取媒体。当前没有 cancel adapter;关闭影策弹窗不会取消上游生成。结果 URL 应及时转存,不能假定永久有效。
|
||||
|
||||
## 错误处理
|
||||
|
||||
模型权限、无效尺寸、参考素材不可访问、内容审核、速率或余额限制必须作为真实失败展示。若官方响应结构与通用解析器不一致,应补 xAI 专属 parser 和 fixture 测试,而不是继续堆叠模糊字段猜测。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [xAI Video Generation guide](https://docs.x.ai/docs/guides/video-generation)
|
||||
- [xAI API Reference](https://docs.x.ai/docs/api-reference)
|
||||
|
||||
{{CONTRACT}}
|
||||
@@ -0,0 +1,113 @@
|
||||
package protocol
|
||||
|
||||
import (
|
||||
"embed"
|
||||
"fmt"
|
||||
"strings"
|
||||
)
|
||||
|
||||
//go:embed docs/*.md
|
||||
var builtinDocumentationFS embed.FS
|
||||
|
||||
func attachDocumentation(info *Metadata) {
|
||||
if info == nil || strings.TrimSpace(info.Documentation) != "" {
|
||||
return
|
||||
}
|
||||
document, err := builtinDocumentationFS.ReadFile("docs/" + info.ID + ".md")
|
||||
if err != nil {
|
||||
return
|
||||
}
|
||||
info.Documentation = renderBuiltinDocumentation(*info, string(document))
|
||||
}
|
||||
|
||||
// AttachDocumentation fills the reference document for a shipped protocol.
|
||||
func AttachDocumentation(info *Metadata) {
|
||||
attachDocumentation(info)
|
||||
}
|
||||
|
||||
func renderBuiltinDocumentation(info Metadata, document string) string {
|
||||
replacements := map[string]string{
|
||||
"{{NAME}}": info.Name,
|
||||
"{{OPERATIONS}}": renderOperations(info),
|
||||
"{{PARAMETERS}}": renderParameters(info.Parameters),
|
||||
"{{CONTRACT}}": renderRuntimeContract(info),
|
||||
}
|
||||
for marker, replacement := range replacements {
|
||||
document = strings.ReplaceAll(document, marker, replacement)
|
||||
}
|
||||
return strings.TrimSpace(document) + "\n"
|
||||
}
|
||||
|
||||
func renderOperations(info Metadata) string {
|
||||
var b strings.Builder
|
||||
b.WriteString("| 阶段 | 方法与相对路径 | 请求类型 | 影策行为 |\n| --- | --- | --- | --- |\n")
|
||||
writeOperation(&b, "创建", info.Create, firstNonEmpty(info.ContentType, "application/json"), "提交请求;同步协议直接解析结果,异步协议读取任务 ID")
|
||||
if strings.TrimSpace(info.Poll) != "" {
|
||||
writeOperation(&b, "轮询", info.Poll, "application/json", "查询状态,成功后提取媒体地址")
|
||||
}
|
||||
if strings.TrimSpace(info.Cancel) != "" {
|
||||
writeOperation(&b, "取消", info.Cancel, "application/json", "取消仍在运行的任务")
|
||||
}
|
||||
return strings.TrimSpace(b.String())
|
||||
}
|
||||
|
||||
func renderParameters(parameters []Parameter) string {
|
||||
if len(parameters) == 0 {
|
||||
return "> 当前适配器没有声明可配置参数;这不表示上游没有参数,只表示影策尚未建立稳定映射。"
|
||||
}
|
||||
var b strings.Builder
|
||||
b.WriteString("| 影策字段 | 类型 | 必填 | 实际上游映射 | 说明 |\n| --- | --- | --- | --- | --- |\n")
|
||||
for _, parameter := range parameters {
|
||||
description := strings.TrimSpace(parameter.Description)
|
||||
if len(parameter.Values) > 0 {
|
||||
description = strings.TrimSpace(description + " 可选值:" + strings.Join(parameter.Values, "、") + "。")
|
||||
}
|
||||
fmt.Fprintf(&b, "| `%s` | `%s` | %s | `%s` | %s |\n", markdownCell(parameter.Name), markdownCell(parameter.Type), yesNo(parameter.Required), markdownCell(firstNonEmpty(parameter.Mapping, "未映射")), markdownCell(firstNonEmpty(description, "由当前协议适配器按请求类型转换。")))
|
||||
}
|
||||
return strings.TrimSpace(b.String())
|
||||
}
|
||||
|
||||
func renderRuntimeContract(info Metadata) string {
|
||||
var b strings.Builder
|
||||
b.WriteString("## 影策运行时合同\n\n")
|
||||
b.WriteString("- Base URL 只填写协议服务根地址,表中的相对路径由适配器拼接;不要把同一路径重复写进 Base URL。\n")
|
||||
b.WriteString("- 密钥由后端渠道中转读取,插件详情和浏览器请求不保存密钥。Bearer、供应商签名或专用版本头以本文鉴权章节为准。\n")
|
||||
b.WriteString("- 模型名来自渠道模型配置并原样发送。此插件不暗改模型名,也不根据名称猜测价格、额度或能力。\n")
|
||||
b.WriteString("- HTTP 非 2xx、非 JSON 响应、缺少任务 ID、成功状态却没有可识别结果都会作为真实错误向上返回。\n")
|
||||
if strings.TrimSpace(info.Poll) != "" {
|
||||
b.WriteString("- 异步状态统一为:`queued/pending/created/submitted` -> 等待,`running/processing/in_progress` -> 处理中,`succeeded/completed/done` -> 成功,`failed/error/expired/cancelled` -> 失败。\n")
|
||||
b.WriteString("- 轮询频率应遵守上游速率限制;媒体 URL 通常有有效期,成功后应立即进入影策资源保存流程。\n")
|
||||
}
|
||||
b.WriteString("- 参考素材只接受上游可访问的 HTTP(S) URL 或带 MIME 前缀的 data URL;裸 Base64、登录后才能访问的链接和 Cookie 保护地址不可用。\n")
|
||||
b.WriteString("- 插件只保证下方“当前实现”明确列出的字段。上游新增能力不会自动获得影策支持,必须补适配、解析和测试。\n")
|
||||
return strings.TrimSpace(b.String())
|
||||
}
|
||||
|
||||
func writeOperation(b *strings.Builder, phase, value, contentType, purpose string) {
|
||||
parts := strings.SplitN(strings.TrimSpace(value), " ", 2)
|
||||
method, path := "", strings.TrimSpace(value)
|
||||
if len(parts) == 2 {
|
||||
method, path = parts[0], parts[1]
|
||||
}
|
||||
fmt.Fprintf(b, "| %s | `%s %s` | `%s` | %s |\n", phase, markdownCell(method), markdownCell(path), markdownCell(contentType), purpose)
|
||||
}
|
||||
|
||||
func markdownCell(value string) string {
|
||||
return strings.ReplaceAll(strings.ReplaceAll(value, "|", "\\|"), "\n", " ")
|
||||
}
|
||||
|
||||
func yesNo(value bool) string {
|
||||
if value {
|
||||
return "是"
|
||||
}
|
||||
return "否"
|
||||
}
|
||||
|
||||
func firstNonEmpty(values ...string) string {
|
||||
for _, value := range values {
|
||||
if strings.TrimSpace(value) != "" {
|
||||
return value
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
package protocol
|
||||
|
||||
import "fmt"
|
||||
|
||||
type UnavailableError struct {
|
||||
Protocol string
|
||||
Reason string
|
||||
}
|
||||
|
||||
func (e UnavailableError) Error() string {
|
||||
if e.Reason == "" {
|
||||
return fmt.Sprintf("protocol %s is unavailable", e.Protocol)
|
||||
}
|
||||
return fmt.Sprintf("protocol %s is unavailable: %s", e.Protocol, e.Reason)
|
||||
}
|
||||
|
||||
func unavailable(metadata Metadata) error {
|
||||
return UnavailableError{Protocol: metadata.ID, Reason: metadata.UnavailableReason}
|
||||
}
|
||||
@@ -0,0 +1,474 @@
|
||||
package protocol
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"strconv"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// Manifest is the declarative format used by future protocol packages. It is
|
||||
// intentionally limited to relative HTTP paths and JSON field mappings; a
|
||||
// plugin cannot inject code or bypass the host outbound policy.
|
||||
type Manifest struct {
|
||||
APIVersion string `json:"apiVersion"`
|
||||
Metadata Metadata `json:"metadata"`
|
||||
Create ManifestOperation `json:"create"`
|
||||
Agent *ManifestOperation `json:"agent,omitempty"`
|
||||
Poll *ManifestOperation `json:"poll,omitempty"`
|
||||
Cancel *ManifestOperation `json:"cancel,omitempty"`
|
||||
Response ManifestResponse `json:"response"`
|
||||
AgentResponse *ManifestAgentResponse `json:"agentResponse,omitempty"`
|
||||
}
|
||||
|
||||
type ManifestOperation struct {
|
||||
Method string `json:"method"`
|
||||
Path string `json:"path"`
|
||||
ContentType string `json:"contentType,omitempty"`
|
||||
Fields map[string]string `json:"fields,omitempty"`
|
||||
}
|
||||
|
||||
type ManifestResponse struct {
|
||||
TaskIDPaths []string `json:"taskIdPaths,omitempty"`
|
||||
StatusPaths []string `json:"statusPaths,omitempty"`
|
||||
MessagePaths []string `json:"messagePaths,omitempty"`
|
||||
TextPaths []string `json:"textPaths,omitempty"`
|
||||
ReasoningPaths []string `json:"reasoningPaths,omitempty"`
|
||||
ResultURLPaths []string `json:"resultUrlPaths,omitempty"`
|
||||
ResultKind string `json:"resultKind,omitempty"`
|
||||
}
|
||||
|
||||
// ManifestAgentResponse describes the provider response shape for a
|
||||
// tool-capable text request. Tool call paths are resolved against each item in
|
||||
// ToolCallsPath.
|
||||
type ManifestAgentResponse struct {
|
||||
TextPaths []string `json:"textPaths,omitempty"`
|
||||
ReasoningPaths []string `json:"reasoningPaths,omitempty"`
|
||||
ToolCallsPath string `json:"toolCallsPath,omitempty"`
|
||||
ToolCallIDPaths []string `json:"toolCallIdPaths,omitempty"`
|
||||
ToolCallNamePaths []string `json:"toolCallNamePaths,omitempty"`
|
||||
ToolCallArgsPaths []string `json:"toolCallArgumentsPaths,omitempty"`
|
||||
}
|
||||
|
||||
// AdapterResolver is used by the host to bind a shipped execution engine to a
|
||||
// manifest. Uploaded plugins must use the declarative path; host bindings are
|
||||
// reserved for manifests shipped with the application.
|
||||
type AdapterResolver func(string) (Adapter, bool)
|
||||
|
||||
func LoadInstalledPlugin(data []byte, resolve AdapterResolver) (Adapter, error) {
|
||||
var manifest Manifest
|
||||
if err := json.Unmarshal(data, &manifest); err != nil {
|
||||
return nil, fmt.Errorf("decode protocol plugin: %w", err)
|
||||
}
|
||||
if strings.HasPrefix(strings.TrimSpace(manifest.Metadata.Execution), "host:") {
|
||||
if resolve == nil {
|
||||
return nil, fmt.Errorf("protocol plugin %q requires a host execution engine", manifest.Metadata.ID)
|
||||
}
|
||||
name := strings.TrimPrefix(strings.TrimSpace(manifest.Metadata.Execution), "host:")
|
||||
adapter, ok := resolve(name)
|
||||
if !ok {
|
||||
return nil, fmt.Errorf("protocol plugin host execution %q is unavailable", name)
|
||||
}
|
||||
if err := validatePluginMetadata(manifest.Metadata); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return metadataAdapter{metadata: manifest.Metadata, delegate: adapter}, nil
|
||||
}
|
||||
return LoadManifest(data)
|
||||
}
|
||||
|
||||
func validatePluginMetadata(metadata Metadata) error {
|
||||
if strings.TrimSpace(metadata.ID) == "" || strings.TrimSpace(metadata.Version) == "" || !validManifestIdentifier(metadata.ID) {
|
||||
return fmt.Errorf("protocol plugin metadata is invalid")
|
||||
}
|
||||
if len(metadata.Categories) == 0 || len(metadata.Scopes) == 0 {
|
||||
return fmt.Errorf("protocol plugin metadata requires categories and scopes")
|
||||
}
|
||||
for _, capability := range metadata.Categories {
|
||||
if capability != CapabilityText && capability != CapabilityImage && capability != CapabilityVideo && capability != CapabilityAudio {
|
||||
return fmt.Errorf("unsupported protocol capability %q", capability)
|
||||
}
|
||||
}
|
||||
for _, scope := range metadata.Scopes {
|
||||
switch scope {
|
||||
case SurfaceAdminSystemChannel, SurfaceUserCustomChannel, SurfaceCanvas, SurfaceCreation, SurfaceAgent:
|
||||
default:
|
||||
return fmt.Errorf("unsupported protocol scope %q", scope)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
type metadataAdapter struct {
|
||||
metadata Metadata
|
||||
delegate Adapter
|
||||
}
|
||||
|
||||
func (a metadataAdapter) Metadata() Metadata { return a.metadata }
|
||||
func (a metadataAdapter) BuildCreate(ctx context.Context, c RequestContext) (RequestSpec, error) {
|
||||
return a.delegate.BuildCreate(ctx, c)
|
||||
}
|
||||
func (a metadataAdapter) ParseCreate(ctx context.Context, body []byte) (CreateResult, error) {
|
||||
return a.delegate.ParseCreate(ctx, body)
|
||||
}
|
||||
func (a metadataAdapter) BuildPoll(ctx context.Context, c PollContext) (RequestSpec, error) {
|
||||
return a.delegate.BuildPoll(ctx, c)
|
||||
}
|
||||
func (a metadataAdapter) ParsePoll(ctx context.Context, c PollContext, body []byte) (PollResult, error) {
|
||||
return a.delegate.ParsePoll(ctx, c, body)
|
||||
}
|
||||
func (a metadataAdapter) BuildCancel(ctx context.Context, c PollContext) (RequestSpec, error) {
|
||||
return a.delegate.BuildCancel(ctx, c)
|
||||
}
|
||||
func (a metadataAdapter) BuildAgent(ctx context.Context, c AgentRequestContext) (RequestSpec, error) {
|
||||
adapter, ok := a.delegate.(AgentAdapter)
|
||||
if !ok {
|
||||
return RequestSpec{}, unavailable(a.metadata)
|
||||
}
|
||||
return adapter.BuildAgent(ctx, c)
|
||||
}
|
||||
func (a metadataAdapter) ParseAgent(ctx context.Context, body []byte) (AgentResult, error) {
|
||||
adapter, ok := a.delegate.(AgentAdapter)
|
||||
if !ok {
|
||||
return AgentResult{}, unavailable(a.metadata)
|
||||
}
|
||||
return adapter.ParseAgent(ctx, body)
|
||||
}
|
||||
|
||||
func LoadManifest(data []byte) (Adapter, error) {
|
||||
var manifest Manifest
|
||||
if err := json.Unmarshal(data, &manifest); err != nil {
|
||||
return nil, fmt.Errorf("decode protocol manifest: %w", err)
|
||||
}
|
||||
if err := ValidateManifest(manifest); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if strings.TrimSpace(manifest.Metadata.Execution) == "" {
|
||||
manifest.Metadata.Execution = "declarative"
|
||||
}
|
||||
return manifestAdapter{manifest: manifest}, nil
|
||||
}
|
||||
|
||||
func ValidateManifest(manifest Manifest) error {
|
||||
if strings.TrimSpace(manifest.APIVersion) != "v1" {
|
||||
return fmt.Errorf("unsupported protocol manifest apiVersion %q", manifest.APIVersion)
|
||||
}
|
||||
if strings.TrimSpace(manifest.Metadata.ID) == "" || strings.TrimSpace(manifest.Metadata.Version) == "" {
|
||||
return fmt.Errorf("protocol manifest metadata requires id and version")
|
||||
}
|
||||
if strings.TrimSpace(manifest.Metadata.Name) == "" {
|
||||
return fmt.Errorf("protocol manifest metadata requires name")
|
||||
}
|
||||
if strings.TrimSpace(manifest.Metadata.Documentation) == "" {
|
||||
return fmt.Errorf("protocol manifest metadata requires Markdown documentation")
|
||||
}
|
||||
if !validManifestIdentifier(manifest.Metadata.ID) {
|
||||
return fmt.Errorf("protocol manifest metadata id is invalid")
|
||||
}
|
||||
if len(manifest.Metadata.Name) > 160 || len(manifest.Metadata.Vendor) > 120 {
|
||||
return fmt.Errorf("protocol manifest metadata name or vendor is too long")
|
||||
}
|
||||
if len(manifest.Metadata.Categories) == 0 || len(manifest.Metadata.Scopes) == 0 {
|
||||
return fmt.Errorf("protocol manifest metadata requires categories and scopes")
|
||||
}
|
||||
for _, capability := range manifest.Metadata.Categories {
|
||||
if capability != CapabilityText && capability != CapabilityImage && capability != CapabilityVideo && capability != CapabilityAudio {
|
||||
return fmt.Errorf("unsupported protocol capability %q", capability)
|
||||
}
|
||||
}
|
||||
for _, scope := range manifest.Metadata.Scopes {
|
||||
switch scope {
|
||||
case SurfaceAdminSystemChannel, SurfaceUserCustomChannel, SurfaceCanvas, SurfaceCreation, SurfaceAgent:
|
||||
default:
|
||||
return fmt.Errorf("unsupported protocol scope %q", scope)
|
||||
}
|
||||
}
|
||||
if err := validateManifestOperation(manifest.Create); err != nil {
|
||||
return fmt.Errorf("create operation: %w", err)
|
||||
}
|
||||
if manifest.Agent != nil {
|
||||
if err := validateManifestOperation(*manifest.Agent); err != nil {
|
||||
return fmt.Errorf("agent operation: %w", err)
|
||||
}
|
||||
if manifest.AgentResponse == nil {
|
||||
return fmt.Errorf("agent response mapping is required when agent operation is declared")
|
||||
}
|
||||
}
|
||||
if manifest.Poll != nil {
|
||||
if err := validateManifestOperation(*manifest.Poll); err != nil {
|
||||
return fmt.Errorf("poll operation: %w", err)
|
||||
}
|
||||
}
|
||||
if manifest.Cancel != nil {
|
||||
if err := validateManifestOperation(*manifest.Cancel); err != nil {
|
||||
return fmt.Errorf("cancel operation: %w", err)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func validateManifestOperation(operation ManifestOperation) error {
|
||||
method := strings.ToUpper(strings.TrimSpace(operation.Method))
|
||||
if method != http.MethodGet && method != http.MethodPost && method != http.MethodDelete && method != http.MethodPut {
|
||||
return fmt.Errorf("unsupported HTTP method %q", operation.Method)
|
||||
}
|
||||
if !isRelativePath(operation.Path) {
|
||||
return fmt.Errorf("path must be relative: %q", operation.Path)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
type manifestAdapter struct{ manifest Manifest }
|
||||
|
||||
func (a manifestAdapter) Metadata() Metadata { return a.manifest.Metadata }
|
||||
func (a manifestAdapter) BuildCreate(_ context.Context, c RequestContext) (RequestSpec, error) {
|
||||
return buildManifestOperation(a.manifest.Create, c.Request, ""), nil
|
||||
}
|
||||
func (a manifestAdapter) BuildAgent(_ context.Context, c AgentRequestContext) (RequestSpec, error) {
|
||||
if a.manifest.Agent == nil {
|
||||
return RequestSpec{}, fmt.Errorf("protocol %s has no agent operation", a.manifest.Metadata.ID)
|
||||
}
|
||||
request := GenerationRequest{Model: c.Model, Extra: map[string]any{"agent": c.Request}}
|
||||
return buildManifestOperation(*a.manifest.Agent, request, ""), nil
|
||||
}
|
||||
func (a manifestAdapter) ParseAgent(_ context.Context, body []byte) (AgentResult, error) {
|
||||
if a.manifest.AgentResponse == nil {
|
||||
return AgentResult{}, fmt.Errorf("protocol %s has no agent response mapping", a.manifest.Metadata.ID)
|
||||
}
|
||||
payload, err := decodeObject(body)
|
||||
if err != nil {
|
||||
return AgentResult{}, err
|
||||
}
|
||||
response := a.manifest.AgentResponse
|
||||
result := AgentResult{Text: firstPathValue(payload, response.TextPaths...), Reasoning: firstPathValue(payload, response.ReasoningPaths...)}
|
||||
if response.ToolCallsPath == "" {
|
||||
return result, nil
|
||||
}
|
||||
for _, item := range arrayValue(pathValue(payload, response.ToolCallsPath)) {
|
||||
object, ok := item.(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
result.ToolCalls = append(result.ToolCalls, AgentToolCall{
|
||||
ID: firstPathValue(object, response.ToolCallIDPaths...),
|
||||
Name: firstPathValue(object, response.ToolCallNamePaths...),
|
||||
Arguments: firstPathJSONValue(object, response.ToolCallArgsPaths...),
|
||||
})
|
||||
}
|
||||
return result, nil
|
||||
}
|
||||
func (a manifestAdapter) ParseCreate(_ context.Context, body []byte) (CreateResult, error) {
|
||||
payload, err := decodeObject(body)
|
||||
if err != nil {
|
||||
return CreateResult{}, err
|
||||
}
|
||||
return a.parse(payload, PollContext{}), nil
|
||||
}
|
||||
func (a manifestAdapter) BuildPoll(_ context.Context, c PollContext) (RequestSpec, error) {
|
||||
if a.manifest.Poll == nil {
|
||||
return RequestSpec{}, fmt.Errorf("protocol %s has no poll operation", a.manifest.Metadata.ID)
|
||||
}
|
||||
request := c.Request
|
||||
request.Model = c.Model
|
||||
return buildManifestOperation(*a.manifest.Poll, request, c.TaskID), nil
|
||||
}
|
||||
func (a manifestAdapter) ParsePoll(_ context.Context, c PollContext, body []byte) (PollResult, error) {
|
||||
payload, err := decodeObject(body)
|
||||
if err != nil {
|
||||
return PollResult{}, err
|
||||
}
|
||||
result := a.parse(payload, c)
|
||||
return PollResult{TaskID: result.TaskID, Status: result.Status, Result: result.Result, Message: result.Message}, nil
|
||||
}
|
||||
func (a manifestAdapter) BuildCancel(_ context.Context, c PollContext) (RequestSpec, error) {
|
||||
if a.manifest.Cancel == nil {
|
||||
return RequestSpec{}, fmt.Errorf("protocol %s does not support cancellation", a.manifest.Metadata.ID)
|
||||
}
|
||||
request := c.Request
|
||||
request.Model = c.Model
|
||||
return buildManifestOperation(*a.manifest.Cancel, request, c.TaskID), nil
|
||||
}
|
||||
|
||||
func (a manifestAdapter) parse(payload map[string]any, c PollContext) CreateResult {
|
||||
id := firstPathValue(payload, a.manifest.Response.TaskIDPaths...)
|
||||
if id == "" {
|
||||
id = c.TaskID
|
||||
}
|
||||
status := normalizeStatus(firstPathValue(payload, a.manifest.Response.StatusPaths...))
|
||||
if status == "" {
|
||||
status = StatusPending
|
||||
}
|
||||
message := firstPathValue(payload, a.manifest.Response.MessagePaths...)
|
||||
result := &Result{
|
||||
Text: firstPathValue(payload, a.manifest.Response.TextPaths...),
|
||||
Reasoning: firstPathValue(payload, a.manifest.Response.ReasoningPaths...),
|
||||
}
|
||||
for _, path := range a.manifest.Response.ResultURLPaths {
|
||||
if value := firstPathValue(payload, path); value != "" {
|
||||
item := MediaReference{URL: value, Kind: a.manifest.Response.ResultKind}
|
||||
switch a.manifest.Response.ResultKind {
|
||||
case "image":
|
||||
result.Images = append(result.Images, item)
|
||||
case "audio":
|
||||
result.Audios = append(result.Audios, item)
|
||||
default:
|
||||
result.Videos = append(result.Videos, item)
|
||||
}
|
||||
}
|
||||
}
|
||||
if status == StatusPending && (result.Text != "" || len(result.Images) > 0 || len(result.Videos) > 0 || len(result.Audios) > 0) {
|
||||
status = StatusSucceeded
|
||||
}
|
||||
if result.Text == "" && result.Reasoning == "" && len(result.Images) == 0 && len(result.Videos) == 0 && len(result.Audios) == 0 {
|
||||
result = nil
|
||||
}
|
||||
return CreateResult{TaskID: id, Status: status, Result: result, Message: message}
|
||||
}
|
||||
|
||||
func buildManifestOperation(operation ManifestOperation, request GenerationRequest, taskID string) RequestSpec {
|
||||
var body map[string]any
|
||||
if len(operation.Fields) > 0 {
|
||||
body = make(map[string]any, len(operation.Fields))
|
||||
}
|
||||
for key, expression := range operation.Fields {
|
||||
setMapPath(body, key, manifestExpressionValue(expression, request, taskID))
|
||||
}
|
||||
path := strings.ReplaceAll(operation.Path, "{{taskId}}", url.PathEscape(taskID))
|
||||
path = strings.ReplaceAll(path, "{{model}}", url.PathEscape(request.Model))
|
||||
return RequestSpec{Method: strings.ToUpper(operation.Method), Path: path, ContentType: defaultValue(operation.ContentType, "application/json"), Body: body}
|
||||
}
|
||||
|
||||
func manifestExpressionValue(expression string, request GenerationRequest, taskID string) any {
|
||||
expression = strings.TrimSpace(expression)
|
||||
switch expression {
|
||||
case "request.model":
|
||||
return request.Model
|
||||
case "request.prompt":
|
||||
return request.Prompt
|
||||
case "request.images":
|
||||
return request.Images
|
||||
case "request.videos":
|
||||
return request.Videos
|
||||
case "request.audios":
|
||||
return request.Audios
|
||||
case "request.imageCount":
|
||||
return request.ImageCount
|
||||
case "request.duration":
|
||||
return request.Duration
|
||||
case "request.aspectRatio":
|
||||
return request.AspectRatio
|
||||
case "request.resolution":
|
||||
return request.Resolution
|
||||
case "request.quality":
|
||||
return request.Quality
|
||||
case "request.generateAudio":
|
||||
return request.GenerateAudio
|
||||
case "request.watermark":
|
||||
return request.Watermark
|
||||
case "request.operation":
|
||||
return request.Operation
|
||||
case "taskId":
|
||||
return taskID
|
||||
}
|
||||
if strings.HasPrefix(expression, "request.extra.") {
|
||||
return pathValue(request.Extra, strings.TrimPrefix(expression, "request.extra."))
|
||||
}
|
||||
return expression
|
||||
}
|
||||
|
||||
func pathValue(payload map[string]any, path string) any {
|
||||
var value any = payload
|
||||
for _, part := range strings.Split(strings.Trim(path, "."), ".") {
|
||||
switch current := value.(type) {
|
||||
case map[string]any:
|
||||
value = current[part]
|
||||
case []any:
|
||||
index, err := strconv.Atoi(part)
|
||||
if err != nil || index < 0 || index >= len(current) {
|
||||
return nil
|
||||
}
|
||||
value = current[index]
|
||||
default:
|
||||
return nil
|
||||
}
|
||||
}
|
||||
return value
|
||||
}
|
||||
|
||||
func arrayValue(value any) []any {
|
||||
items, _ := value.([]any)
|
||||
return items
|
||||
}
|
||||
|
||||
func firstPathValue(payload map[string]any, paths ...string) string {
|
||||
for _, path := range paths {
|
||||
value := pathValue(payload, path)
|
||||
if text, ok := value.(string); ok && strings.TrimSpace(text) != "" {
|
||||
return strings.TrimSpace(text)
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// firstPathJSONValue keeps scalar response fields string-like while allowing
|
||||
// providers to return tool arguments as an object instead of a JSON string.
|
||||
// The platform tool contract always stores arguments as JSON text.
|
||||
func firstPathJSONValue(payload map[string]any, paths ...string) string {
|
||||
for _, path := range paths {
|
||||
value := pathValue(payload, path)
|
||||
switch typed := value.(type) {
|
||||
case string:
|
||||
if strings.TrimSpace(typed) != "" {
|
||||
return strings.TrimSpace(typed)
|
||||
}
|
||||
case nil:
|
||||
continue
|
||||
default:
|
||||
encoded, err := json.Marshal(typed)
|
||||
if err == nil && len(encoded) > 0 {
|
||||
return string(encoded)
|
||||
}
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
func setMapPath(target map[string]any, path string, value any) {
|
||||
parts := strings.Split(strings.Trim(path, "."), ".")
|
||||
current := target
|
||||
for _, part := range parts[:len(parts)-1] {
|
||||
next, ok := current[part].(map[string]any)
|
||||
if !ok {
|
||||
next = map[string]any{}
|
||||
current[part] = next
|
||||
}
|
||||
current = next
|
||||
}
|
||||
if len(parts) > 0 {
|
||||
current[parts[len(parts)-1]] = value
|
||||
}
|
||||
}
|
||||
|
||||
func isRelativePath(path string) bool {
|
||||
parsed, err := url.Parse(strings.TrimSpace(path))
|
||||
return err == nil && parsed.Path != "" && strings.HasPrefix(parsed.Path, "/") && !strings.HasPrefix(parsed.Path, "//") && parsed.Host == "" && parsed.User == nil && parsed.Scheme == ""
|
||||
}
|
||||
|
||||
func validManifestIdentifier(value string) bool {
|
||||
if len(value) == 0 || len(value) > 96 {
|
||||
return false
|
||||
}
|
||||
for index, char := range value {
|
||||
if (char >= 'a' && char <= 'z') || (char >= '0' && char <= '9') || char == '-' || char == '_' || char == '.' {
|
||||
if index == 0 && (char == '-' || char == '_' || char == '.') {
|
||||
return false
|
||||
}
|
||||
continue
|
||||
}
|
||||
return false
|
||||
}
|
||||
return true
|
||||
}
|
||||
@@ -0,0 +1,87 @@
|
||||
package protocol
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestManifestAgentMapsRequestAndResponse(t *testing.T) {
|
||||
manifest := []byte(`{
|
||||
"apiVersion":"v1",
|
||||
"metadata":{"id":"agent-test","version":"1.0.0","name":"Agent Test","vendor":"Test","categories":["text"],"scopes":["agent"],"documentation":"# Agent Test"},
|
||||
"create":{"method":"POST","path":"/create"},
|
||||
"agent":{"method":"POST","path":"/messages","fields":{"model":"request.model","messages":"request.extra.agent.chatCompletion.messages","tools":"request.extra.agent.chatCompletion.tools","tool_choice":"request.extra.agent.chatCompletion.tool_choice"}},
|
||||
"agentResponse":{"textPaths":["choices.0.message.content"],"toolCallsPath":"choices.0.message.tool_calls","toolCallIdPaths":["id"],"toolCallNamePaths":["function.name"],"toolCallArgumentsPaths":["function.arguments"]},
|
||||
"response":{}
|
||||
}`)
|
||||
adapter, err := LoadManifest(manifest)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
agent, ok := adapter.(AgentAdapter)
|
||||
if !ok {
|
||||
t.Fatal("manifest adapter does not expose AgentAdapter")
|
||||
}
|
||||
request := map[string]any{
|
||||
"chatCompletion": map[string]any{
|
||||
"messages": []any{map[string]any{"role": "user", "content": "hello"}},
|
||||
"tools": []any{map[string]any{"type": "function"}},
|
||||
"tool_choice": "required",
|
||||
},
|
||||
"responses": map[string]any{},
|
||||
}
|
||||
spec, err := agent.BuildAgent(context.Background(), AgentRequestContext{Model: "model-a", Request: request})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
body, ok := spec.Body.(map[string]any)
|
||||
if !ok || body["model"] != "model-a" {
|
||||
t.Fatalf("request body = %#v", spec.Body)
|
||||
}
|
||||
if _, ok := body["messages"].([]any); !ok {
|
||||
t.Fatalf("messages were not mapped: %#v", body)
|
||||
}
|
||||
result, err := agent.ParseAgent(context.Background(), []byte(`{"choices":[{"message":{"content":"answer","tool_calls":[{"id":"call-1","function":{"name":"search","arguments":"{\"q\":\"x\"}"}}]}}]}`))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if result.Text != "answer" || len(result.ToolCalls) != 1 || result.ToolCalls[0].Name != "search" {
|
||||
t.Fatalf("agent result = %#v", result)
|
||||
}
|
||||
if !json.Valid([]byte(result.ToolCalls[0].Arguments)) {
|
||||
t.Fatalf("tool arguments are not JSON: %q", result.ToolCalls[0].Arguments)
|
||||
}
|
||||
|
||||
result, err = agent.ParseAgent(context.Background(), []byte(`{"choices":[{"message":{"tool_calls":[{"id":"call-2","function":{"name":"search","arguments":{"q":"object"}}}]}}]}`))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got := result.ToolCalls[0].Arguments; got != `{"q":"object"}` {
|
||||
t.Fatalf("object tool arguments = %q", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestManifestMapsSynchronousTextResponse(t *testing.T) {
|
||||
manifest := []byte(`{
|
||||
"apiVersion":"v1",
|
||||
"metadata":{"id":"text-test","version":"1.0.0","name":"Text Test","vendor":"Test","categories":["text"],"scopes":["canvas"],"documentation":"# Text Test"},
|
||||
"create":{"method":"POST","path":"/chat","fields":{"prompt":"request.prompt"}},
|
||||
"response":{"textPaths":["choices.0.message.content"],"reasoningPaths":["choices.0.message.reasoning_content"]}
|
||||
}`)
|
||||
adapter, err := LoadManifest(manifest)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
spec, err := adapter.BuildCreate(context.Background(), RequestContext{Request: GenerationRequest{Prompt: "hello"}})
|
||||
if err != nil || spec.Body == nil {
|
||||
t.Fatalf("build create = %#v, %v", spec, err)
|
||||
}
|
||||
result, err := adapter.ParseCreate(context.Background(), []byte(`{"choices":[{"message":{"content":"answer","reasoning_content":"thinking"}}]}`))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if result.Status != StatusSucceeded || result.Result == nil || result.Result.Text != "answer" || result.Result.Reasoning != "thinking" {
|
||||
t.Fatalf("text result = %#v", result)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,134 @@
|
||||
package protocol
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"sort"
|
||||
"strings"
|
||||
"sync"
|
||||
)
|
||||
|
||||
type Registry struct {
|
||||
mu sync.RWMutex
|
||||
adapters map[string]Adapter
|
||||
}
|
||||
|
||||
func NewRegistry(adapters ...Adapter) (*Registry, error) {
|
||||
r := &Registry{adapters: make(map[string]Adapter, len(adapters))}
|
||||
for _, adapter := range adapters {
|
||||
if err := r.Register(adapter); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
}
|
||||
return r, nil
|
||||
}
|
||||
|
||||
func (r *Registry) Register(adapter Adapter) error {
|
||||
if adapter == nil {
|
||||
return fmt.Errorf("protocol adapter is nil")
|
||||
}
|
||||
metadata := adapter.Metadata()
|
||||
metadata.ID = strings.TrimSpace(metadata.ID)
|
||||
metadata.Version = strings.TrimSpace(metadata.Version)
|
||||
if metadata.ID == "" || metadata.Version == "" {
|
||||
return fmt.Errorf("protocol adapter metadata requires id and version")
|
||||
}
|
||||
r.mu.Lock()
|
||||
defer r.mu.Unlock()
|
||||
if _, exists := r.adapters[metadata.ID]; exists {
|
||||
return fmt.Errorf("protocol adapter %q is already registered", metadata.ID)
|
||||
}
|
||||
r.adapters[metadata.ID] = adapter
|
||||
return nil
|
||||
}
|
||||
|
||||
// Unregister removes an installed protocol from the live registry. The caller
|
||||
// owns persistence; the registry only represents the current plugin snapshot.
|
||||
func (r *Registry) Unregister(id string) bool {
|
||||
r.mu.Lock()
|
||||
defer r.mu.Unlock()
|
||||
id = strings.TrimSpace(id)
|
||||
if _, ok := r.adapters[id]; !ok {
|
||||
return false
|
||||
}
|
||||
delete(r.adapters, id)
|
||||
return true
|
||||
}
|
||||
|
||||
func (r *Registry) RegisterManifest(data []byte) error {
|
||||
adapter, err := LoadManifest(data)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return r.Register(adapter)
|
||||
}
|
||||
|
||||
func (r *Registry) Get(id string) (Adapter, bool) {
|
||||
r.mu.RLock()
|
||||
defer r.mu.RUnlock()
|
||||
adapter, ok := r.adapters[strings.TrimSpace(id)]
|
||||
return adapter, ok
|
||||
}
|
||||
|
||||
func (r *Registry) Resolve(id string) (Adapter, bool) {
|
||||
if adapter, ok := r.Get(id); ok {
|
||||
return adapter, true
|
||||
}
|
||||
r.mu.RLock()
|
||||
defer r.mu.RUnlock()
|
||||
for _, adapter := range r.adapters {
|
||||
for _, alias := range adapter.Metadata().LegacyAliases {
|
||||
if strings.TrimSpace(alias) == strings.TrimSpace(id) {
|
||||
return adapter, true
|
||||
}
|
||||
}
|
||||
}
|
||||
return nil, false
|
||||
}
|
||||
|
||||
func (r *Registry) List(surface Surface, capability Capability, includeUnavailable bool) []Metadata {
|
||||
r.mu.RLock()
|
||||
items := make([]Metadata, 0, len(r.adapters))
|
||||
for _, adapter := range r.adapters {
|
||||
metadata := adapter.Metadata()
|
||||
if !includeUnavailable && (!metadata.Enabled || metadata.UnavailableReason != "") {
|
||||
continue
|
||||
}
|
||||
if capability != "" && !containsCapability(metadata.Categories, capability) {
|
||||
continue
|
||||
}
|
||||
if surface != "" && !containsSurface(metadata.Scopes, surface) {
|
||||
continue
|
||||
}
|
||||
items = append(items, metadata)
|
||||
}
|
||||
r.mu.RUnlock()
|
||||
sort.Slice(items, func(i, j int) bool { return items[i].ID < items[j].ID })
|
||||
return items
|
||||
}
|
||||
|
||||
func (r *Registry) IsCapability(id string, capability Capability) bool {
|
||||
adapter, ok := r.Resolve(id)
|
||||
if !ok {
|
||||
return false
|
||||
}
|
||||
metadata := adapter.Metadata()
|
||||
return metadata.Enabled && metadata.UnavailableReason == "" && containsCapability(metadata.Categories, capability)
|
||||
}
|
||||
|
||||
func containsCapability(values []Capability, value Capability) bool {
|
||||
for _, item := range values {
|
||||
if item == value {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func containsSurface(values []Surface, value Surface) bool {
|
||||
for _, item := range values {
|
||||
if item == value {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
@@ -0,0 +1,140 @@
|
||||
package protocol
|
||||
|
||||
import "fmt"
|
||||
|
||||
// Capability is the kind of model operation handled by a protocol adapter.
|
||||
type Capability string
|
||||
|
||||
const (
|
||||
CapabilityText Capability = "text"
|
||||
CapabilityImage Capability = "image"
|
||||
CapabilityVideo Capability = "video"
|
||||
CapabilityAudio Capability = "audio"
|
||||
)
|
||||
|
||||
// Surface describes where an installed protocol may be selected.
|
||||
type Surface string
|
||||
|
||||
const (
|
||||
SurfaceAdminSystemChannel Surface = "admin.system-channel"
|
||||
SurfaceUserCustomChannel Surface = "user.custom-channel"
|
||||
SurfaceCanvas Surface = "canvas"
|
||||
SurfaceCreation Surface = "creation"
|
||||
SurfaceAgent Surface = "agent"
|
||||
)
|
||||
|
||||
type Status string
|
||||
|
||||
const (
|
||||
StatusPending Status = "pending"
|
||||
StatusProcessing Status = "processing"
|
||||
StatusSucceeded Status = "succeeded"
|
||||
StatusFailed Status = "failed"
|
||||
StatusCancelled Status = "cancelled"
|
||||
)
|
||||
|
||||
type MediaReference struct {
|
||||
URL string `json:"url,omitempty"`
|
||||
DataURL string `json:"dataUrl,omitempty"`
|
||||
Kind string `json:"kind,omitempty"`
|
||||
}
|
||||
|
||||
// GenerationRequest is the platform contract shared by canvas, creation and agent.
|
||||
// Provider-specific fields belong in Extra and are never interpreted by the host.
|
||||
type GenerationRequest struct {
|
||||
Model string `json:"model"`
|
||||
Prompt string `json:"prompt,omitempty"`
|
||||
Images []MediaReference `json:"images,omitempty"`
|
||||
Videos []MediaReference `json:"videos,omitempty"`
|
||||
Audios []MediaReference `json:"audios,omitempty"`
|
||||
Duration int `json:"duration,omitempty"`
|
||||
AspectRatio string `json:"aspectRatio,omitempty"`
|
||||
Resolution string `json:"resolution,omitempty"`
|
||||
Quality string `json:"quality,omitempty"`
|
||||
GenerateAudio bool `json:"generateAudio,omitempty"`
|
||||
Watermark bool `json:"watermark,omitempty"`
|
||||
ImageCount int `json:"imageCount,omitempty"`
|
||||
Operation string `json:"operation,omitempty"`
|
||||
Extra map[string]any `json:"extra,omitempty"`
|
||||
}
|
||||
|
||||
type RequestContext struct {
|
||||
BaseURL string
|
||||
Request GenerationRequest
|
||||
}
|
||||
|
||||
type PollContext struct {
|
||||
BaseURL string
|
||||
Model string
|
||||
Request GenerationRequest
|
||||
TaskID string
|
||||
Metadata map[string]any
|
||||
}
|
||||
|
||||
type RequestSpec struct {
|
||||
Method string `json:"method"`
|
||||
Path string `json:"path"`
|
||||
ContentType string `json:"contentType"`
|
||||
Headers map[string]string `json:"headers,omitempty"`
|
||||
Body any `json:"body,omitempty"`
|
||||
}
|
||||
|
||||
type CreateResult struct {
|
||||
TaskID string `json:"taskId,omitempty"`
|
||||
Status Status `json:"status"`
|
||||
Result *Result `json:"result,omitempty"`
|
||||
Message string `json:"message,omitempty"`
|
||||
}
|
||||
|
||||
type PollResult struct {
|
||||
TaskID string `json:"taskId,omitempty"`
|
||||
Status Status `json:"status"`
|
||||
Result *Result `json:"result,omitempty"`
|
||||
Message string `json:"message,omitempty"`
|
||||
}
|
||||
|
||||
type Result struct {
|
||||
Images []MediaReference `json:"images,omitempty"`
|
||||
Videos []MediaReference `json:"videos,omitempty"`
|
||||
Audios []MediaReference `json:"audios,omitempty"`
|
||||
Text string `json:"text,omitempty"`
|
||||
Reasoning string `json:"reasoning,omitempty"`
|
||||
Usage map[string]any `json:"usage,omitempty"`
|
||||
}
|
||||
|
||||
type Parameter struct {
|
||||
Name string `json:"name"`
|
||||
Type string `json:"type"`
|
||||
Required bool `json:"required,omitempty"`
|
||||
Description string `json:"description,omitempty"`
|
||||
Values []string `json:"values,omitempty"`
|
||||
Mapping string `json:"mapping,omitempty"`
|
||||
}
|
||||
|
||||
type Metadata struct {
|
||||
ID string `json:"id"`
|
||||
Version string `json:"version"`
|
||||
Name string `json:"name"`
|
||||
Vendor string `json:"vendor"`
|
||||
Description string `json:"description,omitempty"`
|
||||
Categories []Capability `json:"categories"`
|
||||
Scopes []Surface `json:"scopes"`
|
||||
Parameters []Parameter `json:"parameters,omitempty"`
|
||||
Create string `json:"create,omitempty"`
|
||||
Poll string `json:"poll,omitempty"`
|
||||
Cancel string `json:"cancel,omitempty"`
|
||||
ContentType string `json:"contentType,omitempty"`
|
||||
Documentation string `json:"documentation,omitempty"`
|
||||
LegacyAliases []string `json:"legacyAliases,omitempty"`
|
||||
Enabled bool `json:"enabled"`
|
||||
Installable bool `json:"installable"`
|
||||
Execution string `json:"execution,omitempty"`
|
||||
UnavailableReason string `json:"unavailableReason,omitempty"`
|
||||
}
|
||||
|
||||
func (r RequestSpec) Validate() error {
|
||||
if r.Method == "" || r.Path == "" {
|
||||
return fmt.Errorf("protocol request spec is incomplete")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
Reference in new issue
Block a user