32. Media generation#
Some Rayu plans include hosted image and video models, reachable with the same Rayu API key that serves chat. This page covers the API surface and the credit model.
The v3 CLI has no image or video tool. There is no
/generate-image,/image-editor, or/image-videocommand, and noGenerateImageorGenerateVideotool inside the agent. Media generation is a gateway API feature for your own code, not something the terminal agent drives. Anything you ask the agent to draw, it draws by writing code.
What you need#
| Requirement | Detail |
|---|---|
| Rayu API key | rayu_sk_live_…, sent as Authorization: Bearer <key> or x-api-key |
| Plan | One whose catalog includes the media model you want |
| Base URL | https:/ |
An external provider key (Anthropic, OpenAI, Gemini) does not enable this, and there is no bring-your-own media backend. See API keys and the Rayu API for key creation.
Discover media models#
Media models live in their own catalogs, selected with a query parameter:
curl https://gateway.rayucode.com/v1/models?modality=image \
-H "Authorization: Bearer $RAYU_API_KEY"
curl https://gateway.rayucode.com/v1/models?modality=video \
-H "Authorization: Bearer $RAYU_API_KEY"modality= selects one catalog. The older media=image|video|all filter merges
the BYO and hosted generation catalogs and is still accepted.
Each entry carries its own pricing unit, resolution tier, duration limits, and input capabilities, so read the entry rather than assuming.
| Modality | Endpoint | Catalog query |
|---|---|---|
| Image | POST / | ?modality=image |
| Video | POST / | ?modality=video |
The same key also reaches audio and OCR when the plan includes them:
| Modality | Endpoint | Catalog query |
|---|---|---|
| Speech to text | POST / | ? |
| Text to speech | POST /v1/audio/speech | ? |
| OCR | POST /v1/ocr | ?modality=ocr |
| Realtime ticket | POST / | ? |
Generate an image#
curl https://gateway.rayucode.com/v1/images/generations \
-H "Authorization: Bearer $RAYU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<id from /v1/models?modality=image>",
"prompt": "a watercolor fox reading a book under a streetlamp",
"size": "1024x1024",
"response_format": "b64_json"
}'| Field | Meaning |
|---|---|
model | Catalog id. Required |
prompt | Required |
n | Images to generate. The CLI always sends 1 |
size | WxH. Per side the gateway accepts 256 to 4096, with an aspect ratio between 1:8 and 8:1 |
response_format | b64_json (what the CLI uses) or url |
negative_prompt, seed | Optional sampling controls where the model supports them |
image | Only on entries that advertise the edit capability: an https:// URL or a data:image/ URL |
When the model publishes no default size, the upstream decides. Deriving a size
from an aspect ratio gives a 1024-pixel long side and a short side rounded to a
multiple of 8 and clamped to 512–2048, so 16:9 becomes 1024x576.
The response is the OpenAI images shape: {created, data: [{b64_json|url, revised_prompt}], usage?}, plus a rayu block with the billed image count.
Generate a video#
curl https://gateway.rayucode.com/v1/videos/generations \
-H "Authorization: Bearer $RAYU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<id from /v1/models?modality=video>",
"prompt": "a paper boat drifting down a rainy street at dusk",
"duration": 6,
"ratio": "16:9"
}'| Field | Meaning |
|---|---|
model | Catalog id. Required |
prompt | Required |
duration | Clip length in seconds. Clamped to the entry's published minimum and maximum |
ratio | One of the accepted ratios, or adaptive |
negative_prompt, seed | Optional sampling controls |
image | A reference image, on entries that advertise image-to-video |
Video models publish a default and a maximum duration, and the family default window is 2–30 seconds. A catalog entry can declare its own narrower window, and a request outside the window is clamped rather than refused. Resolution tiers are separate model entries with separate prices, so choosing 720p means choosing the 720p model, not passing a bigger number. There is no resolution parameter.
Video is a slow request. Budget a couple of minutes and set your client timeout accordingly.
Billing#
| Modality | Unit |
|---|---|
| Image | Per generated image |
| Video | Per second of video the gateway actually produced |
| OCR | Per page |
| Speech | Per second or per character, as the catalog entry says |
The gateway is the authoritative meter. It reserves and settles the charge, so the balance change is the record. A locally estimated counter is an approximation.
A request that fails before the model produces output is not charged. A client-side timeout can still be billed if the render finished on the server, so prefer generous client timeouts over retries.
From code#
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["RAYU_API_KEY"],
base_url="https://gateway.rayucode.com/v1",
)
image = client.images.generate(
model=os.environ["RAYU_IMAGE_MODEL"],
prompt="a watercolor fox reading a book under a streetlamp",
size="1024x1024",
)
print(image.data[0].url)The Python and JavaScript OpenAI SDKs work unchanged because the endpoint uses
the OpenAI images shape. Video uses POST /v1/videos/generations, which those
SDKs do not wrap, so call it with fetch or your HTTP client.
Error codes#
| Code | Meaning |
|---|---|
400 | Invalid JSON, unsupported parameter for this model, or a size outside the published bounds |
403 | The model is outside the plan or outside the key's allowlist |
404 | Unknown model id. Re-read the catalog |
429 | Rate or credit limit. Check the reason |
Practical notes#
- Read the catalog before hard-coding an id. Model ids are server-owned and new tiers appear without a client change.
- Cache the catalog for a few minutes; it is cheap but not free.
- Store outputs yourself. The gateway returns a URL or base64 bytes and does not keep a media library for you.
- Treat prompts as untrusted input if they come from users, and cap output size before you write the file.
Next#
Back to API keys and the Rayu API →, or read Credits and limits → for the credit math behind these charges.