API Documentation

MovieLook open API · text-to-image + image-to-image · billed in credits

⚡ Quick Start for AI Agents

Paste the paragraph below into an AI agent (Claude, ChatGPT, Copilot, custom agents, ...) so it can generate images with the user's API key. Then call the endpoints with curl or the Python example.

Agent instructions (copy & paste)

You are an image generation assistant backed by MovieLook. The user has an API key that starts with "mlk_". To generate an image: 1) POST /api/v1/generate with header "Authorization: Bearer <api_key>" and a JSON body containing type ("text-to-image" or "image-to-image"), prompt, aspect_ratio, resolution, quality and number_of_images. 2) The API returns HTTP 202 with an "id" immediately. 3) Poll GET /api/v1/generations/{id} every 3 seconds until status is "success" or "failed". 4) On success, present the image URLs from the "images" array to the user; on failure, report the "error" message.

curl

# 1. Submit a text-to-image generation
curl -X POST https://www.aimoviephoto.com/api/v1/generate \
  -H "Authorization: Bearer mlk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"text-to-image","prompt":"A warrior standing on a mountain at sunset","aspect_ratio":"16:9","resolution":"1k","quality":"high","number_of_images":1}'
# -> 202 {"id":"12345","status":"pending",...}

# 2. Poll until done (replace {id} with the returned id)
curl https://www.aimoviephoto.com/api/v1/generations/12345 \
  -H "Authorization: Bearer mlk_YOUR_KEY"
# -> 200 {"id":"12345","status":"success","images":["https://images.aimoviephoto.com/..."],"credits_used":26,...}

Python (requests)

import time
import requests

API_URL = "https://www.aimoviephoto.com"
HEADERS = {"Authorization": "Bearer mlk_YOUR_KEY"}

# 1. Submit a text-to-image generation
resp = requests.post(f"{API_URL}/api/v1/generate", headers=HEADERS, json={
    "type": "text-to-image",
    "prompt": "A warrior standing on a mountain at sunset",
    "aspect_ratio": "16:9",
    "resolution": "1k",
    "quality": "high",
    "number_of_images": 1,
})
task = resp.json()  # {"id": "...", "status": "pending"}

# 2. Poll until the generation finishes
while True:
    data = requests.get(
        f"{API_URL}/api/v1/generations/{task['id']}", headers=HEADERS
    ).json()
    if data["status"] in ("success", "failed"):
        break
    time.sleep(3)

# 3. On success, images are in data["images"]
print(data)

Replace mlk_YOUR_KEY with a real key from your account. The full request/response reference is below.

1. Create an API Key

API keys are available on paid plans. Sign in and open the Account page, go to the API Keys tab and click Create Key after entering a name. The key is shown only once, so copy and save it immediately. Only the hash of the key is stored on the server; if you lose it, use Reset to generate a new one.

2. Authentication

Every request must carry this header:

Authorization: Bearer mlk_xxxxxxxxxxxxxxxxxxxxxxxx

A missing or invalid key returns 401 Unauthorized.

3. Quick Start (submit → poll → download)

The generate endpoint is asynchronous: it returns 202 with a task id immediately; poll that id until the status becomes success.

① Submit a text-to-image generation:

curl -X POST https://www.aimoviephoto.com/api/v1/generate \
  -H "Authorization: Bearer mlk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text-to-image",
    "prompt": "A warrior standing on a mountain at sunset",
    "aspect_ratio": "16:9",
    "resolution": "1k",
    "quality": "high",
    "number_of_images": 1
  }'
# → 202 {"id":"12345","status":"pending",...}

② Poll for the status (use the id from step ①):

curl https://www.aimoviephoto.com/api/v1/generations/12345 \
  -H "Authorization: Bearer mlk_YOUR_KEY"
# → 200 {"id":"12345","status":"success","images":["https://images.aimoviephoto.com/..."],"credits_used":26,...}

③ Image-to-image (4 preset styles + custom):

curl -X POST https://www.aimoviephoto.com/api/v1/generate \
  -H "Authorization: Bearer mlk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image-to-image",
    "style": "cinematic",
    "images": ["<image_url>"],
    "prompt": "add a sunset background",
    "resolution": "1k",
    "quality": "high",
    "number_of_images": 1
  }'

Check your remaining credits:

curl https://www.aimoviephoto.com/api/v1/credits \
  -H "Authorization: Bearer mlk_YOUR_KEY"

4. Generate Endpoint `POST /api/v1/generate`

Field	Required	Description
`type`	✅	`text-to-image` or `image-to-image`
`prompt`	text-to-image ✅ / image-to-image optional	For text-to-image: the image description. For image-to-image: additional instructions.
`style`	image-to-image ✅	`cinematic / action-figure / cyberpunk / anime / custom`
`images`	image-to-image ✅ (1-4 URLs)	Array of image URLs; send `[]` for text-to-image
`aspect_ratio`	optional	`auto / 1:1 / 3:2 / 2:3 / 16:9 / 9:16`, default `auto`
`resolution`	optional	`1k / 2k / 4k`, default `1k`
`quality`	optional	`auto / low / medium / high`, default `high`
`number_of_images`	optional	Default `1`, max `10`

A successful submission returns 202 Accepted (async - it returns immediately without waiting for the generation to finish):

{
  "id": "12345",
  "status": "pending",
  "message": "Generation started. Poll GET /api/v1/generations/{id} for status."
}

Use the id to poll GET /api/v1/generations/{id} for the result. Statuses:

pending — accepted; queued or generating (credits already deducted)
success — done; returns images (image URLs) and credits_used
failed — failed; returns an error reason and credits are automatically refunded

Note: the text-to-image model is OpenAI GPT Image 2. Output size is controlled by aspect_ratio (supports specific pixel sizes from 1024×1024 up to 3840×2160), and text-to-image mode requires images to be an empty array.

5. Query Endpoints

GET /api/v1/credits

Check remaining credits: { "credits_remaining": 340, "credits_used": 60, "plan": "basic" }

GET /api/v1/generations?page=1&limit=20

Paginated generation history (time, parameters, credits used, result images): { "page":1, "limit":20, "total":3, "generations":[...] }

GET /api/v1/generations/{id}

Get the status of one generation (used for async polling): { "id":"12345", "status":"success", "images":[...], "credits_used":26, "created_at":"...", "updated_at":"..." }; returns 404 if the id does not exist or belongs to another user.

GET /api/v1/usage

Credit usage statistics (total, per day, per key): { "total_credits_used": 58, "by_day":[...], "by_key":[...] }

6. Downloading Images Programmatically

The image URLs returned by the API (https://images.aimoviephoto.com/...) can be opened in a browser directly. If your program downloads them with a non-browser User-Agent, the CDN bot protection may return 403. Use the download proxy instead (server-side request with a browser UA, unaffected by bot protection):

curl -o result.png "https://www.aimoviephoto.com/api/download?url=<IMAGE_URL>"

The proxy only allows images hosted on the MovieLook image CDN (the images.aimoviephoto.com custom domain) and returns the raw image content (Content-Disposition: attachment).

7. Error Codes

Status Code	Meaning
400	Invalid request (missing required fields, invalid style, wrong images count, etc.)
401	API key missing or invalid
402	Not enough credits
403	Forbidden (e.g., creating an API key requires an active paid plan)
429	Rate limit exceeded (free: 20/hour, paid: 500/hour)
502	Upstream generation failed (retry later)
500	Internal server error

8. Rate Limits

Free users: 20 requests/hour; paid users: 500 requests/hour (based on the requests in the last hour, failed requests count too). Exceeding the limit returns 429.

Have questions? Contact us (support@aimoviephoto.com).