Client Uploading

General Uploading

The steps description: 1. create: connect to upload API server, to get upload_token and upload_server_uri. 2. create_file: connect to uploading server (with the IP address which is resolved from the upload_server_uri returned by create call before. the following so called uploading server is corresponding to the server with this IP address), to create file uploading process with upload_token and file_md5 as parameters (also with some other parameters together). 3. new_slice: connect to uploading server, to get the first slice uploading point. 4. upload_slice: connect to uploading server, upload one slice of data, and get the next slice uploading point. 5. check: connect to uploading server, to check whether or not the file uploading process accomplished. the result is descripted as blow:

1. uploading: 2 difference situations:
   • 1. if check returned 4
   • new_slice
   • upload_slice
   • 1. if check returned 2 or 3, wait a while (e.g. 60 seconds) and then call check again.
2. commit: connect to upload API server, call commit with the upload_token and server_uri as parameters to confirm the uploading process is totally accomplished. ## API Description

login

login to get access_token (clients of normal level), upload videos to the account. clients of partner level get access_token

token_refresh

This token should be used to refresh the access token when the old access token expired, to avoid every day login.

• Interface

 POST  https://openapi.youku.com/v2/oauth2/token  

• Parameters
  • client_id: string. MUST provide. Application key.
  • client_secret: string. MUST provide. Application secret.
  • grant_type: string. MUST provide. Authenticate type. For refreshing token, “refresh_token” is the only valid value.
  • refresh_token: string. MUST NOT be empty. Returned by previous login call, to refresh to get new access token.
• Return Value
  • access_token: string. MUST NOT be empty. the new access token to call other API.
  • expires_in: int. MUST NOT be empty. the expire time of the access token, in sencond.
  • refresh_token: string. MUST NOT be empty. the token to refresh to get new access token.
  • token_type: string. MUST NOT be empty. how to access resources using access token. default is bearer.
• Error Codes
  • 1007 - Null Access token
  • 1008 - Invalid Access token
  • 1009 - Expired Access token, refresh needed
  • 130011201 - Necessary parameter for OAuth2 missing.
  • 130011202 - Unsupported grant type.
  • 130011203 - Unsupported request HTTP method by authorization server.
  • 130011204 - Unknown authorization server error.
  • 130011205 - Non-authorized authorization grant type for this client.
  • 130011206 - Access permission denied.
  • 130011207 - Invalid grant or invalid refresh_token for token_refresh. In the latter case, the caller should call login then to login again.
  • 130011208 - Invalid client, failed to authenticate.
  • 130011209 - Invalid scope.
  • See #Error Definition for full list of error definitions.
• Sample

 POST /v2/oauth2/token Host: openapi.youku.com

client_id=123 &client_secret=demo_secret &grant_type=refresh_token &refresh_token=4bda296b570a6bba6ff02944cf10d13f

200 OK { “access_token”:”11d0b7627154f0dd000e6084f3811598”, “expires_in”:”3600”, “refresh_token”:”4bda296b570a6bba6ff02944cf10d13f”, “token_type”: “bearer” } 

show_basic

This API is used to get the video clip’s info, including its state..

• Interface

 GET https://openapi.youku.com/v2/videos/show_basic.json 

• Parameters
  • client_id: string. MUST provide. Application key. video_id: string. MUST provide.
• Return Value
  • id: string. The encoded video id of the video clip.
  • title: string.
  • link: string, The URL of the video web page.
  • thumbnail: string, The thumb nail image URL of the video. duration: int. The duration of the video in second. category: string.
  • state: string. The state of the video.
  • normal: The video clip is OK to play.
  • encoding: The video clip is in encoding to suitable formats for play in the video player. fail: Encoding failed.
  • in_review: The video clip is in reviewing.
  • blocked: The video clip is blocked for some reason.
  • published: string. publishing time
  • description: string.
  • player: string. The URL of the individual player for the video clip.
  • public_type:
  • ‘all’: no limit to be access.
  • ‘friend’: only accessable to friends.
  • ‘password’: password protected.
  • copyright_type:
  • ‘original’
  • ‘reproduced ‘
  • user: object.
  • id: int. The video clip owner’s user ID.
  • name: string. The video clip owner’s user name.
  • link: string. The video clip owner’s user space URL.
• Error Codes
  • 120020001 - The video clip does not exist.
  • See #Error Definition for full list of error definitions.
• Sample (for demo only; layout for ease of reading)

 GET /v2/videos/show_basic.json?client_id=123&video_id=XMjg1MTcyNDQ0 Host: openapi.youku.com —-

200 OK

{ “id”: “XMjg1MTcyNDQ0”, “title”: “demo user”, “link”: “http://v.youku.com/v_show/id_XMjg1MTcyNDQ0.htm”, “thumbnail”: “http://g4.ykimg.com/0100641F464E1FC”, “duration”: “910”, “category”: “original”, “state”: “normal”, “published”: “2011-07-15 09:00:42”, “description”: “demo description”, “player”: “http://player.youku.com/player.php/sid/XMjg1MTcyNDQ0/v.swf”, “public_type”: “all”, “copyright_type”: “original”, “user”: { “id”: 58921428, “name”: “demo user”, “link”: “http://u.youku.com/user_show/id_UMjM1Njg1NzEy.html” } } 

create

• Interface

 GET https://api.youku.com/uploads/create.json

• Parameters
  • access_token: string, MUST provide. Access token
  • client_id: string. MUST provide. Application key.
  • title: string, MUST provide. title of the video clip, which is limited to 2 to 50 english characters long, and MUST contains one letter at least.
  • tags: string, default is the client name string. tags of the video clip, comma (‘,’) seperated. limit: 2-6 Chinese characters or 2-12 English characters, and max up to 10 tags.
  • category: string, Optional. Specific category see schemas/video/category.
  • public_type: string, default is ‘all’.
  • ‘all’: no limit to be access.
  • ‘friend’: only accessable to friends.
  • ‘password’: password protected.
  • copyright_type: string, default is ‘original’.
  • ‘original’
  • ‘reproduced ‘
  • watch_password: string, the plain text password string when public_type is ‘password_protected’. default is empty string (“”).
  • description: string, default is empty string (“”). 2000 characters limited at most.
  • file_md5: string, MUST provide.
  • file_name: string, MUST provide.
  • file_size: int, MUST provide. the file size in byte.
  • latitude: double. Optional.
  • longitude: double. Optional.
  • shoot_time: double, in seconds. Optional.
• Return Value
  • error: object. Only returned when error occured. code: int.
  • type: string.
  • description: string.
  • upload_token: string, the upload process token to do folloing steps.
  • instant_upload_ok: string, “yes” or “no”. Indicate if Instant Uploading process is available.
  • upload_server_uri: string. Only returned when instant_upload_ok is “no”. The client SHOULD resolve the hostname to IP address and remember for following steps.
• Error Codes
  • 120010101 - Title cannot be empty
  • 120010102 - Title cannot be more than 60 characters long (updated)
  • 120010104 - Banned content in title
  • 120010111 - Duplicated uploading by the same user
  • 120010121 - Tags must not be empty
  • 120010122 - More than 10 tags specified
  • 120010123 - Sensitive words in tags
  • 120010124 - Tag is less than 2 letters (updated)
  • 120010125 - Tag is longer than 12 letters (updated)
  • 120010141 - Banned content in description
  • 120010142 - Discription too long (new)
  • See #Error Definition for full list of error definitions.
• Sample (for demo only; layout for ease of reading)

 GET /v2/uploads/create.json? client_id=123 &access_token=demo_access_token &title=demo%20video &tags=demo &public_type=password_protected ©right_type=original &watch_password=demopassword &description=this%20is%20a%20demo &file_md5=00000000000000000000000000 &file_name=demo.avi &file_size=123456 &latitude=39.980572 &longitude=116.307289

Host: openapi.youku.com

201 Created

{ “upload_token”: “1a2b3c4d”, “instant_upload_ok”: “no”, “upload_server_uri”: “g01.upload.youku.com” } 

upload

The sub-process of file uploading is devided into several steps descripted below.

The uploading server is resolved by DNS server according to the location of the user, and the IP address of the server MUST be recorded locally by the client to connect to perform all of the following steps of uploading phase.http://gX.upload.youku.com/gupload should be replaced by http://214.54.36.57/gupload“214.54.36.57” is “gX.upload.youku.com” pinged from your local address.

commit

• Interface

 POST https://api.youku.com/uploads/commit.json 

• Parameters
  • access_token: string, MUST provide.
  • client_id: string. MUST provide. Application key.
  • upload_token: string, MUST provide.
  • upload_server_ip: string, default is empty string (“”). Returned by calling #check from uploading server. If it’sInstant Uploading, using empty string (“”).
• Return Value
  • error: object. Only returned when error occured.
  • code: int.
  • type: string.
  • description: string.
  • video_id: string
• Error Codes
  • 120010151 - Invalid upload task
  • 120010152 - Insert video metainfo error
  • See #Error Definition for full list of error definitions.
• Sample (for demo only; layout for ease of reading)

 POST /v2/uploads/commit.json Host: openapi.youku.com

client_id=123&access_token=demo_access_token&upload_token=1a2b3c4d&upload_server_ip=1.2.3.4

200 OK

{ “video_id”: “XMjg1MTcyNDQ0” } 

cancel

Cancel current upload session, including slice uploading tasks.

• Interface

 GET https://openapi.youku.com/v2/uploads/cancel.json 

• Parameters
  • access_token: string, MUST provide.
  • client_id: string. MUST provide. Application key.
  • upload_token: string, MUST provide.
  • upload_server_ip: string, default is empty string (“”). returned by #check call previously.
• Return Value
  • error: object. Only returned when error occured.
  • code: int.
  • type: string.
  • description: string.
  • upload_token: string.
• Error Codes
  • See #Error Definition for full list of error definitions.
• Sample (for demo only; layout for ease of reading)

 GET /v2/uploads/cancel.json?client_id=123&access_token=demo_access_token Host: openapi.youku.com

200 OK

{ “upload_token”: “1a2b3c4d” } 

spec

Get the uploading configuration specification.

• Interface

 GET https://openapi.youku.com/v2/schemas/upload/spec.json 

• Parameters
  • None
• Return Value
  • error: object. Only returned when error occured.
  • code: int.
  • type: string.
  • description: string.
  • allowed_max_file_size: int. In bytes.
  • allowed_extensions: string. Comma seperated file extensions.
• Error Codes
  • None
  • See #Error Definition for full list of error definitions.
• Sample (for demo only; layout for ease of reading)

 GET /v2/schemas/upload/spec.json Host: openapi.youku.com

200 OK

{ “allowed_max_file_size”: 20480000, “allowed_extensions”: “wmv,avi,dat,asf” }