content3

Content3 API，用于创建视频、管理内容、提交评论以及发布到社交媒体。

## 概述（中文）

Content3 API，用于创建视频、管理内容、提交评论以及发布到社交媒体。

## 原文

# content3

Use the Content3 Agent API to create short-form videos, manage content libraries, submit reviews for human approval, and draft social media posts.

## Setup

1. Log in to your Content3 dashboard
2. Navigate to **Settings → API Keys**
3. Click **Create API Key** — copy the key (starts with `c3ak_`, shown only once)
4. Store it:
```bash
mkdir -p ~/.config/content3
echo "c3ak_your_key_here" > ~/.config/content3/api_key
```

## API Basics

Base URL: `https://api.content3.app/v1`

All requests need:
```bash
C3_KEY=$(cat ~/.config/content3/api_key)
curl -X GET "https://api.content3.app/v1/..." \
  -H "Authorization: Bearer $C3_KEY" \
  -H "Content-Type: application/json"
```

> **Note:** Agent API keys have scopes that control access. Default scopes: `content:read`, `social:generate`, `social:drafts:read`, `social:drafts:write`. Ask the user to grant additional scopes if needed.

## Authentication

**Verify your key:**
```bash
curl "https://api.content3.app/v1/me" \
  -H "Authorization: Bearer $C3_KEY"
```

Returns: `{ "userId", "keyId", "keyName", "scopes": [...] }`

### Scopes Reference

| Scope | Access |
|-------|--------|
| `content:read` | Read content items, render jobs, social connections, short-form options |
| `content:write` | Create/modify content |
| `reviews:read` | Read reviews |
| `reviews:write` | Create reviews and comments |
| `social:generate` | Generate AI social media content |
| `social:drafts:read` | Read social media drafts |
| `social:drafts:write` | Create social media drafts |
| `products:read` | Read products |
| `products:write` | Create/modify products |
| `*` | Full access (all scopes) |

## Short-Form Video Generation

This is the primary agent workflow — generate short-form videos from various sources.

**Get available options (voices, sources, aspect ratios):**
```bash
curl "https://api.content3.app/v1/agents/short-form/options" \
  -H "Authorization: Bearer $C3_KEY"
```

Returns source types (`quora`, `reddit`, `prompt`, `text`), voice options (Kore, Puck, Charon, Fenrir, Zephyr, Aoede, Orbit, Orus), and aspect ratios (`9:16`, `16:9`).

**Generate a video from a prompt:**
```bash
curl -X POST "https://api.content3.app/v1/agents/short-form/generate" \
  -H "Authorization: Bearer $C3_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "prompt",
      "prompt": "Explain why cats always land on their feet"
    },
    "voiceId": "Kore",
    "aspectRatio": "9:16",
    "saveToLibrary": true
  }'
```

**Generate from a Reddit post:**
```bash
curl -X POST "https://api.content3.app/v1/agents/short-form/generate" \
  -H "Authorization: Bearer $C3_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "reddit",
      "url": "https://reddit.com/r/..."
    },
    "voiceId": "Puck",
    "aspectRatio": "9:16"
  }'
```

**Generate from a Quora answer:**
```bash
curl -X POST "https://api.content3.app/v1/agents/short-form/generate" \
  -H "Authorization: Bearer $C3_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "quora",
      "url": "https://quora.com/..."
    },
    "voiceId": "Zephyr"
  }'
```

**Generate from raw text:**
```bash
curl -X POST "https://api.content3.app/v1/agents/short-form/generate" \
  -H "Authorization: Bearer $C3_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "text",
      "text": "Your script or content here..."
    },
    "voiceId": "Fenrir",
    "aspectRatio": "16:9"
  }'
```

Returns: `{ "success": true, "jobId": "uuid", "status": "queued", "taskName": "..." }`

## Render Jobs

Track the status of video generation jobs.

**List render jobs:**
```bash
curl "https://api.content3.app/v1/render-jobs?status=completed&limit=10" \
  -H "Authorization: Bearer $C3_KEY"
```

Query params: `status` (queued, processing, completed, failed), `agent_type`, `job_type`, `limit` (max 100), `offset`.

**Get a specific job:**
```bash
curl "https://api.content3.app/v1/render-jobs/{job_id}" \
  -H "Authorization: Bearer $C3_KEY"
```

Returns full job details including `payload`, `status`, `output_url`, timestamps.

## Content Items

Manage your content library.

**List content items:**
```bash
curl "https://api.content3.app/v1/content-items?type=video&limit=20" \
  -H "Authorization: Bearer $C3_KEY"
```

Query params: `type`, `limit` (max 100, default 20), `offset`.

Returns: `{ "items": [{ "id", "type", "title", "description", "source_url", "thumbnail_url", "created_at" }] }`

## Reviews (Human-in-the-Loop)

Submit content for human review and approval before publishing.

**Create a review:**
```bash
curl -X POST "https://api.content3.app/v1/reviews" \
  -H "Authorization: Bearer $C3_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly video batch - Feb 18",
    "description": "5 short-form videos for review before publishing",
    "contentType": "video",
    "attachments": [
      {"url": "https://r2.example.com/video1.mp4", "label": "Cat facts video"},
      {"url": "https://r2.example.com/video2.mp4", "label": "Tech tips video"}
    ],
    "metadata": {
      "tags": ["short-form", "batch"],
      "notes": "Generated from trending Reddit posts"
    }
  }'
```

Content types: `pdf`, `video`, `image`, `slides`, `markdown`.

**List reviews:**
```bash
curl "https://api.content3.app/v1/reviews?status=pending&limit=10" \
  -H "Authorization: Bearer $C3_KEY"
```

Status values: `pending`, `approved`, `rejected`, `needs_revision`.

**Get review with comments:**
```bash
curl "https://api.content3.app/v1/reviews/{review_id}" \
  -H "Authorization: Bearer $C3_KEY"
```

**Add a comment to a review:**
```bash
curl -X POST "https://api.content3.app/v1/reviews/{review_id}/comments" \
  -H "Authorization: Bearer $C3_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "Revised the thumbnail based on feedback"}'
```

### Update Review Status

**Update a review's status:**
```bash
curl -X PATCH "https://api.content3.app/v1/reviews/{review_id}" \
  -H "Authorization: Bearer $C3_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "in_review"}'
```

Valid transitions: `pending` → `in_review`, `in_review` → `approved` / `rejected` / `changes_requested`, `changes_requested` → `in_review`.

Returns: `{ "review": { "id": "uuid", "status": "in_review", "updatedAt": "..." } }`

### Review Revisions

Submit updated attachments when changes are requested. The platform tracks all versions.

**Submit a revision:**
```bash
curl -X POST "https://api.content3.app/v1/reviews/{review_id}/revisions" \
  -H "Authorization: Bearer $C3_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attachments": [
      {"url": "https://r2.example.com/video1-v2.mp4", "label": "Fixed background color"}
    ],
    "note": "Fixed the background color as requested"
  }'
```

If no revisions exist yet, revision 1 is automatically created from the current attachments (labeled "Original"). The new revision becomes the latest, and `reviews.attachments` is updated.

**List revisions:**
```bash
curl "https://api.content3.app/v1/reviews/{review_id}/revisions" \
  -H "Authorization: Bearer $C3_KEY"
```

Returns: `{ "revisions": [{ "revisionNumber": 1, "attachments": [...], "note": "Original", "agentKeyName": "...", "createdAt": "..." }, ...] }`

### Shareable Review Links

Generate a public share link for a review so humans can view and comment without logging in.

**Create or get a share link:**
```bash
curl -X POST "https://api.content3.app/v1/reviews/{review_id}/share" \
  -H "Authorization: Bearer $C3_KEY"
```

Returns: `{ "shareToken": "...", "shareUrl": "https://content3.app/review/...", "shareEnabled": true }`

If a share link already exists, this returns the existing link and ensures it is enabled.

**Toggle share link on/off:**
```bash
curl -X PATCH "https://api.content3.app/v1/reviews/{review_id}/share" \
  -H "Authorization: