# Renderful AI - Full Agent Integration Reference

> Version: 1.1.0
> Canonical base URL: `https://api.renderful.ai/api/v1`

## 1) Overview

Renderful is an agent-native generation API supporting:
- text-to-image
- image-to-image
- text-to-video
- image-to-video
- video-to-video
- reference-to-video
- text-to-audio
- text-to-music
- lip-sync
- text/image-to-3d

## 2) Authentication Modes

### Mode A: API key (rf_)

```http
Authorization: Bearer rf_your_api_key
```

### Mode B: x402 permissionless payments

```http
x-payment: <base64-encoded payment payload>
```

x402 is accepted on `POST /api/v1/generations`.

## 3) Agent Onboarding Flow

### Step 1. Register

```http
POST /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"
}
```

Success response includes:
- `agent_id`
- `api_key` (shown once)
- `deposit_addresses`
- `balance`
- `starting_balance`
- `trial_credit_applied`
- `activation_tips`

### Step 2. Quote before generating

```http
POST /api/v1/agents/quote
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{
  "type": "text-to-video",
  "model": "hailuo-2.3",
  "resolution": "720p"
}
```

### Step 3. Generate

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

{
  "type": "text-to-image",
  "model": "flux-dev",
  "prompt": "A clean product hero shot of headphones"
}
```

### Step 4. Poll

```http
GET /api/v1/generations/{id}
Authorization: Bearer rf_your_api_key
```

## 4) Core Endpoints

- `GET /api/v1/models`
- `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}`

## 5) Generation Request Schema (high-level)

Required fields:
- `type`
- `model`

Common optional fields:
- `prompt`
- `negative_prompt`
- `image_url`
- `video_url`
- `audio_url`
- `images[]`
- `videos[]`
- `aspect_ratio`
- `resolution`
- `duration`
- `num_outputs`
- `seed`
- `webhook_url`

## 6) Payment

- Currency: USD
- Prepaid asset: USDC
- Supported chains: Base, Polygon, Ethereum
- Deposit endpoint: `POST /api/v1/agents/deposit`
- x402 header: `x-payment`

## 7) Webhooks

Configure with:

```http
PATCH /api/v1/agents/webhook
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{ "webhook_url": "https://example.com/webhook" }
```

Webhook verification:
- header: `X-Webhook-Signature`
- algorithm: `HMAC-SHA256`

## 8) Discoverability URLs

- `https://api.renderful.ai/.well-known/agents.json`
- `https://api.renderful.ai/.well-known/ai-plugin.json`
- `https://api.renderful.ai/llms.txt`
- `https://api.renderful.ai/llms-full.txt`
- `https://api.renderful.ai/api/v1/openapi.json`

## 9) Compatibility + Deprecations

Deprecated aliases (temporary):
- `GET /api/v1/predictions/{taskId}/result` -> `GET /api/v1/generations/{id}`
- `/v1/*` -> `/api/v1/*`

Deprecated aliases return `Deprecation` and `Sunset` headers.

## 10) OpenAPI

Use this as source of truth for tools and SDKs:
- `GET https://api.renderful.ai/api/v1/openapi.json`