# Renderful AI API (Agent Quickstart)

> Agent-native API for image, video, audio, 3D, and LLM generation.

## Base URLs

- API: https://api.renderful.ai/api/v1
- OpenAPI: https://api.renderful.ai/api/v1/openapi.json
- Docs: https://api.renderful.ai/docs

## Authentication

1. API key auth (recommended):
- Header: `Authorization: Bearer rf_...`

2. x402 payment auth (permissionless):
- Header: `x-payment: <base64-encoded x402 payload>`
- Used on `POST /api/v1/generations`

## Core Agent Endpoints

- `POST /api/v1/agents/register`
- `POST /api/v1/agents/deposit`
- `GET /api/v1/agents/balance`
- `POST /api/v1/agents/quote`
- `PATCH /api/v1/agents/webhook`
- `POST /api/v1/generations`
- `GET /api/v1/generations/{id}`
- `GET /api/v1/models`

## Register Agent

```http
POST https://api.renderful.ai/api/v1/agents/register
Content-Type: application/json

{
  "agent_name": "MyAgent",
  "webhook_url": "https://example.com/webhook",
  "source": "directory",
  "agent_platform": "openclaw",
  "agent_version": "1.0.0"
}
```

## Generate Content

```http
POST https://api.renderful.ai/api/v1/generations
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{
  "type": "text-to-image",
  "model": "flux-dev",
  "prompt": "A cinematic shot of a futuristic city at sunset"
}
```

LLM/text example:

```http
POST https://api.renderful.ai/api/v1/generations
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{
  "type": "text-to-text",
  "model": "kimi-k2.5",
  "prompt": "Summarize this in 3 bullets",
  "system_prompt": "Be concise.",
  "max_tokens": 512,
  "temperature": 0.7
}
```

OpenAI-style messages are also accepted for `text-to-text`:

```json
{
  "type": "text-to-text",
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Draft a short release note." }
  ],
  "max_tokens": 300
}
```

Use `/api/v1/generations` for LLM requests. Do not call `/v1/chat/completions` on Renderful.
Discover LLM catalog via `GET /api/v1/models?type=text-to-text` (includes all currently available LLM models).

Response includes:
- `id`
- `status` (queued)
- `poll_url`

Poll status:

```http
GET https://api.renderful.ai/api/v1/generations/{id}
Authorization: Bearer rf_your_api_key
```

`GET /api/v1/generations/{id}` returns `output`/`outputs`. For `text-to-text`, output points to a generated text artifact URL.

## Deprecated Aliases

- `/api/v1/predictions/{taskId}/result` -> use `/api/v1/generations/{id}`
- `/v1/*` -> use `/api/v1/*`

## Contact

- support@renderful.ai