feat(*): 插件中心与模型协议 - 完善声明式协议运行时并增加功能开放控制

This commit is contained in:
ddCat committed 2026-08-23 23:19:27 +08:00
1 parent 70a6640ecf
commit af41893678
106 files changed
+8816 -499

No files matched your search

+67
View File
@@ -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)
}
+876
View File
@@ -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
}
+370
View File
@@ -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}}
+66
View File
@@ -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}}
+113
View File
@@ -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 ""
}
+19
View File
@@ -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}
}
+474
View File
@@ -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)
}
}
+134
View File
@@ -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
}
+140
View File
@@ -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
}