OpenParable
Skip to content
← Back to skills

Runware API

Apps & Automation
runware-api

Runware 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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 taskUUID must use a fresh UUID v4. Preserve and log the UUID for debugging and async polling.
  • Match responses to requests by taskUUID and taskType; 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 getResponse task:
[
  {
    "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.
  • getResponse can return processing, success, or error; completed generations can appear before the whole task is finished.

Error And Retry Rules

  • Runware errors are returned in an errors array. Multiple-task requests can have some successful data entries and some scoped errors.
  • Log the full message and taskUUID; the UUID is important for support.
  • Retry only transient failures with exponential backoff: HTTP 429, HTTP 5xx, and capacity/provider codes such as timeoutProvider or providerRateLimitExceeded.
  • 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 v4 taskUUID.
  • Use runware:101@1 only as a quick FLUX.1 Dev starting point; search or inspect model docs when style, cost, speed, or capability matters.
  • negativePrompt is 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, .env files, generated request payloads containing keys, or downloaded private outputs.
  • Prefer RUNWARE_API_KEY in 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.