Runway PLANNED

Premium proprietary provider for voice storage, transcript-to-speech, and talking-head video. Paid API, shared org key - real-money risk, so it ships behind per-job credit ceilings and a daily org-spend guard.

Status: research + plan. No live paid calls have been made. Two items must be verified live before the talking-video tier is promised: (1) a custom voice.id works in text_to_speech (not only Avatars), and (2) Act-Two accepts an audio-only reference (docs suggest video-only). Ship Voice Studio + transcript-to-speech first; gate the video tier on those tests.

Authentication and base URL

Item	Value
Base URL	`https://api.dev.runwayml.com/v1`
Auth header	`Authorization: Bearer <key_...>` (org API key)
Version header	`X-Runway-Version: 2024-11-06` (required on EVERY request)
Content type	`Content-Type: application/json`
Credits	$0.01 per credit. `GET /v1/organization` returns the balance (free auth probe).

Authorization: Bearer key_xxxxxxxxxxxxxxxxxxxxxxxx
X-Runway-Version: 2024-11-06
Content-Type: application/json

Endpoints used

Endpoint	Purpose	Notes
`POST /v1/voices`	Create / store a voice	Clone from a 10 s - 5 min sample (<=10MB) or design from a text prompt. Async - poll `voices.list/get` until `status == READY` (NOT via /v1/tasks).
`GET /v1/voices`	List stored voices	Persistent per org. FlopCoin namespaces voices per-user in its own table and enforces quotas (the org is shared).
`POST /v1/text_to_speech`	Transcript to speech	Model `eleven_multilingual_v2` or `seed_audio`; `voiceId` preset or custom (LIVE-TEST #1). Returns a task id.
`POST /v1/character_performance`	Act-Two talking-head video	5 credits/second, 15-credit (3 s) minimum. `reference` documented as type=video; audio-only is LIVE-TEST #2.
`GET /v1/tasks/{id}`	Poll an async job	PENDING / THROTTLED / RUNNING -> SUCCEEDED \| FAILED \| CANCELLED. On SUCCEEDED, `output` is an array of short-lived result URLs.
`POST /v1/avatars` + realtime	GWM-1 live avatar	The only natively audio-driven talking video, but a real-time WebRTC session (5-min max), not a file render. Future product, not the MVP lane.

Planned FlopCoin modes

Mode	Input	Output
`voice_create`	voice sample or prompt	a stored Runway `voice.id`
`voice_tts`	transcript + voice_id	audio (mp3/wav)
`voice_video`	transcript + voice_id + character	talking-head mp4

Provider tag in generation_requests: provider = 'runway'. It drops into the existing async submit / store external_job_id / poll-to-adopt design (the poller owns polling, not a blocking call).

Official documentation

Docs root: docs.dev.runwayml.com
Custom voices: docs.dev.runwayml.com/characters/custom-voice
Characters / Avatars: docs.dev.runwayml.com/characters
Task failures: docs.dev.runwayml.com/errors/task-failures
Developer portal (keys, credits): dev.runwayml.com