아래 스킬을 복사하여 OpenCode 채팅에 붙여넣으세요. 그러면 에이전트는 대화가 이어지는 동안 API 표면, 오류 규칙, 그리고 재시도하지 말아야 할 시점을 알게 됩니다.
> Paste this into the OpenCode chat. It teaches the agent the DreamUtopia API for the
> rest of the conversation. Keep the `DREAMUTOPIA_API_KEY` in your shell environment,
> not in the pasted text.
# DreamUtopia media generation
Use this skill when the user asks you to generate an image or a video with DreamUtopia.
## Prerequisites
- **API access requires a paid account.** Keys cannot be minted by a free account.
- The user sets their key in the environment:
```sh
export DREAMUTOPIA_API_KEY="du_live_..."
```
If `DREAMUTOPIA_API_KEY` is unset, **stop and ask the user to set it**. Never write the key
into a project file, a commit, or a message.
- Base URL: `https://api.dreamutopia.net/v1`
- Every request sends `Authorization: Bearer $DREAMUTOPIA_API_KEY`.
## Keeping this skill current
This skill is served by the product and can change without notice. If a request fails in a way
this document does not describe — an unknown field, an unexpected status or error code, or a
route that returns `404` — the skill may be stale. Re-fetch it, paste the new version into the
conversation, and re-read it before retrying:
```sh
curl -fsSL https://dreamutopia.net/skills/dreamutopia/opencode.md
```
Do not invent request fields from memory. The re-fetched file is the current contract; the copy
in the conversation is only a snapshot.
## 1. Upload a local reference image (optional)
Only needed when the user has a local file. A previous generation's `result.url` can be used
directly instead.
```sh
curl -sS -X POST https://api.dreamutopia.net/v1/uploads \
-H "Authorization: Bearer $DREAMUTOPIA_API_KEY" \
-F "file=@/path/to/photo.png"
```
Response `201`:
```json
{ "id": "<upload_id>",
"url": "<upload_url>",
"expires_at": "2026-10-31T12:00:00Z" }
```
Use `id` (not `url`) in the next request. Accepted: JPEG, PNG, WebP, up to 30 MB.
`id` only works for the account that uploaded it.
## 2. Create an image
```sh
curl -sS -X POST https://api.dreamutopia.net/v1/images/generations \
-H "Authorization: Bearer $DREAMUTOPIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "lite",
"prompt": "a red fox in fresh snow, cinematic",
"resolution": "2k",
"aspect_ratio": "1:1"
}'
```
| Field | Values |
|---|---|
| `model` | `lite`, `pro` |
| `resolution` | `2k`, `4k` (`lite` accepts `2k` only) |
| `aspect_ratio` | `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `adaptive` |
| `reference_images` | array of upload ids or DreamUtopia URLs; 0–3 for `lite`, 0–14 for `pro` |
| `prompt` | non-empty, up to 8000 characters |
`adaptive` requires at least one reference image. `resolution` defaults to `2k` and
`aspect_ratio` to `1:1`.
Response `202`:
```json
{ "id": "3f2b…", "type": "image", "status": "queued", "created_at": "2026-10-24T12:00:00Z" }
```
## 3. Create a video
```sh
curl -sS -X POST https://api.dreamutopia.net/v1/videos/generations \
-H "Authorization: Bearer $DREAMUTOPIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "medium",
"prompt": "the fox turns and looks at the camera",
"image": "<upload_id>",
"resolution": "720p",
"duration": 8
}'
```
| Field | Values |
|---|---|
| `model` | `lite`, `medium`, `pro` |
| `resolution` | `480p`, `720p`, `1080p` (`lite` cannot use `1080p`) |
| `duration` | 5–10 seconds (`lite`), 5–15 (`medium`), 5–30 (`pro`) |
| `image` | first-frame upload id or DreamUtopia URL (omit for text-to-video) |
| `last_frame_image` | requires `image`; not supported by `lite` |
| `generate_audio` | `pro` only, and the account must hold premium; `lite` and `medium` are rejected |
Response `202` with `type: "video"`.
## 4. Poll until it finishes
```sh
curl -sS https://api.dreamutopia.net/v1/generations/$MID \
-H "Authorization: Bearer $DREAMUTOPIA_API_KEY"
```
`status` is one of `queued`, `processing`, `succeeded`, `failed`.
- Poll every 3–5 seconds, backing off to 10 seconds. Give up after about 10 minutes.
- On `succeeded`, download `result.url`. The link is valid for 7 days.
- On `failed`, report `error.message` to the user and stop. A failed job is terminal; do
**not** submit it again automatically.
- If an id is lost, `GET /generations?limit=20` lists recent jobs, newest first.
Terminal response:
```json
{
"id": "3f2b…",
"type": "video",
"status": "succeeded",
"model": "medium",
"credits_used": 12,
"created_at": "2026-10-24T12:00:00Z",
"updated_at": "2026-10-24T12:02:10Z",
"result": { "url": "<result_url>" },
"error": null
}
```
## 5. Check credits and prices
```sh
curl -sS https://api.dreamutopia.net/v1/account -H "Authorization: Bearer $DREAMUTOPIA_API_KEY"
curl -sS https://api.dreamutopia.net/v1/models
```
`/models` is public and returns every tier's allowed resolutions and durations plus the
`resolution → duration → credits` matrix. Check it before choosing settings when the user
cares about cost.
## Errors
Every error body is exactly:
```json
{ "error": { "code": "insufficient_credits", "message": "You need more credits to generate." } }
```
| HTTP | Meaning |
|---|---|
| 400 | invalid input (`invalid_request`, `prompt_too_long`, `invalid_reference_image`, …) |
| 401 | missing, malformed, revoked or removed-account key |
| 402 | not enough credits |
| 403 | unpaid key creation, or audio requested without premium |
| 404 | unknown job, or a job belonging to another account |
| 409 | `Idempotency-Key` reused with a different body, or still in flight |
| 413 / 415 | upload too large / not a supported image |
| 429 | rate limited; read `Retry-After` |
| 500 / 503 | internal; retry later |
Retry only HTTP `429`, `timeout` and `internal` responses. Never retry
`insufficient_credits`, and never resubmit a job that already finished as `failed`.
## Idempotency
Send `Idempotency-Key: <unique value>` on a create request. A retry with the same key and
body returns the existing job (`200`) instead of creating and charging a second one. Use a
fresh value for every genuinely different request.
## Complete example
```sh
#!/usr/bin/env bash
set -euo pipefail
: "${DREAMUTOPIA_API_KEY:?set DREAMUTOPIA_API_KEY first}"
API="https://api.dreamutopia.net/v1"
ID=$(curl -sS -X POST "$API/images/generations" \
-H "Authorization: Bearer $DREAMUTOPIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"lite","prompt":"a red fox in fresh snow","resolution":"2k","aspect_ratio":"1:1"}' \
| jq -r .id)
while :; do
BODY=$(curl -sS "$API/generations/$ID" -H "Authorization: Bearer $DREAMUTOPIA_API_KEY")
STATUS=$(jq -r .status <<<"$BODY")
case "$STATUS" in
succeeded) jq -r .result.url <<<"$BODY"; break ;;
failed) jq -r .error.message <<<"$BODY" >&2; exit 1 ;;
*) sleep 4 ;;
esac
done
```