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
