0x0funky/agent-sprite-forge / skills/generate2dmedia
generate2dmedia
VerifiedThe art-route layer of the Forge skills. route_media.py is the one command that generates an image or an image-to-video clip - through the paid API of any provider whose key is configured (OpenAI, Google Gemini, xAI, BytePlus ModelArk, fal.ai; the configured key is the owner's consent), else through the user's own signed-in Codex or Grok CLI - and prints one JSON line with the route, artifact, sha256 and cost estimate; with no route it answers no-route (codeart2d is then the last resort). Also the capability check (forge_doctor), API key configuration, the spend ledger, resume and Codex image adoption. Use when a Forge skill sends a generation here, for the capability check, or when the user asks about keys, routes or spend. Not for planning, processing or QA of sprites, video frames or maps (generate2dsprite, video2dsprite, generate2dmap) or for code-drawn art (codeart2d).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.0 KB |
| agents/openai.yaml | config | 388 B |
| references/agent-profiles/README.md | markdown | 1.3 KB |
| references/agent-profiles/video-agent.md | markdown | 981 B |
| references/api-usage.md | markdown | 18.6 KB |
| references/capabilities.json | config | 32.9 KB |
| references/cli-routes.md | markdown | 15.3 KB |
| references/prices.json | config | 23.5 KB |
| references/provider-survey.md | markdown | 17.2 KB |
| references/route-media.md | markdown | 12.8 KB |
| references/schemas/common.schema.json | config | 12.9 KB |
| references/schemas/host.schema.json | config | 18.8 KB |
| references/schemas/media.schema.json | config | 22.5 KB |
| scripts/cli_media.py | script | 113.3 KB |
| scripts/forge_doctor.py | script | 74.5 KB |
| scripts/forge_index.py | script | 24.8 KB |
| scripts/generate_media.py | script | 72.1 KB |
| scripts/media_config.py | script | 9.1 KB |
| scripts/media_ledger.py | script | 29.8 KB |
| scripts/media_mp4.py | script | 9.4 KB |
| scripts/media_providers.py | script | 66.9 KB |
| scripts/route_media.py | script | 41.7 KB |
references/schemas/media.schema.json
View on GitHub{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/0x0funky/agent-sprite-forge/main/shared/schemas/media.schema.json",
"title": "generate2dmedia contracts",
"description": "Frozen contracts, version 1, for paid or quota-consuming media requests: the job record, the append-only spend ledger, the batch progress file, the readiness doctor and the price table. schemaVersion 1 jobs stay valid and resumable. Objects stay open (additionalProperties true), except a job's provider error block.",
"$defs": {
"job_v2": {
"description": "job.json from generate_media.py (REST) and cli_media.py (local CLI routes). v2 adds the receipt, the cost estimate and the duplicate-guard fingerprint, plus the route, the API base, the consent record, the ledger reservation, the client and provider request ids, the provider's error and usage, and partialArtifact (returned bytes kept in a .partial file when they could not be published). A job is unpriced when estimate.usd is null (no verified price row). artifact is absent until the job is done, and a done job always records it; status not_sent means the request provably never left the machine. CLI-route jobs also record cliRun (the run, the CLI version and recipe, and where the CLI wrote its output, symbolically), artSource and, when the artifact was taken from the CLI's own output, adoption and adoptedAt; outputDir appears only in run records under .forge/cli-runs/. For CLI routes requestedModel is <cli>-<tool> (the CLIs choose their own model), options hold the tool (plus duration and resolution for video), error uses the closed error object with the error code and a scrubbed message, and receipt.outcomeCode carries the same code, ok or adopted.",
"type": "object",
"required": ["schemaVersion", "provider", "kind", "status"],
"properties": {
"schemaVersion": {"enum": [1, 2]},
"provider": {"type": "string", "minLength": 1},
"kind": {"type": "string", "minLength": 1},
"route": {"description": "How the request travels: generate_media.py writes rest, cli_media.py the local CLI routes (users see grok-cli and grok-acp as one Grok (local CLI) route, per D22).", "enum": ["rest", "codex-cli", "grok-cli", "grok-acp"]},
"apiBase": {"type": "string", "pattern": "^https://"},
"endpoint": {"type": "string"},
"requestedModel": {"type": "string", "minLength": 1},
"options": {"description": "The request options that enter the fingerprint. A cli_media --verify-route run adds verifies, the installed CLI version it verifies (per D23, so re-verifying after a CLI update is a new request).", "type": "object"},
"routeChoice": {
"description": "How cli_media --route auto chose the route (per D22, local agent first): route and its user-facing label, the order tried, why earlier routes were skipped, and the installed CLI version the VERIFIED proof matched (null on a dry run, which then records verifiedFor, the proof's version, and a note).",
"type": "object",
"required": ["requested", "route", "label", "order", "skipped"],
"properties": {
"requested": {"const": "auto"},
"route": {"enum": ["codex-cli", "grok-cli", "grok-acp"]},
"label": {"type": "string", "minLength": 1},
"order": {"type": "array", "items": {"type": "string", "minLength": 1}},
"skipped": {"type": "array", "items": {"type": "string"}},
"version": {"type": ["string", "null"]},
"verifiedFor": {"type": ["string", "null"]},
"note": {"type": "string"}
}
},
"promptSha256": {"$ref": "common.schema.json#/$defs/sha256"},
"references": {"type": "array", "items": {"type": "object", "required": ["sha256"], "properties": {"sha256": {"$ref": "common.schema.json#/$defs/sha256"}}}},
"execution": {"enum": ["dry-run", "execute"]},
"status": {
"enum": ["submitting", "pending", "downloading", "processing_result", "done", "failed", "expired", "pending_timeout", "submit_unknown", "interrupted", "not_sent"]
},
"requestId": {"type": "string", "minLength": 1},
"clientRequestId": {"type": "string", "minLength": 1},
"providerRequestId": {"type": "string", "minLength": 1},
"consent": {
"description": "What the user consented to before sending: provider, model, paid calls, the estimate (null when unpriced) and the API host; for a CLI route the route, whether it spends account quota, the account and a note.",
"type": "object",
"properties": {
"provider": {"type": "string", "minLength": 1},
"model": {"type": "string", "minLength": 1},
"calls": {"type": "integer", "minimum": 0},
"estimateUsd": {"type": ["number", "null"], "minimum": 0},
"apiHost": {"type": "string", "minLength": 1},
"route": {"enum": ["rest", "codex-cli", "grok-cli", "grok-acp"]},
"quota": {"type": "boolean"},
"account": {"type": "string"},
"note": {"type": "string"}
}
},
"ledger": {
"description": "The job's reservation in <projectDir>/.forge/ledger.jsonl and its last committed status; error says why an outcome could not be committed.",
"type": "object",
"required": ["reservationId", "status"],
"properties": {
"projectDir": {"type": "string", "minLength": 1},
"reservationId": {"type": "string", "minLength": 1},
"status": {"enum": ["reserved", "done", "failed", "unknown", "not_sent"]},
"error": {"type": "string"}
}
},
"uploadUrl": {
"description": "Only the host and the sha256 of a signed upload URL are stored.",
"type": "object",
"required": ["host", "sha256"],
"properties": {
"host": {"type": "string", "minLength": 1},
"sha256": {"$ref": "common.schema.json#/$defs/sha256"}
}
},
"artifact": {
"type": "object",
"required": ["path", "sha256"],
"properties": {
"path": {"$ref": "common.schema.json#/$defs/relPath"},
"sha256": {"$ref": "common.schema.json#/$defs/sha256"},
"bytes": {"type": "integer", "minimum": 0}
}
},
"partialArtifact": {
"type": "object",
"required": ["path", "sha256", "bytes"],
"properties": {
"path": {"$ref": "common.schema.json#/$defs/relPath"},
"sha256": {"$ref": "common.schema.json#/$defs/sha256"},
"bytes": {"type": "integer", "minimum": 0}
}
},
"returnedModel": {"type": ["string", "null"]},
"errorType": {"type": "string", "minLength": 1},
"error": {
"description": "The provider's error, whitelisted and scrubbed: never a raw body, URL, prompt or credential. Closed object (additionalProperties false).",
"type": "object",
"properties": {
"httpStatus": {"type": "integer"},
"code": {"type": "string"},
"type": {"type": "string"},
"param": {"type": "string"},
"message": {"type": "string", "maxLength": 300},
"requestId": {"type": "string"}
},
"additionalProperties": false
},
"providerUsage": {"type": "object", "additionalProperties": {"type": "integer", "minimum": 0}},
"receipt": {
"type": "object",
"required": ["startedAt", "attempt", "toolVersion"],
"properties": {
"startedAt": {"$ref": "common.schema.json#/$defs/timestamp"},
"submittedAt": {"anyOf": [{"$ref": "common.schema.json#/$defs/timestamp"}, {"type": "null"}]},
"completedAt": {"anyOf": [{"$ref": "common.schema.json#/$defs/timestamp"}, {"type": "null"}]},
"wallMs": {"type": ["integer", "null"], "minimum": 0},
"providerMs": {"type": ["integer", "null"], "minimum": 0},
"attempt": {"type": "integer", "minimum": 1},
"purpose": {"type": ["string", "null"]},
"toolVersion": {"type": "string", "minLength": 1},
"outcomeCode": {"type": ["string", "null"]}
}
},
"estimate": {
"description": "List-price estimate: usd is null when a needed price row is missing (basis then names it); items are the priced units (unit, quantity, usdEach, usd, source, verifiedAt and any row qualifiers).",
"type": "object",
"required": ["usd", "basis", "pricesVersion"],
"properties": {
"usd": {"type": ["number", "null"], "minimum": 0},
"currency": {"const": "USD"},
"basis": {"type": "string", "minLength": 1},
"pricesVersion": {"type": "string", "minLength": 1},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"unit": {"type": "string", "minLength": 1},
"quantity": {"type": "number", "minimum": 0},
"usdEach": {"type": "number", "minimum": 0},
"usd": {"type": "number", "minimum": 0}
}
}
}
}
},
"fingerprint": {"$ref": "common.schema.json#/$defs/sha256"},
"cliRun": {
"description": "The local CLI run: cwd is the run folder's name (never an absolute path), version and versionText the CLI's, recipe the versioned invocation recipe, home and sourceRel where the CLI wrote its output (relative to CODEX_HOME or GROK_HOME), verifiedBefore whether the route was VERIFIED when the run started.",
"type": "object",
"required": ["tool", "runId", "cwd", "startedAt"],
"properties": {
"tool": {"type": "string", "minLength": 1},
"runId": {"type": "string", "minLength": 1},
"cwd": {"type": "string", "minLength": 1},
"startedAt": {"$ref": "common.schema.json#/$defs/timestamp"},
"threadId": {"type": "string"},
"sessionId": {"type": "string"},
"version": {"type": ["string", "null"]},
"versionText": {"type": ["string", "null"]},
"recipe": {"type": "string", "pattern": "^[a-z0-9-]+/[0-9]+$"},
"home": {"enum": ["CODEX_HOME", "GROK_HOME"]},
"sourceRel": {"type": "string", "pattern": "^\\*/[0-9A-Za-z][0-9A-Za-z_-]{7,79}/(images|videos)/[0-9A-Za-z_.-]{1,120}$"},
"verifiedBefore": {"type": "boolean"}
}
},
"artSource": {"$ref": "common.schema.json#/$defs/artSource"},
"outputDir": {"$ref": "common.schema.json#/$defs/relPath"},
"adoptedAt": {"$ref": "common.schema.json#/$defs/timestamp"},
"adoption": {
"description": "How the artifact was taken from the CLI's own output: method native-run-folder (a cli_media run or resume --adopt), codex-thread-folder or codex-thread-rollout (adopt --codex-thread). source is symbolic (CODEX_HOME/... or GROK_HOME/sessions/*/...), never an absolute path.",
"type": "object",
"required": ["method", "source", "sourceSha256"],
"properties": {
"method": {"type": "string", "minLength": 1},
"source": {"type": "string", "pattern": "^(CODEX_HOME|GROK_HOME)/"},
"sourceSha256": {"$ref": "common.schema.json#/$defs/sha256"},
"sourceMtime": {"type": ["string", "null"]},
"freshAfter": {"anyOf": [{"$ref": "common.schema.json#/$defs/timestamp"}, {"type": "null"}]},
"threadId": {"type": "string"},
"checks": {"type": "array", "items": {"type": "string"}},
"finalAnswerNamesFile": {"type": "boolean"}
}
}
},
"allOf": [
{"if": {"properties": {"schemaVersion": {"const": 2}}, "required": ["schemaVersion"]}, "then": {"required": ["receipt", "estimate", "fingerprint"]}},
{"if": {"properties": {"status": {"const": "done"}}, "required": ["status"]}, "then": {"required": ["artifact"]}}
]
},
"ledger_line_v1": {
"description": "One line of <project>/.forge/ledger.jsonl. A reservation is appended before sending and later lines with the same reservationId commit it (readers fold per reservationId; the last line wins). An unknown outcome keeps the reservation counted against the caps. reservedUsd is null for an unpriced request.",
"type": "object",
"required": ["ts", "reservationId", "jobDir", "fingerprint", "provider", "model", "kind", "route", "reservedUsd", "status", "quotaCall"],
"properties": {
"schema": {"const": "generate2dmedia.ledger_line.v1"},
"ts": {"$ref": "common.schema.json#/$defs/timestamp"},
"jobDir": {"type": "string", "minLength": 1},
"fingerprint": {"$ref": "common.schema.json#/$defs/sha256"},
"provider": {"type": "string", "minLength": 1},
"model": {"type": "string", "minLength": 1},
"kind": {"type": "string", "minLength": 1},
"route": {"enum": ["rest", "codex-cli", "grok-cli", "grok-acp"]},
"reservedUsd": {"type": ["number", "null"], "minimum": 0},
"actualUsd": {"type": ["number", "null"], "minimum": 0},
"status": {"enum": ["reserved", "done", "failed", "unknown", "not_sent"]},
"quotaCall": {"type": "boolean"},
"reservationId": {"type": "string", "minLength": 1}
}
},
"batch_progress_v1": {
"description": "<jobs stem>.progress.json written by generate_media.py batch --execute and cli_media.py batch after every dispatch and result. results hold one entry per finished job (generated, reused, left-for-human or failed, with its outcomeCode); inFlight and remaining are job ids. stopped means an account-level, unknown or possibly charged outcome stopped dispatching (nothing is retried) and stopReason says which; complete means no job is left or in flight. jobsFile and results[].jobDir are POSIX paths relative to the progress file's folder (per D25, never absolute; '..' segments are allowed). No tool reads a progress file back.",
"type": "object",
"required": ["schema", "jobsFile", "execution", "workers", "startedAt", "updatedAt", "results", "inFlight", "remaining", "stopped", "stopReason", "complete"],
"properties": {
"schema": {"const": "generate2dmedia.batch_progress.v1"},
"jobsFile": {"$ref": "common.schema.json#/$defs/relPath"},
"execution": {"enum": ["dry-run", "execute"]},
"workers": {"type": "integer", "minimum": 1},
"startedAt": {"$ref": "common.schema.json#/$defs/timestamp"},
"updatedAt": {"anyOf": [{"$ref": "common.schema.json#/$defs/timestamp"}, {"type": "null"}]},
"results": {
"type": "array",
"items": {
"type": "object",
"required": ["id", "status", "outcomeCode", "jobDir"],
"properties": {
"id": {"type": "string", "pattern": "^[A-Za-z0-9_.-]{1,80}$"},
"status": {"enum": ["generated", "reused", "left-for-human", "failed"]},
"outcomeCode": {"type": "string", "minLength": 1},
"jobDir": {"$ref": "common.schema.json#/$defs/relPath"},
"priorStatus": {"type": ["string", "null"]},
"artifact": {"$ref": "common.schema.json#/$defs/relPath"},
"estimateUsd": {"type": ["number", "null"], "minimum": 0},
"error": {"type": "string"}
},
"if": {"properties": {"status": {"const": "generated"}}, "required": ["status"]},
"then": {"required": ["artifact"]}
}
},
"inFlight": {"type": "array", "items": {"type": "string", "pattern": "^[A-Za-z0-9_.-]{1,80}$"}},
"remaining": {"type": "array", "items": {"type": "string", "pattern": "^[A-Za-z0-9_.-]{1,80}$"}},
"stopped": {"type": "boolean"},
"stopReason": {"type": ["string", "null"]},
"complete": {"type": "boolean"}
},
"allOf": [
{"if": {"properties": {"stopped": {"const": true}}, "required": ["stopped"]}, "then": {"properties": {"stopReason": {"type": "string", "minLength": 1}}}},
{"if": {"properties": {"complete": {"const": true}}, "required": ["complete"]}, "then": {"properties": {"inFlight": {"maxItems": 0}, "remaining": {"maxItems": 0}}}}
]
},
"doctor_v1": {
"description": "forge_doctor.py --json. Each check climbs the readiness ladder; FAIL and MISSING always carry a remedy. routes says which art routes are usable: keys image, image_edit, video, clip and code_art, each {route, status (ready, blocked, fallback, limited, unknown or none), detail, options?}, where route is api:openai, api:xai, host_image, host_image_edit, host_video, local:codex-cli, local:grok-cli, local:grok-acp, ffmpeg, png-frames, codeart2d or none. The order is the owner's (2026-10-06), the one route_media.py uses: the API when a key is configured (a configured key is the owner's consent), then local (the calling agent's own tool, then the user's signed-in Codex and Grok CLIs; an installed CLI is ready and its first successful run records the VERIFIED proof), then codeart2d, which is the explicit-only last resort (status fallback). options lists every candidate as {route, status, detail, consent? (paid, quota or host), level?, label?, model?, verified?}, where label is the user-facing route name (OpenAI API, xAI API, Codex (local CLI), Grok (local CLI) in one-shot image or ACP video mode). apiKeys says which API providers have a key configured (in the environment or the user config file): booleans only, never a key. routeOrder lists, per need (image, image_edit, video), the ready routes in order, ending with codeart2d. proofs holds the version-keyed verification records {level, version, recipe, verifiedAt, matchesInstalled} by <route>:<tool>. The report also has the tool, createdAt, the overall verdict, the declared host tools, the per-capability ladder of every CLI route in cli and elapsedMs; saved appears on stdout only.",
"type": "object",
"required": ["schema", "checks", "routes"],
"properties": {
"schema": {"const": "generate2dmedia.doctor.v1"},
"tool": {"$ref": "common.schema.json#/$defs/toolInfo"},
"createdAt": {"$ref": "common.schema.json#/$defs/timestamp"},
"overall": {"enum": ["OK", "WARN", "FAIL"]},
"host": {"type": "object"},
"cli": {"type": "object"},
"apiKeys": {"type": "object", "additionalProperties": {"type": "boolean"}},
"routeOrder": {"type": "object", "additionalProperties": {"type": "array", "items": {"type": "string", "minLength": 1}}},
"elapsedMs": {"type": "integer", "minimum": 0},
"saved": {"type": "string"},
"checks": {
"type": "array",
"items": {
"type": "object",
"required": ["id", "status"],
"properties": {
"id": {"type": "string", "minLength": 1},
"status": {"enum": ["OK", "WARN", "FAIL", "MISSING", "AGENT", "UNKNOWN"]},
"detail": {"type": "string"},
"remedy": {"type": "string", "minLength": 1}
},
"if": {"properties": {"status": {"enum": ["FAIL", "MISSING"]}}, "required": ["status"]},
"then": {"required": ["remedy"]}
}
},
"routes": {"type": "object"},
"proofs": {"type": "object"}
}
},
"prices_v1": {
"description": "prices.json: one row per provider, model, billing unit and qualifiers (resolution, quality, size; a row that names a qualifier only matches requests with that value), each with its source and the calendar date it was verified. version becomes estimate.pricesVersion. A request with no matching row is unpriced; nothing is extrapolated.",
"type": "object",
"required": ["schema", "rows"],
"properties": {
"schema": {"const": "generate2dmedia.prices.v1"},
"version": {"type": "string", "minLength": 1},
"currency": {"const": "USD"},
"notes": {"type": "string"},
"rows": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": ["provider", "model", "unit", "usd", "source", "verifiedAt"],
"properties": {
"provider": {"type": "string", "minLength": 1},
"model": {"type": "string", "minLength": 1},
"unit": {"type": "string", "minLength": 1},
"resolution": {"type": "string", "minLength": 1},
"quality": {"type": "string", "minLength": 1},
"size": {"type": "string", "minLength": 1},
"usd": {"type": "number", "minimum": 0},
"source": {"type": "string", "minLength": 1},
"verifiedAt": {"type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"}
}
}
}
}
},
"route_proofs_v1": {
"description": "<project>/.forge/route-proofs.json written by cli_media.py: version-keyed evidence that an opt-in CLI route works. A record is valid only for its route, native tool, CLI version and recipe; forge_doctor.py reads it for the TOOL_EXPOSED and VERIFIED ladder steps. A VERIFIED record names the artifact it produced; after a CLI update the route is verified again (per D23 the CLI version is part of the verification request's fingerprint).",
"type": "object",
"required": ["schema", "proofs"],
"properties": {
"schema": {"const": "generate2dmedia.route_proofs.v1"},
"proofs": {
"type": "array",
"items": {
"type": "object",
"required": ["route", "tool", "version", "recipe", "level", "verifiedAt"],
"properties": {
"route": {"enum": ["codex-cli", "grok-cli", "grok-acp"]},
"tool": {"enum": ["image_gen", "image_edit", "image_to_video"]},
"version": {"type": "string", "minLength": 1},
"versionText": {"type": "string", "minLength": 1},
"recipe": {"type": "string", "pattern": "^[a-z0-9-]+/[0-9]+$"},
"level": {"enum": ["TOOL_EXPOSED", "VERIFIED"]},
"verifiedAt": {"$ref": "common.schema.json#/$defs/timestamp"},
"runId": {"type": "string", "pattern": "^[0-9a-f]{32}$"},
"method": {"type": "string"},
"jobDir": {"$ref": "common.schema.json#/$defs/relPath"},
"artifactSha256": {"$ref": "common.schema.json#/$defs/sha256"}
},
"if": {"properties": {"level": {"const": "VERIFIED"}}, "required": ["level"]},
"then": {"required": ["artifactSha256"]}
}
}
}
}
}
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |