RukPrompt
Docs

เอกสาร API สำหรับนักพัฒนา

RukPrompt API ให้คุณสร้างภาพด้วย AI จากแอปของคุณ ผ่าน HTTP request แบบ sync blocking (POST แล้วรอจน generate เสร็จ) โดยไม่ต้อง polling — เหมาะสำหรับ server-side integration, SDK, หรือ automation workflow

เริ่มใช้งาน API ฟรี

สมัคร workspace เพื่อสร้าง API key และเริ่ม generate ภาพ — ใช้เครดิตฟรีตั้งแต่สมัคร

เข้าสู่ระบบสมัครฟรี
Base URL
https://developer.rukprompt.com
Auth
Bearer sk-img-...
Max blocking time
180 วินาที (ถ้าเกินจะคืน 504 + jobId)

การยืนยันตัวตน (Authentication)

ทุก request ต้องมี header:

bash
Authorization: Bearer sk-img-<your-key>

• สมัครสมาชิก เพื่อสร้าง workspace — ได้เครดิตฟรีตั้งแต่เริ่ม

• เข้าไปที่ Settings → สำหรับนักพัฒนา ในหน้า workspace เพื่อสร้าง API key

• key จะแสดงครั้งเดียวตอนสร้าง — บันทึกไว้ใน password manager หรือ environment variable

• เครดิตตัดจาก workspace ของ key — ดูยอดได้จาก GET /v0/usage

API Playground
ปรับค่าเพื่อดูตัวอย่าง code ที่ตรงกับของจริง
สมัครเพื่อรับ API Key

สร้างภาพด้วย AI

POST
/v0/images/generations

สร้างภาพด้วย AI — รอสูงสุด 180 วินาที แล้วคืน URL ของภาพที่สร้างเสร็จทันที (sync blocking)

Example Request

cURL
curl -X POST https://developer.rukprompt.com/v0/images/generations \
  -H "Authorization: Bearer sk-img-..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cute cat wearing sunglasses",
    "modelVersion": "gemini-2.5-flash-image",
    "resolution": "standard",
    "aspectRatio": "1:1",
    "sampleCount": 1
  }'

Request Body Parameters
คลิกช่องเพื่อแก้ค่า

Parameter
Description
Value
Required
prompt
string
ข้อความอธิบายภาพที่ต้องการสร้าง — ใช้ภาษาอังกฤษหรือไทยก็ได้ แนะนำ 20-500 คำ
required
modelVersion
string
Model ID — ดูรายการจาก GET /v0/models
optional
resolution
"low" | "standard" | "high" | "4k"
default: "standard"
Resolution tier — เครดิตต่อภาพขึ้นกับ tier
optional
aspectRatio
string
default: "1:1"
สัดส่วนของภาพ — แต่ละ model อาจรองรับไม่ครบ
optional
sampleCount
integer (1-4)
default: 1
จำนวนภาพที่ต้องการ — เครดิตจะคูณตาม count
optional
isPublic
boolean
default: false
การมองเห็นของภาพ —
• private (default): เห็นเฉพาะในทีมของคุณ
• public: โชว์ใน Community gallery — คนอื่นเห็นได้
optional
response_format
"url" | "b64_json" | "both"
default: "url"
รูปแบบ response —
• url (default) คืนลิงก์ภาพ
• b64_json คืน base64 อย่างเดียว (เข้ากับ OpenAI)
• both คืนทั้ง url + base64
ส่งเป็น query (?response_format=b64_json) หรือใน body ก็ได้
optional
async
boolean
default: false
ถ้า true — enqueue แล้ว return jobId ทันที (ไม่รอ) แล้วให้ poll ผ่าน GET /v0/images/generations/{jobId}
แนะนำสำหรับโมเดลที่ช้า (gpt-image-2 อาจเกิน 180s) หรืออยู่หลัง proxy ที่มี timeout สั้น
ใช้ตามต้องการ
optional
negativePrompt
string
สิ่งที่ไม่อยากให้มีในภาพ (เฉพาะ Stable Diffusion models)
ใช้ตามต้องการ
optional
presetId
string
ID ของ preset ที่จะใช้เป็น base prompt template
ใช้ตามต้องการ
optional
variables
object
ค่าตัวแปรของ preset (ใช้ร่วมกับ presetId) — เช่น `{"product": "sneakers"}`
ใช้ตามต้องการ
optional
refImageUrls
string[]
URL ของภาพอ้างอิง (public HTTP/HTTPS, max 5 ภาพ, 10MB/ภาพ) — ใช้ใน image-to-image
ใช้ตามต้องการ
optional
refImageBase64
{ mimeType, data }[]
ภาพอ้างอิงแบบ base64 — ทางเลือกแทน refImageUrls (max 5 ภาพ, 10MB/ภาพ)
ใช้ตามต้องการ
optional

Response (200 OK)

json
{
  "code": 200,
  "data": {
    "id": "job_abc123",           // jobId สำหรับ tracking
    "created": 1745000000,        // unix timestamp
    "model": "gemini-2.5-flash-image",
    "data": [
      {
        "id": "img_xyz",          // generated image id
        "url": "https://cdn.rukprompt.com/teams/.../abc.png",
        "storageKey": "teams/.../abc.png",
        // ถ้าส่ง ?response_format=b64_json หรือ both จะมี field เพิ่ม:
        "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
        "mimeType": "image/png"
      }
    ],
    "usage": {
      "credits": 1                // เครดิตที่ถูกตัดจาก team
    }
  }
}

ตรวจสอบสถานะ Job

GET
/v0/images/generations/:jobId

ใช้เมื่อ POST ได้ 504 timeout เพื่อเช็คว่า job เสร็จหรือยัง — คืนข้อมูลภาพเมื่อ status = completed

cURL
curl "https://developer.rukprompt.com/v0/images/generations/job_abc123" \
  -H "Authorization: Bearer sk-img-..."
Response shape เหมือน POST /v0/images/generationsแต่จะมี status field เพิ่ม:"waiting" | "processing" | "completed" | "failed"

รายการ AI Models ที่ใช้ได้

GET
/v0/models

ดูโมเดลทั้งหมด + ค่าเครดิตต่อภาพ + aspect ratios ที่แต่ละโมเดลรองรับ

cURL
curl "https://developer.rukprompt.com/v0/models" \
  -H "Authorization: Bearer sk-img-..."

Models ที่ใช้งานได้ในทีมของคุณ

กำลังโหลด models...

ตัวเลขคือเครดิตต่อ 1 ภาพ — ถ้า sampleCount = 4 จะคูณ 4

Presets (Read-only)

GET
/v0/images/presets

ดึงรายการ preset ที่ทีมเข้าถึงได้ — แล้วส่ง presetId เข้า /v0/images/generations เพื่อใช้ prompt template ของ preset นั้น

Read-only
Preset ไม่สามารถ สร้าง/แก้ไข/ลบ ผ่าน API key ได้ — ใช้งานผ่าน dashboard เท่านั้น

ดึงรายการ preset

cURL
curl "https://developer.rukprompt.com/v0/images/presets" \
  -H "Authorization: Bearer sk-img-..."

เพิ่ม ?teamOnly=true ใน URL ถ้าอยากได้เฉพาะ preset ของทีม (ไม่รวม public)

ดูรายละเอียด preset ตัวเดียว

cURL
curl "https://developer.rukprompt.com/v0/images/presets/<presetId>" \
  -H "Authorization: Bearer sk-img-..."

ใช้งาน preset ใน generate

ส่ง presetId เข้าไปใน body — prompt ของ preset จะถูกนำมาใช้เป็น base ถ้า preset มี requirements (ตัวแปร) ต้องส่งใน variables ด้วย

json
{
  "presetId": "preset_abc123",
  "prompt": "extra details to append (optional)",
  "modelVersion": "gemini-2.5-flash-image",
  "variables": {
    "product": "sneakers",
    "color": "white"
  }
}

Response

json
{
  "code": 200,
  "data": [
    {
      "id": "preset_abc123",
      "name": "Studio Product Shot",
      "note": "สำหรับถ่ายสินค้าแบบ studio",
      "modelVersion": "gemini-2.5-flash-image",
      "defaultAspectRatio": "1:1",
      "lockModel": true,
      "lockAspectRatio": false,
      "thumbnailUrl": "https://cdn.../thumb.png",
      "requirements": [
        { "key": "product", "label": "สินค้า", "type": "text" },
        { "key": "color", "label": "สี", "type": "text" }
      ],
      "accessLevel": "READ",   // หรือ "FULL" สำหรับ preset ของทีม
      "isCommunity": false,
      "categories": ["product"],
      "originTeam": null,
      "createdAt": "2026-04-24T...Z"
    }
  ]
}

เครดิตคงเหลือและประวัติการใช้

GET
/v0/usage

เครดิตคงเหลือของทีม + สถิติการใช้งาน + 50 jobs ล่าสุด

cURL
curl "https://developer.rukprompt.com/v0/usage?from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer sk-img-..."

Query params (optional):

  • from — ISO date (start of range)
  • to — ISO date (end of range)

ประวัติการเรียก API

GET
/v0/history

ประวัติการเรียก API ทั้งหมดของทีม — กรองและแบ่งหน้าได้

cURL
curl "https://developer.rukprompt.com/v0/history?page=1&limit=20&status=success" \
  -H "Authorization: Bearer sk-img-..."

Query params:

  • page — default 1
  • limit — 1-100, default 20
  • status — "success" | "failed"
  • apiKeyId — filter เฉพาะ key
  • from / to — ISO date range

รหัส Error (Error Codes)

Code
Name
Common Cause
400
Bad Request
Parameter ไม่ถูกต้อง (prompt ว่าง, aspectRatio ไม่รองรับ, model invalid)
401
Unauthorized
ไม่มี Authorization header / key ไม่ถูกต้อง / key ถูก revoke
403
Forbidden
Team ไม่มีสิทธิ์ใช้ model นี้ (R18, premium) หรือ suspended
404
Not Found
jobId ไม่ใช่ของ team นี้ หรือ request host ไม่ใช่ developer.rukprompt.com
429
Too Many Requests
Rate limit 60 req/min per key หรือ planConcurrent reached
500
Internal Server Error
AI provider fail, storage error, unexpected exception
504 timeout
Gateway Timeout
Generation เกิน 180s — ใช้ jobId ที่ return มา poll ผ่าน GET endpoint หรือส่ง async:true เพื่อ return jobId ตั้งแต่แรก
Error response format:
json
{
  "code": 401,
  "message": "Invalid or revoked API key",
  "data": null
}