fetch, full type safety.
Installation
Quick Start
RUNCRATE_API_KEY environment variable instead of passing apiKey.
Configuration
Retries and launches
Reads, updates and deletes are retried on 429, 5xx, timeouts and lost connections, honouringRetry-After up to 60 seconds. A request that creates or launches something is never sent twice by accident:
- Job submits and reruns send an
Idempotency-Key(a new one per call, reused on its retries), which the server honours, so they are retried like reads: a retry after a timeout answers the first job. - Instance, schedule and volume creates also send an
Idempotency-Key, but those routes do not deduplicate it yet;schedules.runNowsends none. Once one of these, or a run-now, may have reached Runcrate (a timeout, a lost connection, a 500, 502 or 504), it is not sent again and the error is thrown: checkrc.instances.list()before launching again. Only a 429 or 503, which say nothing was launched, and a connection that never opened are retried. - A launch waits at least 75 seconds for its answer (a job submit 135), whatever
timeoutis, so the client does not give up while the server is still launching. - A
502withcodelaunch_refusedis never retried: the same request is refused the same way.
Environments
API keys are workspace-scoped. By default, requests target the workspace’s default environment (usuallymain). Pass environment at client construction to target a different one:
Model Inference
All inference methods hitapi.runcrate.ai.
Chat Completions
Streaming
Image Generation
Model-Specific Parameters
All inference methods accept extra parameters that get passed through to the model. Different models support different parameters:Video Generation
seed, negative_prompt, image for image-to-video) are passed through:
Text-to-Speech
speed or language are passed through:
Transcription
responseFormat you get the full object: text, duration, language and timed segments (the same as verbose_json). json gives text only.
Infrastructure Management
GPU Instances
maxRuntimeMinutes and idleShutdownMinutes are optional and off when omitted. After an instance stops, stopReason (type InstanceStopReason) says why: user, max_runtime, idle, budget, low_balance, failed or system. See Spend guardrails.
Environment Budgets
InsufficientCreditsError with err.code === 'BUDGET_REACHED'.
Schedules
A schedule starts an instance or a job later. Pass exactly one ofrunAt (once) or cron (repeating, read in timezone). spec is the create body of the kind, and maxRuntimeMinutes is required in it.
Jobs
A job runs one command on its own fresh GPU machine, which stops (and stops billing) when the command ends. Files the command writes to$RUNCRATE_OUTPUT_DIR are kept 30 days.
const upload = await rc.jobs.uploads.upload('./code.tar.gz') (a path to a tar.gz, or its bytes, at most 1 GB) and run with code: { uploadId: upload.uploadId } within 24 hours. The command runs in /workspace/code.
Pass your own
idempotencyKey to make a submit safe to repeat across processes: the same key with the same request answers the first job for 24 hours (see Idempotency). A low balance throws InsufficientCreditsError, a reached environment budget the same with code BUDGET_REACHED, and a bad field UnprocessableEntityError.
Secrets
The names of the secrets every machine in the client’s environment gets. Values are set in the dashboard and never returned. A value passed for one launch (envVars) wins over a secret of the same name.
SSH Keys
Storage
Storage volumes are environment-scoped. Your workspace’s storage must be set up in the dashboard first; the SDK picks it up automatically.$0.03/GB/month, charged weekly in advance. Deletion refunds the unused portion of the current billing week.
Billing
idempotencyKey, topUp makes a UUID and returns it on the answer. See Top up by API for the permission, caps and statuses.
Templates
Error Handling
All API errors include the actual error message from the server, never a generic fallback.err.message: human-readable error description from the APIerr.statusCode: HTTP status codeerr.code: machine-readable error code (e.g.not_found,rate_limited)err.details: additional details (when available)