OI FOR BUSINESS · API V1
Your product.
Our creative studio.
Bring image and video generation to your system. The API uses the same credits and prices as your studio account.
The API follows availability reported by GET /tools. Requesting a quote does not create jobs or consume credits.
API base URL
https://oiai.me/api/v1Send Authorization: Bearer YOUR_OI_KEY with every request. Never put keys in browser apps, URLs or repositories. This API is for server-to-server use.
API partner pricing
Connect oiAI to your app and apply for a dedicated credit package.
- Separate credit top-up package
- See exclusive prices after approval
- Existing platform generation billing applies
Your API keys
Use keys only on your company's server. Each key can check the balance, upload files and spend your account credits. Valid for 90 days. Up to 10 active keys.
No keys created yet.
Your first creation
- Sign in and create a key above.
- Call
GET /toolsto check availability and pricing, andGET /balanceto check your credits. - Once services are active, submit a task and check its status until it completes.
First send the same parameters to POST /quotes. Confirm cost and send X-Quote-Id when creating the job. Quotes expire after 2 minutes.
cURL example:
export OI_BASE="https://oiai.me/api/v1"
# Set OI_API_KEY in your secure server environment.
curl "$OI_BASE/balance" -H "Authorization: Bearer $OI_API_KEY"
curl "$OI_BASE/quotes" -H "Authorization: Bearer $OI_API_KEY" -H "Content-Type: application/json" -d '{"tool":"image","prompt":"A tropical landscape at sunrise","ratio":"16:9"}'
# Confirm cost; replace QUOTE_UUID with the returned id.
curl "$OI_BASE/jobs" \
-H "Authorization: Bearer $OI_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Quote-Id: QUOTE_UUID" \
-H "Idempotency-Key: 5c547d79-e79e-4cc1-a9ea-861161897138" \
-d '{"tool":"image","prompt":"A tropical landscape at sunrise","ratio":"16:9"}'
# Response: {"id":"JOB_UUID","status":"processing"}
curl "$OI_BASE/jobs/JOB_UUID" \
-H "Authorization: Bearer $OI_API_KEY"To use a photo, upload the file first and use the id returned in assetIds:
curl "$OI_BASE/uploads" \
-H "Authorization: Bearer $OI_API_KEY" \
-F "file=@photo.jpg"
# POST /jobs body, with a new Idempotency-Key:
{"tool":"video","assetIds":["ASSET_UUID"],"consent":true,"duration":"5"}JavaScript example for Node.js:
const base = process.env.OI_BASE;
const headers = { Authorization: 'Bearer ' + process.env.OI_API_KEY };
const response = await fetch(base + '/balance', { headers });
const data = await response.json();
if (!response.ok) throw new Error(data.error.message);
console.log(data.credits);Endpoints
All paths below are relative to /api/v1. JSON responses, except media downloads and edge-protection responses.
| Method and path | Usage and response |
|---|---|
| GET /balance | {"credits":100} · account balance, shared with the website. |
| GET /tools | generation_ready, billing_rule, tools. Use POST /quotes to obtain the price for this creation. |
| POST /uploads | Multipart with the field file. 201: id, name, mime. JPG, PNG, WebP, MP4, WebM, MP3 or WAV; up to 30 MB per file and 200 MB per account. |
| GET /voices?locale=pt-BR | locale, voices[]: id, label, locale, gender |
| POST /quotes | Creation → id, cost, expiresAt, inputDuration |
| POST /jobs | JSON and Idempotency-Key + X-Quote-Id required. 202: id, status; accepted replay: 200. JSON up to 32 KB. |
| GET /jobs | limit from 1 to 100 (default 20), offset ≥ 0. Returns data and next_offset (null at the end). Lists website and API tasks; does not refresh provider statuses. New tasks can change pagination. |
| GET /jobs/{id} | Refreshes the task from the provider while processing. Returns id, tool, status, cost, outputs, created_at. Poll every 15 seconds; save the result links on completion. |
Dates are Unix timestamps in milliseconds. outputs contains authenticated relative result paths and may be empty until completion. Resolve against https://oiai.me and download with the same Bearer key; save a copy in your own storage.
Limit: 60 requests per minute per account across all keys. On 429, respect Retry-After. The limit uses fixed one-minute windows.
Ferramentas, um contrato
| tool | Files in assetIds, in this order | Pricing parameters |
|---|---|---|
imageCreate image | None; prompt is required | image |
videoImage to video | Reference image | video:5 / :10 / :15 · Wan 3.0 |
tryonVirtual try-on | Person photo → Clothing photo | tryon |
photobookPhoto shoot | Face photo | photobook:4 / :8 / :12 / :16 |
faceFace swap · photo | Source face → Target photo | face:face / :head |
facevideoFace swap · video | Source face → Target video | facevideo:face / :head |
motionMotion transfer | Person photo → Motion reference video | motion |
talkTalking photo | Face photo → Speech audio | talk:5 / :10 |
upscaleEnhance quality | Image or video | upscale |
subtitleRemove subtitles | MP4 video | subtitle |
ttsAI voiceover | None; prompt is required | tts |
productProduct with model | Product photo → Person photo | product |
textvideoText to video | None; prompt is required | textvideo:5 / :10 / :15 |
tool: required; one of the identifiers above.prompt: text, up to 2,000 characters. Required for image; the setting for photobook.negativePrompt: text, up to 2,000 characters; empty by default. Uses the model’s negative field for video, motion and talk; included as text constraints for image and photobook. Wan 3.0 requires an empty negativePrompt.ratio: "1:1" (default), "9:16" or "16:9"; for image.tts: prompt, voiceId, voiceLocale, speechRate: select a system voice via GET /voices. Up to 1,000 characters, speed 0.5–2, no negative prompt. The quote is a maximum reservation; actual duration is settled on completion and unused credits are refunded.product: productX, productY, productWidth, productHeight: assetIds order is product image, person image. Placement uses 0–1 coordinates relative to the person image; the rectangle must stay inside the image. The output is an image of the model presenting the product.textvideo: prompt, negativePrompt, ratio, duration: no source files. Duration is 5, 10 or 15 seconds, with native audio; describe the scene, motion and sound.imageModel, imageResolution, imageCount: Seedream 5.0 Pro supports 1K/2K, 1–8 outputs and up to 10 reference images.upscaleMedia, upscaleModel, upscaleQuality, upscaleResolution: upscale selects image/video and v1/v2. V2 is video-only with standard/professional quality and 1080p/2K output. V1 video allows 15 seconds; V2 allows 60 seconds.subtitle: one MP4 up to 60 seconds and 4K. Enhancement and subtitle removal process files automatically; both prompt fields must be empty.duration: "5" (default) or "10"; video also supports "15".videoMode: "extend", sourceJobId, sourceOutputIndex: to extend your completed video, use tool=video, assetIds=[] and consent=true. duration is additional seconds, up to 120 seconds total. Request a new quote for every extension. Wan 3.0 does not accept extend.count: "4" (default), "8", "12" or "16"; for photobook.clothing: text up to 400 characters; for photobook.swapMode: "face" (default) or "head"; for face and facevideo.assetIds: owned asset UUIDs; up to 10 references for Seedream and the table’s file count for other tools.consent: must be true when files are included, confirming authorization to use the images and voices.
Face and facevideo require empty prompt fields for generation; drafts may store text. Tryon accepts text instructions. Upscale and subtitle process files automatically without prompts.
Duration and count values are strings. Do not send external URLs in assetIds. Use only content you are authorized to use. For Wan 3.0, wanDuration is a number, wanAudio is boolean and wanSeed is an optional integer.
Wan 3.0: four video modes
Use tool="video" and videoModel="wan3.0-video" or "wan3.0-video-prime". Both models share the same contract. These settings apply only to Wan 3.0.
| Mode | Materials in wanMedia |
|---|---|
text-to-video | Text to video: no files or links; prompt required. |
first-frame | First frame: exactly one first_frame image; prompt required. |
first-last-frames | First and last frames: one first_frame image followed by one last_frame image; prompt required. |
reference | References: images, videos, audio and an optional link. The prompt may be empty if materials or a link are included. |
Settings and defaults
wanMode: text-to-video / first-frame / first-last-frames / reference;text-to-videowanResolution: 480P / 720P / 1080P;480PwanRatio: adaptive / 16:9 / 4:3 / 1:1 / 3:4 / 9:16;16:9wanDuration: Integer from 2 to 30 seconds; default 3. -1 requests automatic duration and requires an exact quote. This differs from duration for earlier models.wanAudio: Defaults to true; false disables generated audio.wanSeed: Optional integer from 0 to 2147483647.
Up to 5,000 characters for Wan 3.0. negativePrompt must be empty and videoMode="extend" is not accepted. Earlier models retain their existing video extension contract.
Supply owned file UUIDs in assetIds and repeat exactly the same IDs, in the same order, in wanMedia. type selects each file’s role. URLs are not accepted in assetIds or wanMedia. Each reference must use a different file. With materials or links, consent must be true.
Material limits
- JPG, PNG or WebP images: up to 20 MiB each, width and height from 240 to 7680 pixels, aspect ratio from 1:8 to 8:1.
- MP4 videos: up to 30 MiB each, 1–15 seconds each; reference videos total at most 15 seconds. Output duration plus total reference video duration must not exceed 30 seconds.
- MP3 or WAV audio: up to 15 MiB each, 1–15 seconds each; reference audio totals at most 15 seconds.
- In reference mode: at most 10 materials combined, including at most 10 images, 5 videos and 5 audio files. A wanLinks entry also counts towards that total.
wanLinks accepts at most one {type:"file"|"link",url:"https://…"} object, only in reference mode. URLs must be public: no credentials, localhost or private IP addresses. OI does not fetch the URL. Owned PDF uploads are not accepted.
Send the complete body to POST /quotes. Confirm cost in credits, then send the identical body to POST /jobs with X-Quote-Id and a new Idempotency-Key. There is no fixed price; changes to settings or materials require a new quote. Creation is rejected without an exact quote, including automatic duration (-1). Poll GET /jobs/{id} every 15 seconds: status and outputs use the existing job contract; wanMode, wanResolution, wanDuration, wanRatio and wanAudio report the selected settings.
Example: text to video
WAN_BODY='{"tool":"video","videoModel":"wan3.0-video","wanMode":"text-to-video","prompt":"A red kite flying over a green field, with birdsong","wanResolution":"480P","wanDuration":3,"wanRatio":"16:9","wanAudio":true}'
curl "$OI_BASE/quotes" \
-H "Authorization: Bearer $OI_API_KEY" \
-H "Content-Type: application/json" --data "$WAN_BODY"
# Confirm cost and replace QUOTE_UUID with the returned quote id.
curl "$OI_BASE/jobs" \
-H "Authorization: Bearer $OI_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Quote-Id: QUOTE_UUID" \
-H "Idempotency-Key: 73426a7e-bc84-42df-891f-e4cb65968af8" \
--data "$WAN_BODY"Example materials for first and last frames
{
"tool": "video",
"videoModel": "wan3.0-video",
"wanMode": "first-last-frames",
"prompt": "Smooth transition between these two scenes",
"assetIds": [
"FIRST_FRAME_UUID",
"LAST_FRAME_UUID"
],
"wanMedia": [
{
"type": "first_frame",
"assetId": "FIRST_FRAME_UUID"
},
{
"type": "last_frame",
"assetId": "LAST_FRAME_UUID"
}
],
"consent": true,
"wanDuration": 3
}Production integration
Choose the model explicitly
These are public model identifiers. Omitting videoModel preserves the earlier standard model; it does not select HD automatically.
videoModel=standard: Standard videovideoModel=hd: HD image to video; videoAudio=true enables native audio.videoModel=seedance-2.5: Cinematic short: explicitly send integer wanDuration from 4 to 30; uses wanMode/wanResolution/wanRatio/wanAudio.- Precise editing: imageModel=seedream-5.0-pro-edit, at least one owned reference; imageRegion is optional.
Example bodies (use identical JSON for quotes and jobs)
{
"tool": "video",
"videoModel": "hd",
"videoAudio": true,
"assetIds": [
"YOUR_ASSET_UUID"
],
"consent": true,
"prompt": "A slow camera move along the coast",
"duration": "5"
}{
"tool": "video",
"videoModel": "seedance-2.5",
"wanMode": "text-to-video",
"prompt": "A cinematic journey through a futuristic city",
"wanDuration": 4,
"wanResolution": "480P",
"wanRatio": "16:9",
"wanAudio": true
}{
"tool": "image",
"imageModel": "seedream-5.0-pro-edit",
"prompt": "Change the jacket to blue",
"assetIds": [
"YOUR_ASSET_UUID"
],
"consent": true,
"imageResolution": "1K",
"imageCount": 1
}Download results from your server
outputs contains relative paths, such as /api/v1/jobs/JOB_UUID/file?index=0. Resolve against https://oiai.me and send the same Bearer key. Never put a key in a URL or an end-user browser. index starts at zero; download=1 suggests a filename. GET supports one Range interval and may return 206.
curl "https://oiai.me/api/v1/jobs/JOB_UUID/file?index=0&download=1" \
-H "Authorization: Bearer $OI_API_KEY" \
--output result.binFiles are automatically deleted 72 hours after completion. Administrator and published platform creations are exempt: retentionExempt=true, expiresAt and retentionHours are null. expiresAt is the Unix millisecond deadline; contentExpired marks expiry and outputStorage may also be expired. After the deadline file access returns 410/content_expired. Save a copy in your own storage. outputStorage can be saving, saved, retry or unavailable; this describes file storage, not generation completion. An unavailable result returns 410/result_unavailable; an invalid byte range returns 416/invalid_range.
Operating rules
- Use a separate account per business customer. Keys belonging to one account share credits, files, jobs and 60 requests/minute; keys do not isolate your own downstream customers.
- Persist the body, Idempotency-Key and job id on your server. After a timeout or 502/503, repeat the same body and key. A different creation needs a new quote and new key.
- Poll every 15 seconds, with queues/backoff to respect the aggregate limit. Stop resubmission in review and contact support. This version has no completion webhook or cancellation endpoint.
- Uploads: 30 MiB per file, 200 MiB per account and normally 2,000 files. Reuse assetIds where possible. V1 has no material listing/deletion endpoint; clean up in the studio or contact support before a large batch.
- For 400 responses, error.details identifies fields and validation codes without echoing submitted content. generation_rejected with error.submission means failure and refund are committed; use jobId for reconciliation.
- Keys expire after 90 days. Create a replacement before expiry, switch your server, then revoke the old key. Agree on credit replenishment and volume support before production.
Response handling
Check HTTP status and Content-Type before parsing JSON. HTML/text without X-Request-Id may originate from edge protection; record the time and CF-Ray and contact support, preserving the same idempotency key.
No dedicated concurrency or SLA is promised. Before sending volume, verify one explicitly authorized paid creation end to end and confirm support arrangements.
Credits and safe retries
The credits required are shown for each creation and vary with your selected options. Confirm the cost before submission; changes require a new quote.
For each new creation, generate an Idempotency-Key of 16–80 letters, digits, underscores or hyphens. Store the key and original body on your server. After a timeout, retry with exactly the same key and parameters. The existing task is returned without another charge. Reusing the key with different parameters returns 409.
Idempotency keys are unique per account, shared across all API keys and the website, and remain bound to the task. Do not create another key to work around a timeout. Confirmed failures return credits once. In review, credits stay reserved until checked; do not resubmit as a new task.
Statuses and errors
submitting: submitting · processing: generating · stitching: unindo as cenas · completed: completed · failed: confirmed failure, credits returned · review: manual confirmation needed · refunded: closed with a manual credit refund.
API messages remain in Portuguese; use error.code to handle errors in your system.
{
"error": {
"code": "insufficient_credits",
"message": "Créditos insuficientes.",
"request_id": "REQUEST_UUID"
}
}400: invalid parameters · 401: missing, invalid, expired or revoked key · 402: insufficient credits · 403: suspended account · 404: resource missing or owned by another account · 409: idempotency conflict · 413: size/storage limit · 415: wrong body type · 429: rate limit · 502/503: service unavailable.
API responses include X-Request-Id for support. On 502/503 or a network error, wait before retrying and keep the same Idempotency-Key. This version has no completion webhooks: use GET /jobs/{id}.
Open OpenAPI 3.0 specification