Runware API
Apps & Automationrunware-apiRunware API is an Agent Skill for apps & automation published in the LayrKits/Sprite-Pipeline repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when making, reviewing, debugging, or scripting Runware API requests. Follow Runware's raw REST/WebSocket request shape, authentication, UUID, async polling, error, retry, and model-selection rules.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/LayrKits/Sprite-Pipeline/blob/HEAD/skills/runware-api/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/runware-api, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Runware API Skill
Use this skill when working with Runware requests in this repo. Prefer the current Runware docs for model-specific parameters, because available models and capabilities change often.
Docs To Check
- Platform intro:
https://runware.ai/docs/platform/introduction - Authentication:
https://runware.ai/docs/platform/authentication - Task polling:
https://runware.ai/docs/platform/task-polling - Errors:
https://runware.ai/docs/platform/errors - Rate limits:
https://runware.ai/docs/platform/rate-limits - Model search:
https://runware.ai/docs/platform/model-search - Text to image guide:
https://runware.ai/docs/guides/text-to-image
Request Rules
- REST endpoint:
https://api.runware.ai/v1. - WebSocket endpoint:
wss://ws-api.runware.ai/v1. - Raw API request bodies are always a JSON array of task objects, even for one task.
- Authenticate REST calls with
Authorization: Bearer <API_KEY>whenever possible. Payload auth is allowed by docs but avoid embedding keys in saved JSON. - For WebSockets, the first message must be an authentication task containing the API key; subsequent messages use the same authenticated connection.
- Every task that accepts
taskUUIDmust use a fresh UUID v4. Preserve and log the UUID for debugging and async polling. - Match responses to requests by
taskUUIDandtaskType; do not assume array order is enough.
Local Helper
This workspace has an ignored local helper at local/runware_request.py.
Examples:
export RUNWARE_API_KEY="..."
python3 local/runware_request.py model-search --search "pixel art" --limit 5
python3 local/runware_request.py text-to-image --prompt "a small airship over a forest"
python3 local/runware_request.py raw request.json
python3 local/runware_request.py poll <taskUUID>
The helper prints the full JSON response, retries transient REST/capacity
failures with exponential backoff, exits nonzero when errors is present, and
uses only Python standard-library modules.
Async And Polling
- For long-running operations, set
"deliveryMethod": "async"when the model or workflow supports it. - Poll with a
getResponsetask:
[
{
"taskType": "getResponse",
"taskUUID": "00000000-0000-4000-8000-000000000000"
}
]
- Use exponential backoff when polling. Start around 1-2 seconds, increase the delay, and add an initial delay for predictable long tasks such as video.
getResponsecan returnprocessing,success, orerror; completed generations can appear before the whole task is finished.
Error And Retry Rules
- Runware errors are returned in an
errorsarray. Multiple-task requests can have some successfuldataentries and some scopederrors. - Log the full
messageandtaskUUID; the UUID is important for support. - Retry only transient failures with exponential backoff: HTTP
429, HTTP5xx, and capacity/provider codes such astimeoutProviderorproviderRateLimitExceeded. - Do not blindly retry client errors such as invalid parameters, invalid API keys, missing balance, or permission failures.
- Keep normal concurrency around 2-4 requests unless the user has a capacity agreement or the current docs say otherwise.
Image Generation Defaults
For imageInference text-to-image work:
- Use
taskType: "imageInference". - Include
model,positivePrompt,width,height, and a UUID v4taskUUID. - Use
runware:101@1only as a quick FLUX.1 Dev starting point; search or inspect model docs when style, cost, speed, or capability matters. negativePromptis useful for many diffusion models, but FLUX-style models may ignore it.- Check each model's recommended defaults for dimensions,
steps, scheduler, CFG, and supported extras before assuming parameters are valid.
Secret Handling
- Never commit API keys,
.envfiles, generated request payloads containing keys, or downloaded private outputs. - Prefer
RUNWARE_API_KEYin the shell environment. - If a command fails because the key is missing, ask the user to provide or set the key instead of inventing one.