dsh-agnes-media

English | 中文

Agnes AI image and video generation for DeepSeek Harness, as two model-facing tools:

Tool	Endpoint	Purpose
agnes_image	POST /v1/images/generations	Text-to-image, image-to-image, multi-image composition
agnes_video	POST /v1/videos + GET /agnesapi	Asynchronous tasks: text-to-video, keyframes, multimodal reference

Why a plugin rather than an LLM route

The harness LLM seam speaks chat protocols only (completions / responses / messages). Agnes' text models make a fine llm-pi-ai route, but image and video are generation endpoints that return no conversation — so they are tools, not models. The two coexist: text on a route, media through this plugin.

Install

dsh plugin --profile <profile> add dsh-agnes-media

Or declare it as a bundle in the profile package.json:

{
  "dsh": { "profile": { "bundles": ["dsh-agnes-media"] } }
}

Restart the harness afterwards.

Credentials

No secret is stored by the plugin. Each call resolves apiKeyEnv (default AGNES_API_KEY) through the harness credential seam:

# $DSH_HOME/.credentials.yaml
refs:
  AGNES_API_KEY: sk-...

An unconfigured reference fails with an error naming it, rather than sending a request that is certain to 401.

Configuration

Override by id from the profile patch layer:

- id: agnes-media
  config:
    baseURL: https://apihub.agnes-ai.com/v1
    apiKeyEnv: AGNES_API_KEY
    imageModel: agnes-image-2.5-flash
    videoModel: agnes-video-2.5-flash
    outputDir: agnes-media
    requestTimeoutMs: 300000
    imageTimeoutMs: 360000
    videoTimeoutMs: 1800000
    videoPollIntervalMs: 3000

Field	Default	Meaning
baseURL	https://apihub.agnes-ai.com/v1	International service. China is https://api.agnes-ai.cn/v1; the international alternate is https://apihub.agnes-ai.cn/v1
apiKeyEnv	AGNES_API_KEY	Credential reference resolved per call
imageModel	agnes-image-2.5-flash	Used when a call names no model
videoModel	agnes-video-2.5-flash	Defaults to the free tier so an unconfigured call cannot silently spend money
outputDir	agnes-media	Relative to the calling workspace; an absolute outputPath bypasses it

Where artifacts land

By default, under the calling agent session's workspace:

<workspace>/agnes-media/image-<UTC timestamp>.png
<workspace>/agnes-media/video-<UTC timestamp>.mp4

Extensions come from sniffing the downloaded bytes, not from a fixed table. Pass outputPath to override — relative paths resolve against the workspace, absolute paths are used as given.

Agnes also returns a URL it hosts (the result's sourceUrl), and that URL may expire, so the plugin downloads the bytes; the local file is authoritative.

Free tiers

Per the Agnes pricing page: every resolution tier of all three image models is currently free; agnes-video-v2.0 and agnes-video-2.5-flash are currently $0/second; agnes-video-2.5 is billed per second. The free tier is rate-limited per account.

Implementation notes: where the API differs from its documentation

Each of these was observed against the live endpoint and each one affects correctness, so they are documented rather than left in code comments:

• The video result URL is at the top level (url), not at the documented metadata.url — a completed response carried no metadata object at all. The plugin prefers the observed shape and keeps the documented one as a fallback.
• Task status uses spellings the documentation does not list — live responses returned pending where the docs say queued. Status is therefore read as a terminal-state check (completed / failed), never an enumeration of in-progress values.
• Polling returns 429 even at the documented 1–2 second cadence. The plugin backs off instead of reporting a rate limit as a generation failure.
• Creation returns 503 video_queue_full. Also retried with backoff. A generic 500 is deliberately not retried: it cannot be told apart from a task that was created before the failure, and retrying would bill for a duplicate.
• The result URL rejects the bearer token — attaching it yields 401. Downloads are unauthenticated.
• Images accept data URIs, so a local image can be inlined without an upload step.
• Video media must be a public URL: Agnes fetches it server-side and cannot reach this machine's filesystem.

Limitations

• Image input support relies on Agnes accepting data URIs (verified), which is not true of every OpenAI-compatible gateway.
• The video tool is long-running: it polls for up to 30 minutes by default, declares a matching timeoutMs, and observes exec.signal throughout for cooperative cancellation.
• Agnes' image and video model catalog is not discovered from the endpoint; model names are configuration.

License

MIT