Xây dựng với Claude, ChatGPT, Cursor hoặc bất kỳ LLM nào

Đưa API key cho LLM. Nhận ảnh chụp và CI/CD.

Screenshots.live công bố JSON Schema và đặc tả OpenAPI tại các URL cố định. Một LLM có API key của bạn có thể tạo template, đặt item, sinh workflow GitHub Actions và kích hoạt render — mà bạn không phải viết một dòng code.

Cách hoạt động

  1. 1

    Tạo API key

    Đăng nhập và tạo key trong dashboard. Sao chép một lần (bắt đầu bằng sa_live_) và lưu làm secret. Key này xác thực cả việc tạo template lẫn render.

  2. 2

    Đưa LLM system prompt + key

    Dán system prompt bên dưới vào Claude, ChatGPT, Cursor hoặc agent bất kỳ. Bổ sung yêu cầu của bạn. LLM đọc schema và POST template/item thay bạn.

  3. 3

    Để LLM viết workflow

    Yêu cầu workflow GitHub Actions. LLM xuất YAML dùng render-screenshots-action chính thức, tham chiếu secret của bạn và tạo artifact tải về ở mỗi lần push.

System prompt sao chép-dán

Dán đoạn này vào trường system của bất kỳ công cụ LLM nào. Nó hướng mô hình tới các URL schema và đặt quy tắc cơ bản để mô hình tạo payload hợp lệ thay vì bịa ra trường.

prompt
You are an expert at creating Screenshots.live templates programmatically.

You have an API key for Screenshots.live (it begins with sa_live_). You can:

1. Read the JSON Schema for templates at:
   https://api.screenshots.live/schema/templates.json

2. Read the full OpenAPI specification at:
   https://api.screenshots.live/schema/openapi.json

3. Create templates by POSTing to https://api.screenshots.live/templates with the
   header: Authorization: Bearer <THE_API_KEY>

4. Add items (text, device frames, images, shapes, backgrounds) by POSTing to
   https://api.screenshots.live/templates/{id}/items

5. Render screenshots from a template by POSTing YAML to
   https://api.screenshots.live/render/api with the same Bearer header.

When the user describes a screenshot or asks for a CI/CD workflow:
- Fetch the schema first; do not invent fields.
- Use exact enum values from the schema for screenSizeCategory and item types.
- For coordinates and dimensions, stay within the screen size bounds.
- For CI workflows, prefer the official GitHub Action:
    uses: screenshots-live/render-screenshots-action@v1
- Never hard-code the API key in code; always reference a secret.

Always show the exact curl or YAML you executed, plus the response status,
so the user can audit what changed.

Schema máy đọc được

Hai URL cố định mà LLM có thể fetch trực tiếp. URL đầu lọc tới các cấu trúc liên quan tới template; URL thứ hai là đặc tả OpenAPI công khai đầy đủ cho mọi endpoint mà API key của bạn có thể dùng.

Đặc tả OpenAPI 3.x đầy đủ
https://api.screenshots.live/schema/openapi.json
bash
curl https://api.screenshots.live/schema/templates.json | jq '.components.schemas | keys'

Endpoint LLM dùng nhiều nhất

Mọi endpoint chấp nhận API key sa_live_ của bạn dạng Bearer token. Template và item thuộc về chủ sở hữu key; rate limit theo tier.

Phương thứcĐường dẫnMục đích
POST/templatesCreate a template (defines canvas size and screen count).
GET/templatesList the API key owner's templates.
GET/templates/{id}Fetch a template with its items.
POST/templates/{id}/itemsAdd an item: Text, DeviceFrame, Image, Shape, CanvasBackground, or Html.
PUT/templates/{id}/items/{itemId}Update an item's position, z-index, or properties.
PUT/templates/{id}/items/bulkReplace all items in a template in one call.
POST/render/apiRender a template into screenshots from a YAML body.
GET/templates/{id}/yamlDownload a YAML scaffold with swappable fields ready to feed the render API.

Xác thực

Gửi Authorization: Bearer sa_live_<key-của-bạn>. Cùng một key xác thực CRUD template, CRUD item và dispatch render — không có scope riêng.

bash
curl -X POST https://api.screenshots.live/templates \
  -H "Authorization: Bearer $SCREENSHOTS_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fitness app — launch screens",
    "screenSizeCategory": "Mobile",
    "screenCount": 3
  }'
bash
curl -X POST https://api.screenshots.live/templates/$TEMPLATE_ID/items \
  -H "Authorization: Bearer $SCREENSHOTS_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Text",
    "x": 80,
    "y": 120,
    "zIndex": 10,
    "properties": {
      "text": "Track every workout",
      "fontSize": 64,
      "fontWeight": "bold",
      "color": "#0F172A",
      "textAlign": "left"
    }
  }'

Từ vựng LLM nên ghim

Các enum này lấy thẳng từ schema. Ghim chúng trong system prompt giúp mô hình không bịa giá trị làm hỏng (lỗi 422).

Loại item
TextDeviceFrameImageShapeCanvasBackgroundHtml
Nhóm kích thước màn hình
MobileTabletDesktopCustom

Workflow CI/CD ví dụ

Một LLM tuân theo prompt phía trên sẽ tạo ra thứ tương tự. Action lo phần gọi YAML render, retry khi lỗi và upload artifact.

yaml
name: Render screenshots
on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  screenshots:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Render via Screenshots.live
        uses: screenshots-live/render-screenshots-action@v1
        with:
          api-key: ${{ secrets.SCREENSHOTS_LIVE_API_KEY }}
          template-id: ${{ vars.SCREENSHOTS_TEMPLATE_ID }}
          yaml-path: ./screenshots/template.yaml

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: screenshots
          path: ./screenshots/output/

Thêm SCREENSHOTS_LIVE_API_KEY vào secrets của repo và SCREENSHOTS_TEMPLATE_ID vào variables của repo trước khi push.

Lỗi LLM cần lường trước

Chuyển các lỗi này tới LLM để nó hồi phục thay vì lặp vô hạn.

  • 401Bearer token thiếu hoặc không hợp lệ. Kiểm tra lại tham chiếu secret.
  • 403Đạt giới hạn tier (vd. số template) hoặc sai chủ sở hữu. LLM không nên thử lại nếu không có thay đổi.
  • 422Validate schema thất bại. LLM nên fetch lại schema và kiểm tra trước khi POST.
  • 429Vượt rate limit. Backoff và thử lại; giới hạn theo tier áp dụng cho từng key.

Bước tiếp theo