# CI에서 이미지 미리 그리기

Mocco는 이미지를 처음 불러올 때 그립니다. 그리는 데 잠깐 시간이 걸리고, 어떤 앱은 이미지가 느리면 기다리지 않고 이미지 없이 링크를 보여 줍니다. 페이지를 공개할 때 CI가 바로 이미지를 그리게 하면, 첫 크롤러가 올 때 이미 저장되어 있습니다.

이때 CI에는 서명 시크릿이 필요 없습니다. Mocco가 프로젝트에 저장된 시크릿으로 서명하고 서명된 URL을 돌려줍니다. 다만 프로젝트에는 시크릿이 있어야 합니다([서명 시크릿](https://www.mocco.club/docs/ko/articles/27m78b-overview#서명-시크릿) 참고).

## 1. 키 만들기

소유자나 관리자가 프로젝트의 **API 키**에서 `og:write` 권한이 있는 **시크릿** 키를 만듭니다. CI 시크릿으로 저장하세요(예: `MOCCO_API_KEY`).

## 2. 그리기

```sh
curl -X POST https://api.mocco.club/v1/og/images \
  -H "Authorization: Bearer $MOCCO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"template":"article","params":{"brand":"Acme Docs","eyebrow":"Guides","title":"Install in five minutes"}}'
```

`params`는 템플릿의 항목을 문자열로 넣은 것으로, 서명된 URL에 쓰는 항목과 같고 `s`만 뺍니다([템플릿](https://www.mocco.club/docs/ko/articles/27m78b-overview#템플릿) 참고). Mocco는 이렇게 응답합니다.

```json
{ "url": "https://api.mocco.club/v1/og/<project id>/article.png?brand=…&s=…", "hash": "<64자리 16진수>" }
```

`url`을 페이지의 `og:image`에 넣으세요. 같은 항목이면 `@mocco/node`와 콘솔이 서명하는 URL과 같고, 이제 저장된 이미지로 제공됩니다. 같은 요청을 다시 보내면 아무것도 새로 그리지 않고 같은 응답을 돌려주므로, 배포할 때마다 실행해도 됩니다.

## Mocco의 응답

| 상황 | 응답 |
| --- | --- |
| 키가 없거나, 퍼블리셔블 키이거나, `og:write`가 없는 시크릿 키 | `401` 또는 `403` |
| 없는 템플릿, 또는 프로젝트에 서명 시크릿이 없음 | `404` |
| 필수 항목이 없거나, 템플릿에 없는 항목(`s` 포함), 한도를 넘는 값, 잘못된 `accent`, 또는 문자열 값으로 된 `{ template, params }`가 아닌 본문 | `400`, 문제가 된 항목을 알려 줌 |
| 16KiB를 넘는 본문 | `413` |
| 프로젝트에서 1분에 새로 그리는 이미지가 60개를 넘음(이미 저장된 이미지는 포함하지 않음) | `429`, `Retry-After` 포함 |
| 그 밖의 경우 | `url`과 `hash`가 담긴 `200` |

1분에 60개 한도는 서명된 URL로 불러오는 이미지와 함께 셉니다. 여러 페이지를 한꺼번에 미리 그린다면 `Retry-After`만큼 기다렸다가 이어서 하세요.