# Transcripto — Document Transcription API

Simple API for AI agents to transcribe PDFs, JPGs, and PNGs. Upload a file, get the text back.

## Quick Start for AI Agents

### Step 1: Register with your email

```bash
curl -X POST https://transcrip.to/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email": "your-agent@example.com"}'
```

Response:
```json
{
  "data": {
    "email": "your-agent@example.com",
    "email_verified": false,
    "api_key": "1|your-api-key-here",
    "credits_remaining": 0
  },
  "meta": {
    "note": "Account created. Use /api/v1/fake-transcribe to build your integration.",
    "claim_url": "https://example.com/claim/your-token"
  }
}
```

Save the `api_key` — you need it for all subsequent requests.

### Step 2: Build your integration with the test endpoint

```bash
curl -X POST https://transcrip.to/api/v1/fake-transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"
```

Response:
```json
{
  "data": {
    "id": 0,
    "text": "Lorem ipsum dolor sit amet...",
    "file_type": "application/pdf",
    "pages": 1
  },
  "meta": {
    "credits_used": 0,
    "credits_remaining": 0
  }
}
```

This endpoint always returns Lorem Ipsum. No credits needed. Same response format as the real endpoint.

### Step 3: Ask your human to activate the account

Share the `claim_url` from Step 1 with your human operator. They visit the link, set a password, and the account gets verified. After that, `/api/v1/transcribe` is unlocked.

---

## Quick Start for Humans

1. **Register** at https://transcrip.to/register with email and password.
2. **Create an API key** in the dashboard under "API Keys". Copy it and give it to your AI agent.
3. **Buy credits** in the dashboard under "Credits". 1 credit = 1 transcription.

---

## API Reference

### Authentication

All requests require a Bearer token in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

AI agents: use `POST /api/v1/register` to get a key instantly.
Humans: register at https://transcrip.to/register, then create a key in the dashboard.

---

### POST /api/v1/register

Create an account with just an email. Returns an API key immediately. No password needed. Rate limited to 3 per hour per IP.

```bash
curl -X POST https://transcrip.to/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email": "agent@example.com"}'
```

Response (201):
```json
{
  "data": {
    "email": "agent@example.com",
    "email_verified": false,
    "api_key": "1|abc123...",
    "credits_remaining": 0
  },
  "meta": {
    "note": "Account created. Use /api/v1/fake-transcribe to build your integration.",
    "claim_url": "https://example.com/claim/token..."
  }
}
```

---

### GET /api/v1/me

Check your account info and credit balance.

```bash
curl https://transcrip.to/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response (200):
```json
{
  "data": {
    "name": "John Doe",
    "email": "john@example.com",
    "credits_remaining": 42
  }
}
```

---

### POST /api/v1/fake-transcribe

Test endpoint. Identical to `/api/v1/transcribe` but always returns Lorem Ipsum. No credits needed. Available to all users (verified and unverified).

```bash
curl -X POST https://transcrip.to/api/v1/fake-transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"
```

Response (200):
```json
{
  "data": {
    "id": 0,
    "text": "Lorem ipsum dolor sit amet...",
    "file_type": "application/pdf",
    "pages": 1
  },
  "meta": {
    "credits_used": 0,
    "credits_remaining": 0
  }
}
```

---

### POST /api/v1/transcribe

Upload a single-page PDF, JPG, or PNG (max 10MB) and get the extracted text back. Costs 1 credit. Requires a verified account (email verified via claim flow).

```bash
curl -X POST https://transcrip.to/api/v1/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"
```

Response (200):
```json
{
  "data": {
    "id": 42,
    "text": "Extracted content from your document...",
    "file_type": "application/pdf",
    "pages": 1
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 41
  }
}
```

---

## Error Handling

All errors use the same format:

```json
{
  "error": {
    "code": "error_code",
    "message": "Human-readable message."
  }
}
```

| Status | Code                   | Description                                  |
|--------|------------------------|----------------------------------------------|
| 401    | `unauthenticated`      | Invalid or missing API key                   |
| 402    | `insufficient_credits` | No credits remaining                         |
| 403    | `email_not_verified`   | Account not verified — claim it first        |
| 422    | `validation_error`     | Wrong file type, too large, or multi-page PDF|
| 429    | `too_many_requests`    | Rate limit exceeded (60/min)                 |

---

## Rate Limiting

60 requests per minute per user, shared across all API keys. Rate limit info is included in response headers.

---

## Pricing

| Package      | Price  |
|-------------|--------|
| 100 Credits  | $5.00  |
| 500 Credits  | $20.00 |
| 1,000 Credits| $35.00 |

1 credit = 1 transcription. No expiration. Buy credits at https://transcrip.to/credits after verifying your account.